VSCode Port Monitor

A VS Code extension for real-time monitoring of multiple host and port statuses in the status bar.
Features intelligent configuration processing that automatically handles simple arrays, complex grouped configurations, well-known port names, and port ranges.
✨ Key Features
- 🔍 Multi-host & multi-port monitoring with zero external dependencies
- 🏷️ Intelligent configuration processing (5-step automatic transformation)
- 📊 Real-time status display (live status bar monitoring)
- 🌐 Well-known port support (http, https, ssh, postgresql, etc.)
- 📈 Port range expansion ("3000-3009" → individual ports)
- 🎯 Smart defaults (Node.js development ports: 3000-3003)
- 🛑 Process management (kill processes using ports with server/client detection)
- 📺 Interactive process viewer (clickable status bar with process selection)
- 🎨 Customizable display (icons, colors, intervals)
- 📍 Status bar positioning (left or right alignment)
- 🚨 Smart error detection (detailed configuration validation)
- 💡 Helpful error messages (specific fix suggestions)
📸 Screenshots
localhost: 300[🟢user:0|⚪️car:1|⚪️2|⚪️3|🟢4]
db-server.local: [⚪️postgresql:5432]
api-server: [🟢9000|⚪️9001]
🚀 Quick Start
1. Installation
Install "Port Monitor" from the VS Code extension marketplace.
This extension supports multiple configuration formats that are automatically processed:
{
"portMonitor.hosts": {
"Next.js": [3000, 3001, "3002-3009"]
}
}
{
"portMonitor.hosts": {
"Development": ["3000-3003"],
"Production": {
"8080-8090": ""
}
}
}
{
"portMonitor.hosts": {
"Next.js": {
"3000": "app",
"3001": "api",
"3002": "etc",
"3003": "etc",
"3004": "etc",
"3005": "etc",
"3006": "etc",
"3007": "etc",
"3008": "etc",
"3009": "etc",
"__CONFIG": {
"compact": true,
"show_title": true
}
},
"Web Services": {
"80": "http",
"443": "https"
},
"Server Services": {
"22": "ssh",
"5432": "postgresql"
},
"Development": {
"8080": "main",
"8081": "alt",
"8082": "alt",
"8083": "alt",
"8084": "alt",
"8085": "alt",
"8086": "alt",
"8087": "alt",
"8088": "alt",
"8089": "alt",
"8090": "alt"
}
}
}
Well-Known Port Names
{
"portMonitor.hosts": {
"Web Services": ["http", "https", "ssh"],
"Database": ["postgresql", "mysql", "redis"]
}
}
3. See Results
Results are displayed in the status bar like [🟢admin:3000|🟢app:3001|⚪️user:3002]
.
- 🟢 = Port is open (service running)
- ⚪️ = Port is closed (service stopped)
📋 Configuration Examples
Automatic Configuration Processing
The extension uses a 5-step intelligent processing system:
- Well-known ports replacement:
"http"
→ 80
, "https"
→ 443
, etc.
- Port range expansion:
"3002-3009"
→ individual ports 3002, 3003, 3004...
- Default group wrapper: Simple arrays get wrapped in
"__NOTITLE"
group
- Array to object conversion:
[3000, 3001]
→ {"3000": "", "3001": ""}
- Structure normalization: Clean and validate final configuration format
Multiple Services with __CONFIG
{
"portMonitor.hosts": {
"Frontend": {
"3000": "frontend",
"3001": "backend",
"__CONFIG": {
"compact": true,
"bgcolor": "blue",
"show_title": true
}
},
"Database": {
"5432": "postgres",
"6379": "redis",
"__CONFIG": {
"compact": false,
"bgcolor": "yellow"
}
}
},
"portMonitor.backgroundColor": "statusBarItem.warningBackground"
}
Mixed Configuration with Well-Known Ports
{
"portMonitor.hosts": {
"Development": ["3000-3009", "8080"],
"Web Services": ["http", "https"],
"Server Services": ["ssh", "postgresql"]
}
}
Pattern Match Labels (Advanced)
{
"portMonitor.hosts": {
"Development": ["3000-3009", "8080"]
},
"portMonitor.portLabels": {
"3000": "main-app", // 3000 only
"300*": "dev-env", // 3001-3009
"8080": "proxy", // 8080
"*": "service" // others
}
}
Custom Icons
{
"portMonitor.statusIcons": {
"free": "⚪️",
"inUse": "🟢"
}
}
Development Environment Example
{
"portMonitor.hosts": {
"Frontend": {
"3000": "react",
"6006": "storybook",
"8080": "webpack",
"__CONFIG": {
"compact": true,
"separator": " | "
}
},
"Backend": {
"3001": "node",
"3002": "api"
}
}
}
※ Click status bar display → "Kill Process" to terminate process using the port
Interactive Process Management
Click the status bar to open the port selector and manage processes:
- Port Selection: Choose from monitored ports with real-time status
- Process Details: View detailed process information and command lines
- Smart Process Detection: Automatically prioritizes server processes over client processes (e.g., Node.js server vs. Chrome browser)
- Multiple Process Handling: When multiple processes use the same port, select the specific one to manage
- Process Termination: Safely kill processes with confirmation dialogs
Usage:
- Click status bar → Select port → Choose action:
- View Details: See comprehensive process information
- Select Process: Choose from multiple processes (if available)
- Kill Process: Terminate the selected process
Process Prioritization:
- Server processes (Node.js, Python, etc.) are automatically selected over client processes (browsers)
- Multiple processes are clearly labeled as
[SERVER]
or [CLIENT]
- Process count is shown when multiple processes exist:
(node - PID: 1234) [2 processes]
⚙️ Configuration Options
Setting Key |
Description |
Default |
portMonitor.hosts |
Monitored host and port targets (supports multiple formats) |
{} |
portMonitor.portLabels |
Port labels (patterns supported for advanced labeling) |
{} |
portMonitor.portEmojis |
Custom emojis for specific port labels |
{} |
portMonitor.emojiMode |
How to display port emojis (prefix/replace/suffix) |
"replace" |
portMonitor.statusIcons |
Status icon settings |
{ "inUse": "🟢", "free": "⚪️" } |
portMonitor.backgroundColor |
Status bar background color (VS Code theme colors only) |
none |
portMonitor.intervalMs |
Monitoring interval (ms, minimum 1000) |
3000 |
portMonitor.statusBarPosition |
Status bar position ("left" or "right") |
"right" |
portMonitor.displayOptions.separator |
Port separator character |
"|" |
portMonitor.displayOptions.showFullPortNumber |
Show full port numbers |
false |
portMonitor.enableProcessKill |
Enable process kill feature |
true |
portMonitor.enableLogViewer |
Enable log viewer |
true |
Port Specification Methods
- Number:
3000
- Range:
"3000-3009"
- Well-known port names:
"http"
, "https"
, "ssh"
, "postgresql"
, etc.
Configuration Processing Features
- Automatic well-known port resolution:
"http"
, "https"
, "ssh"
, "postgresql"
, etc.
- Port range expansion:
"3000-3009"
automatically expands to individual ports
- Smart grouping: Simple arrays automatically get grouped for better organization
- Flexible input formats: Arrays, objects, mixed configurations all supported
Background Color Configuration
Background colors can be set at two levels:
- Group-level: Use
__CONFIG.bgcolor
within a group (highest priority)
- Global-level: Use
portMonitor.backgroundColor
setting
Available background colors:
- Simple names:
"red"
, "yellow"
, "blue"
, "green"
- VS Code theme colors:
"statusBarItem.errorBackground"
, "statusBarItem.warningBackground"
, "statusBarItem.prominentBackground"
, "statusBarItem.remoteBackground"
portLabels Pattern Examples (Advanced)
"3000"
- Exact match
"300*"
- Prefix match (3000, 3001, ...)
"*80"
- Suffix match (80, 8080, ...)
"30?0"
- Single character wildcard (3000, 3010, ...)
"*"
- All (lowest priority)
📝 Configuration Examples
Custom Port Emojis
{
"portMonitor.portEmojis": {
"car": "🚗", // Simple format
"user": { "prefix": "🙂" } // Individual mode
}
}
Display: 🚗car:3000 🙂🟢user:3001
Comprehensive examples and advanced configurations: docs/SETTING_SAMPLES.md
🔧 Configuration Error Detection
The extension provides detailed error detection and helpful fix suggestions for common configuration mistakes:
Common Configuration Errors
1. Reversed Port-Label Configuration
❌ Incorrect:
{
"portMonitor.hosts": {
"localhost": {
"user": 3000,
"car": 3001
}
}
}
✅ Correct:
{
"portMonitor.hosts": {
"localhost": {
"3000": "user",
"3001": "car"
}
}
}
2. Empty Host Name
❌ Incorrect:
{
"portMonitor.hosts": {
"": {
"3000": "app"
}
}
}
✅ Correct:
{
"portMonitor.hosts": {
"localhost": {
"3000": "app"
}
}
}
3. Host Name as Port Number
❌ Incorrect:
{
"portMonitor.hosts": {
"3000": {
"app": "label"
}
}
}
✅ Correct:
{
"portMonitor.hosts": {
"localhost": {
"3000": "app"
}
}
}
Error Messages
When configuration errors are detected, the extension shows:
- Status Bar: "Port Monitor: Configuration Error"
- Tooltip: Detailed error messages with fix suggestions
- Example:
Port numbers should be keys, not values. Current: {"user": 3000} Correct: {"3000": "user"}
Status Bar Position
You can configure the status bar position:
{
"portMonitor.statusBarPosition": "left" // or "right" (default)
}
※ All configuration formats are automatically processed and normalized internally for consistent behavior.
📚 Rich Configuration Examples
For more configuration examples for various development environments, see:
Supported development environments include:
- Frontend: Next.js, React, Vue.js, Angular, Svelte
- Backend: Express, NestJS, Django, Flask, Spring Boot
- Database: PostgreSQL, MySQL, MongoDB, Redis
- Architecture: Microservices, Full-stack, JAMstack
- Use Cases: E-commerce, SaaS, Mobile, AI/ML, Games
Requirements
- Node.js 14.x or higher
- VS Code 1.60.0 or higher
Local Development
# Clone repository
git clone https://github.com/dkurokawa/vscode-port-monitor.git
cd vscode-port-monitor
# Install dependencies
npm install
# Build for development
npm run compile
# Debug execution
# Press F5 to launch Extension Development Host
🐛 Bug Reports & Feature Requests
For bug reports or feature requests, please create an issue on GitHub Issues.
📄 License
MIT License - See LICENSE file for details.
🤝 Contributing
Pull requests and issues are welcome! See docs/SPECIFICATION.md for details.
Development Status: 🚧 Currently under active development