Dev Process Tracker - Quick Start Guide

What is Dev Process Tracker?

Dev Process Tracker is a macOS CLI tool that helps you discover, track, and manage local development servers and ports. It answers three key questions:

What servers are running? - Lists all TCP listening ports on your machine
Which project owns each server? - Associates ports with their project roots
Who started each server? - Detects if an AI agent started the server

Installation

Build from source:

cd ~/path/to/dev-process-tracker
go build -o devpt ./cmd/devpt/main.go

Optionally install to PATH:

sudo mv devpt /usr/local/bin/devpt

Then use from anywhere:

devpt ls

First Steps

See what's currently running

devpt ls

Shows all discovered listening ports with their PID, project, and source.

Register a service you manage

devpt add myapp ~/myapp "npm start" 3000

This stores myapp in your registry so you can control it with devpt.

List with details

devpt ls --details

Shows the full command that each process is running.

Check your registered services

cat ~/.config/devpt/registry.json

Your services are stored here and can be edited manually.

Common Workflows

Start a managed service

devpt start myapp

Logs are captured to: ~/.config/devpt/logs/myapp/<timestamp>.log

Stop a service by name

devpt stop myapp

Stop a service by port

devpt stop --port 3000

Restart a service

devpt restart myapp

View logs

devpt logs myapp
devpt logs myapp --lines 100

Key Concepts

Server Sources

Each server is tagged with a source:

manual - Running but not in your managed registry
managed - In your registry (may or may not be running)
agent:xxx - Started by an AI coding agent

Project Detection

Dev Process Tracker walks up the directory tree looking for:

.git (Git repos)
package.json (Node.js)
go.mod (Go)
Gemfile (Ruby)
composer.json (PHP)
And more...

Agent Detection

Detects servers likely started by:

OpenCode
Cursor
Claude
Gemini
Copilot

Uses heuristics like parent process name, TTY attachment, and environment variables.

File Locations

~/.config/devpt/
├── registry.json          # Your managed services
└── logs/
    ├── myapp/
    │   ├── 2026-02-09T16-00-01.log
    │   └── 2026-02-09T16-05-30.log
    └── otherapp/
        └── 2026-02-09T16-10-00.log

Tips & Tricks

Edit registry manually - ~/.config/devpt/registry.json is just JSON
Check what's using a port - devpt ls --details | grep :3000
Find projects - devpt ls | grep "my-project"
See processes without names - devpt ls --details | grep -v "^-"

Troubleshooting

"lsof: command not found"

brew install lsof

Registry file seems broken

rm ~/.config/devpt/registry.json
# It will be recreated next time you add a service

Process won't stop

# Find the PID
devpt ls | grep myapp

# Force kill it (use carefully!)
kill -9 <PID>

Performance

devpt ls typically completes in 1-2 seconds
No background daemon (everything is on-demand)
Results are fresh on each run

What's Next?

Register your frequently-used dev servers
Check the README.md for full documentation
Explore the --details flag to see more info
Set up the servers you manage with devpt add

Need Help?

devpt help
devpt ls --help
devpt add --help

Or see the full README.md for detailed documentation.

FilesExpand file tree

QUICKSTART.md

Latest commit

History