PortScope

Real-time Port Visibility for Developers

A Windows desktop application that provides developers with real-time visibility, monitoring, and historical insights into local network ports. Built with a dashboard-first approach that interprets data, not just displays it.

🎯 What Makes PortScope Different

Unlike Task Manager or system utilities, PortScope is built specifically for developers:

• Dashboard-First Design - Live summary cards, insights, and visual indicators
• Developer-Centric - Columns ordered by relevance (Port → Type → Owner → Runtime)
• Intelligent Interpretation - Explains what's happening, not just raw data
• Signature Scope Indicator - Animated radar showing scan status and conflicts
• Identity Panel - Left sidebar with branding and live statistics
• Real-time Notifications - System tray alerts for port changes and conflicts
• Detailed Port Inspector - Double-click any port for comprehensive information
• Theme Toggle - Switch between light and dark themes instantly

✨ Key Features

Core Monitoring

• ✅ Real-time TCP/UDP port scanning
• ✅ Auto-refresh with configurable intervals (1-60 seconds)
• ✅ Color-coded port types (Dev/System/Docker/Other)
• ✅ Process name, PID, and status display
• ✅ Docker container name mapping

Visual Dashboard

• ✅ Left sidebar with live statistics
• ✅ Summary cards showing key metrics
• ✅ Animated scope indicator (signature element)
• ✅ Live insight bar with interpreted data
• ✅ Port usage chart over time

Intelligence & Insights

• ✅ Port conflict detection with alerts
• ✅ New port/closed port notifications
• ✅ Developer-first column ordering
• ✅ Simplified owner names (Python, Node.js, Docker, etc.)
• ✅ Usage recommendations per port type

Data Management

• ✅ SQLite historical tracking
• ✅ Export to CSV with timestamps
• ✅ History viewer dialog
• ✅ Configurable data retention (1-90 days)

User Experience

• ✅ Light and dark theme support
• ✅ System tray integration
• ✅ Scrollable content area
• ✅ Double-click for port details
• ✅ Search and filter functionality
• ✅ Admin mode detection

🚀 Quick Start

Setup

# Create virtual environment
python -m venv venv

# Activate (Windows)
venv\Scripts\activate

# Install dependencies
pip install pyqt6
pip install psutil

Run

python main.py

Optional: Run as Administrator

For full port visibility, right-click and "Run as Administrator"

🎨 Professional UI

┌───────────┬────────────────────────────────────┐
│  🧭       │  🔄 Live Monitoring                │
│ PortScope │  Real-time port activity           │
│───────────│  ──────────────────────────────    │
│ 📊 132    │  [🟢 Dev] [🔴 Sys] [🟣 Doc] [⚠️]  │
│ Active    │  ──────────────────────────────    │
│───────────│  🔍 Search...  [↻] [📤]           │
│ 🟢 19     │  ──────────────────────────────    │
│ Dev       │  🟢 19 Dev ports | 🐳 0 Docker     │
│───────────│  ──────────────────────────────    │
│ 🐳 0      │  [Chart: Active Ports Over Time]   │
│ Docker    │  ──────────────────────────────    │
│───────────│  PORT│TYPE│OWNER│RUNTIME│STATUS    │
│ ⚠️ 16     │  3000│Dev │Node │node.exe│LISTEN   │
│ Conflicts │  8080│Dev │Python│python.exe│...   │
│───────────│  5432│Sys │Postgres│postgres...   │
│ 📊 History│                                    │
│ ⚙️ Settings│                                   │
│ 🌙 Dark   │                                    │
└───────────┴────────────────────────────────────┘

🔧 Features in Detail

Port Detail Inspector

Double-click any port to see:

• Basic information (port, protocol, status, type)
• Process details (name, PID, executable path, user)
• Full command line
• Docker container info (if applicable)
• Usage recommendations

Smart Notifications

Get notified about:

• New ports opened
• Ports closed
• Port conflicts detected
• Configurable in settings

Theme Support

• Dark Theme: Professional dark slate with vibrant accents
• Light Theme: Clean white background with adjusted colors
• Toggle instantly with sidebar button

Port Categorization

• 🟢 Dev Ports (3000-9999): Green - Safe for development
• 🔴 System Ports (1-1023): Red - Reserved system ports
• 🟣 Docker Ports: Purple - Docker-managed
• 🔵 Other Ports: Blue - Unknown/Other services

📊 Architecture

portscope/
├── ui/                    # UI components
│   ├── main_window.py     # Main application window
│   ├── sidebar.py         # Left identity panel
│   ├── summary_cards.py   # Metric cards
│   ├── insight_bar.py     # Live insights
│   ├── scope_indicator.py # Animated radar
│   ├── chart_widget.py    # Port usage chart
│   ├── port_detail_dialog.py # Detail inspector
│   ├── history_dialog.py  # History viewer
│   ├── settings_dialog.py # Settings panel
│   └── theme.py           # Theme configuration
├── services/              # Business logic
│   ├── port_scanner.py    # Port scanning
│   ├── database.py        # Historical storage
│   ├── docker_service.py  # Docker integration
│   ├── system_service.py  # System utilities
│   ├── port_monitor.py    # Change detection
│   └── notification_service.py # Notifications
├── core/                  # Core business logic
├── images/                # Assets
│   └── logo.png          # Application logo
└── main.py               # Entry point

🎯 Use Cases

1. Identify Port Conflicts - Quickly see which process is using a port
2. Monitor Dev Servers - Track your development environment ports
3. Docker Debugging - See which containers are exposing ports
4. Historical Analysis - Review port usage patterns over time
5. System Monitoring - Keep an eye on system services

🔐 Security & Privacy

• Local Only: All data stays on your machine
• No Network Calls: No external connections
• SQLite Storage: Local database file
• Open Source: Fully transparent code

📝 Requirements

• Windows 10+
• Python 3.10+
• PyQt6
• psutil

🤝 Contributing

This is an open-source project. Contributions are welcome!

See AGENTS.md for development guidelines.

📄 License

Open Source

---

Built with ❤️ for developers who need real-time port visibility