# 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:**
```bash
pip install "devpilot-ai[mcp]"
claude mcp add devpilot -- devpilot-mcp
```

**Cursor / VS Code / other MCP clients:**
```json
{
  "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](https://smithery.ai/server/benzsevern/devpilot) exists for discovery and documentation — actual usage requires the local server.

### CLI

```bash
pip install devpilot-ai
```

Or with pipx for global CLI use:

```bash
pipx install devpilot-ai
```

## Quick Start

### Auto-detect and configure your project

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

```bash
devpilot run api "uvicorn main:app --reload --port 8000"
```

### Or attach to an already-running server

```bash
devpilot attach api --port 8000
```

### Check what happened after editing a file

```bash
devpilot changed src/main.py
```

Returns structured JSON:

```json
[{
  "service": "api",
  "reload": "reloaded",
  "reload_time_ms": 340,
  "healthy": true,
  "response_time_ms": 12
}]
```

### Manage everything at once

```bash
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](https://modelcontextprotocol.io/), 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](#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):

```yaml
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:

```python
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](https://pypi.org/project/devpilot-ai/)
- [Smithery](https://smithery.ai/server/benzsevern/devpilot) (discovery and docs)

## License

MIT