devpilot
Dev server supervisor for AI coders.
AI coding agents (Claude Code, Cursor, Copilot) break dev servers constantly — editing files mid-reload, causing port conflicts, spawning zombie processes. Then they panic: kill random PIDs, rotate ports, nuke all Python processes. It gets worse.
devpilot gives AI coders structured, reliable process awareness. It manages dev server lifecycles, detects reloads, checks health, and returns JSON that AI can parse and act on — so the panic cycle never starts.
Install
MCP Server (recommended for AI tools)
DevPilot runs as a local MCP server because it needs direct access to your machine's processes, ports, and filesystem. Install once, and every AI session has the tools available.
Claude Code:
pip install "devpilot-ai[mcp]"
claude mcp add devpilot -- devpilot-mcp
Cursor / VS Code / other MCP clients:
{
"mcpServers": {
"devpilot": {
"command": "devpilot-mcp"
}
}
}
Why local, not remote? DevPilot spawns processes, reads stdout, checks localhost ports, and manages PIDs on your machine. A remote server can't do any of that. The Smithery listing exists for discovery and documentation — actual usage requires the local server.
CLI
pip install devpilot-ai
Or with pipx for global CLI use:
pipx install devpilot-ai
Quick Start
Auto-detect and configure your project
devpilot init
Scans for pyproject.toml, requirements.txt, package.json and generates .devpilot.yaml with the right framework profiles.
Start your dev server under devpilot
devpilot run api "uvicorn main:app --reload --port 8000"
Or attach to an already-running server
devpilot attach api --port 8000
Check what happened after editing a file
devpilot changed src/main.py
Returns structured JSON:
[{
"service": "api",
"reload": "reloaded",
"reload_time_ms": 340,
"healthy": true,
"response_time_ms": 12
}]
Manage everything at once
devpilot up # start all services from .devpilot.yaml
devpilot down # stop all services
devpilot status # health check everything
Why This Exists
When an AI coder edits your code, the dev server reloads. But the AI has no way to know:
- Did the reload succeed or crash?
- Is the server healthy?
- Which service was affected by that file change?
- Should it wait, retry, or escalate?
Without answers, AI coders guess. They kill processes they shouldn't, rotate ports randomly, and create cascading failures. devpilot closes this feedback loop with structured, reliable signals.
How It Works
Two modes:
- Managed (
devpilot run) — devpilot spawns the process, captures stdout, detects reload patterns, owns the full lifecycle
- Attached (
devpilot attach) — devpilot monitors an existing process by port, health-check only, never kills what it didn't start
Three recovery tiers:
| Tier | Action | Example |
|---|
| Silent | Auto-restart with backoff | Process crashed, retry up to 3x |
| Report | Auto-recover + notify | Repeated crashes, port reassignment |
| Escalate | Report only, never act | Unknown process on port, code errors |
Core principle: devpilot never rotates ports randomly, never kills processes it didn't start, never nukes all Python tasks.
MCP Server
DevPilot exposes 10 tools via the Model Context Protocol, making it natively accessible to any MCP-compatible AI client.
| Tool | Description |
|---|
devpilot_status | Health check services |
devpilot_changed | Report file edit, get reload + health result |
devpilot_run | Start a managed service |
devpilot_attach | Monitor an existing service |
devpilot_stop | Stop managed services |
devpilot_init | Auto-detect project and generate config |
devpilot_up | Start all services from config |
devpilot_log | View events and recovery actions |
devpilot_cleanup | Remove stale state |
devpilot_health_check | Direct port health check |
The MCP server runs locally via stdio — it needs direct access to your machine's processes and ports. See Install for setup.
Built-in Framework Profiles
| Framework | Detection | Default Port |
|---|
| FastAPI/Uvicorn | uvicorn in command | 8000 |
| Flask | flask in command | 5000 |
| Django | manage.py runserver | 8000 |
| Vite | vite in command | 5173 |
| Next.js | next dev in command | 3000 |
| Create React App | react-scripts start | 3000 |
Custom frameworks can be added in .devpilot.yaml.
Configuration
.devpilot.yaml (generated by devpilot init or written manually):
services:
api:
cmd: "uvicorn main:app --reload --port 8000"
port: 8000
health: /health
file_patterns:
- "src/**/*.py"
reload_patterns:
- "Reloading..."
frontend:
cmd: "npm run dev"
port: 3000
file_patterns:
- "src/**/*.tsx"
- "src/**/*.css"
recovery:
max_retries: 3
backoff_seconds: [1, 3, 5]
auto_port_reassign: true
All Commands
| Command | Description |
|---|
devpilot init | Auto-detect project and generate .devpilot.yaml |
devpilot run <name> <cmd> | Start a managed service |
devpilot attach <name> --port N | Monitor an existing service |
devpilot status [name] | Health check one or all services |
devpilot changed <filepath> | Report file change, get reload/health result |
devpilot stop [name] [--all] | Stop managed services |
devpilot restart <name> | Restart a managed service |
devpilot log [name] | Show recent events |
devpilot cleanup | Remove stale state and dead PIDs |
devpilot up | Start all services from config |
devpilot down | Stop all services |
Every command returns structured JSON to stdout with exit codes 0 (success), 1 (all failed), or 2 (partial).
For AI Tool Authors
devpilot is designed to be called programmatically. The MCP server is the recommended integration path, but the CLI also works:
import subprocess, json
result = subprocess.run(
["devpilot", "changed", "src/main.py"],
capture_output=True, text=True
)
changes = json.loads(result.stdout)
for svc in changes:
if not svc["healthy"]:
if svc["reload"] == "reload_failed":
print(f"Code error in {svc['service']}: {svc.get('error')}")
elif svc["reload"] == "timeout":
print(f"Reload slow for {svc['service']}, waiting...")
Requirements
- Python 3.10+
- Works on Windows, macOS, and Linux
Links
License
MIT
