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

• PyPI
• Smithery (discovery and docs)

License

MIT