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:

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.

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

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

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