Portrm - Stop guessing what's running on your machine.

portrm is a CLI + VS Code extension to see, fix, and control your dev environment ports in seconds. No more lsof commands. No more EADDRINUSE errors. Just a simple, reliable way to keep your dev stack running smoothly.

See every port, kill rogue processes, manage services, and fix conflicts -- all from the VS Code sidebar.

Features

Sidebar Port Dashboard

Instantly see every listening port on your machine with process name, PID, and service status -- no terminal needed.

Project-Aware Service Management

Detects .ptrm.toml in your workspace and shows your services (frontend, backend, database) with live status indicators:

• Running -- green dot
• Stopped -- red dot
• Conflict -- yellow warning

One-Click Actions

Smart Terminal Integration

• Single shared terminal for all actions
• Automatic cleanup when switching between commands
• Interactive TUI support with graceful exit handling

Auto-Install & Update

Extension automatically detects if ptrm CLI is installed. If not, it prompts to download the correct binary for your platform (macOS/Linux/Windows, x64/ARM64) from GitHub releases.

Quick Start

1. Install the extension from the VS Code Marketplace
2. Open a project -- the Ptrm icon appears in the activity bar
3. Click the icon to see all listening ports on your machine
4. (Optional) Run ptrm init to create a .ptrm.toml for service management

Example .ptrm.toml

[project]
name = "my-app"

[services.frontend]
port = 3000
run = "npm run dev"
cwd = "."

[services.api]
port = 8080
run = "cargo run"
cwd = "./api"

[profiles.staging]
frontend = { port = 3100 }
api = { port = 8180 }

Commands

All commands are available via the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) under the Ptrm category:

• Ptrm: Refresh -- Refresh port and service data
• Ptrm: Start All Services -- Start all services from config
• Ptrm: Stop All Services -- Stop all running services
• Ptrm: Kill Process on Port -- Kill a process by port number
• Ptrm: Restart Service -- Restart a specific service
• Ptrm: View Logs -- Show logs for a service or port
• Ptrm: Fix Port Conflicts -- Auto-resolve port conflicts
• Ptrm: Inspect Port -- Deep inspect a specific port
• Ptrm: Watch Port -- Monitor a port for changes
• Ptrm: Doctor -- Run diagnostic checks
• Ptrm: Preflight Check -- Verify ports before launch
• Ptrm: Switch Profile -- Switch port profile (staging, production)
• Ptrm: Reset to Default Profile -- Restore default port config
• Ptrm: Initialize Project -- Create .ptrm.toml in workspace
• Ptrm: Interactive TUI -- Open full terminal interface
• Ptrm: Group by Role -- Group ports by type
• Ptrm: History -- View port usage history
• Ptrm: Scan Dev Ports -- Scan for development servers
• Ptrm: Registry Check -- Check against known services
• Ptrm: CI Check -- Validate for CI/CD
• Ptrm: Update CLI -- Update ptrm to latest version

Settings

Requirements

• ptrm CLI -- automatically installed via the extension, or install manually:

# macOS (Homebrew)
brew install abhishekayu/tap/portrm

# npm (cross-platform)
npm install -g portrm

# From source
cargo install portrm

Supported Platforms

Links

• GitHub Repository
• CLI Documentation
• Report Issues

License

MIT