Metadata-Version: 2.4
Name: devpilot-ai
Version: 0.2.0
Summary: Dev server supervisor for AI coders
Project-URL: Homepage, https://github.com/benzsevern/devpilot
Project-URL: Repository, https://github.com/benzsevern/devpilot
Project-URL: Issues, https://github.com/benzsevern/devpilot/issues
Author-email: Ben Severn <benzsevern@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,claude,copilot,cursor,dev-server,hot-reload,process-manager,supervisor
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: filelock>=3.13
Requires-Dist: httpx>=0.27
Requires-Dist: psutil>=5.9
Requires-Dist: pyyaml>=6.0
Requires-Dist: watchdog>=4.0
Provides-Extra: dev
Requires-Dist: pytest-timeout>=2.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp[cli]>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# 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

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

Or with pipx for global CLI use:

```bash
pipx install devpilot
```

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

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

```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"]:
        # 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
