devpilot-ai 0.1.0

Dev server supervisor for AI coders

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

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:

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.

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:
      - "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

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 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