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

pip install devpilot-ai

Or with pipx for global CLI use:

pipx install devpilot

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.

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:
      - "Started reloading"
      - "Application startup complete"

  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 JSON output and deterministic exit codes make it straightforward to integrate into any AI coding workflow:

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"]:
        # check the reload status before panicking
        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

License

MIT