Metadata-Version: 2.4
Name: devvy
Version: 0.1.0
Summary: Autonomous coding agent CLI — plans, implements, validates, and opens pull requests
Project-URL: Homepage, https://pypi.org/project/devvy/
Author-email: Devvy <nirmalfalzoni@hotmail.co.uk>
License: MIT License
        
        Copyright (c) 2026 Devvy
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai,cli,coding-agent,devops,opencode
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: sqlalchemy>=2.0.45
Requires-Dist: typer[all]>=0.12.0
Description-Content-Type: text/markdown

# devvy

An autonomous coding agent CLI. Give it a task - it plans, implements, validates, and opens a pull request, then responds to review comments until the PR is merged.

Everything runs locally inside Docker containers. No server required.

> **Requires [opencode](https://opencode.ai) and an opencode-compatible AI provider** (e.g. GitHub Copilot, Anthropic, OpenAI). opencode is the AI backbone devvy uses to plan and write code. You must have it installed and authenticated before running devvy.

---

## How devvy works

devvy drives a ticket through a finite state machine. Each state maps to a concrete action:

```
RECEIVED → PREPARE_ENV → PLAN → IMPLEMENT → VALIDATE → CREATE_PR → WAIT_FOR_REVIEW
                                                 ↑                         |
                                                 |    ← RESPOND_TO_REVIEW ←|
                                                 |____________↑____________/
                                              (re-validates after each review response)
```

| State | What happens |
|---|---|
| `RECEIVED` | Validates that a repo URL is present |
| `PREPARE_ENV` | Clones the repo into `~/.devvy/workspaces/<ticket-id>/`, starts a `devvy-worker` container with the workspace bind-mounted |
| `PLAN` | Runs opencode in the container — explores the codebase and produces a detailed implementation plan (no code changes yet) |
| `IMPLEMENT` | Continues the same opencode session — implements the plan, then self-verifies by running the project's own validation scripts inside the container |
| `VALIDATE` | Builds the repo's Docker image and runs its validation scripts (`format.sh`, `code-checks.sh`, `run-tests.sh`). On failure, re-prompts opencode to fix the issues. Up to 3 fix attempts before the ticket is marked `FAILED`. |
| `CREATE_PR` | Pushes the branch to ADO and opens a pull request. If the repo has a PR template (`.azuredevops/pull_request_template.md` or `docs/pull_request_template.md`), opencode fills it in. |
| `WAIT_FOR_REVIEW` | Polls ADO every 30 seconds. On `completed` → `MERGED`. On new review comments → `RESPOND_TO_REVIEW`. |
| `RESPOND_TO_REVIEW` | Re-reads all review threads, prompts opencode to address each one (code changes or a written reply), posts replies back to ADO. If code changed, re-runs `VALIDATE` before returning to `WAIT_FOR_REVIEW`. |
| `MERGED` | Stops the container and deletes the workspace. Done. |
| `FAILED` | Stops the container and deletes the workspace. Error stored in the DB. |

### Validation in detail

devvy does not have a fixed linter/test runner. Instead it looks for three shell scripts **in the repo being worked on**:

| Script | Fatal on failure? |
|---|---|
| `src/scripts/format.sh` | No — runs first; any formatting changes land in the workspace for the next commit |
| `src/scripts/code-checks.sh` | Yes — linting/type-checking |
| `src/scripts/run-tests.sh` | Yes — test suite |

These scripts are run inside a temporary container built from the repo's own `Dockerfile` or `docker-compose.yml`, so the validation environment exactly mirrors production. The container and its image are removed immediately after validation to avoid filling disk.

---

## Requirements

- Python 3.11+
- Docker
- [opencode](https://opencode.ai) — installed and authenticated with an AI provider
- An Azure DevOps repository

---

## Installation

```bash
pip install devvy
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv tool install devvy
```

---

## Setup

### 1. Install and authenticate opencode

Follow the [opencode getting started guide](https://opencode.ai/docs) to install opencode and sign in to your AI provider. devvy mounts your opencode credentials (`~/.local/share/opencode/auth.json`) into the worker container automatically.

```bash
opencode auth login
```

### 2. Build the worker image

The `devvy-worker` Docker image contains git, Node.js 22, and opencode. devvy builds it automatically the first time you run `devvy run` if it isn't already present.

To build it manually in advance (optional):

```bash
docker build -f worker.dockerfile -t devvy-worker:latest .
```

> The `worker.dockerfile` is included in this repository. If you installed devvy via pip, clone the repo first:
> ```bash
> git clone https://github.com/anomalyco/devvy && cd devvy
> docker build -f worker.dockerfile -t devvy-worker:latest .
> ```

### 3. Configure devvy

```bash
devvy init
```

You will be prompted for:

| Prompt | Description |
|---|---|
| Model | Arrow-key picker of 16 GitHub Copilot models (or type any `provider/model` string) |
| Azure DevOps org URL | e.g. `https://dev.azure.com/myorg` |
| Azure DevOps project name | e.g. `MyProject` |
| Azure DevOps personal access token | Needs Code (Read & Write) and Pull Requests (Read & Write) scopes |
| Repository URL | e.g. `https://dev.azure.com/myorg/myproject/_git/myrepo` — used as the default for `devvy run` |
| Path to `.env` file | Optional — copied into each workspace so the validation environment can reach databases, APIs, etc. |

Config is written to `~/.coding-agent.toml` (mode `600`).

---

## Usage

### Run a task (foreground)

```bash
devvy run --title "Fix login bug" --description "Users cannot log in with SSO after the OAuth refactor"
```

Both flags are optional — omit either to be prompted interactively:

```bash
devvy run
```

devvy runs in the foreground, printing each state transition as it progresses. On success it exits 0; on failure it exits 1.

### Run a task in the background

Add `--background` (or `-d`) to detach immediately. The command returns as soon as the ticket is queued:

```bash
devvy run -d --title "Fix login bug" --description "Users can't log in with SSO"
```

Multiple tickets can run in parallel — each gets its own Docker worker container and workspace:

```bash
devvy run -d --title "Add dark mode"    --description "..."
devvy run -d --title "Fix payment bug"  --description "..."
devvy run -d --title "Update README"    --description "..."
```

### List active tickets

```bash
devvy ps
```

Shows all non-terminal tickets with their current state and whether the background process is still running:

```
ID        TITLE              STATE            PROCESS                BRANCH
a1b2c3    Fix login bug      ● VALIDATE        Running  (pid 48291)   agent/a1b2c3
d4e5f6    Add dark mode      ● IMPLEMENT       Running  (pid 48355)   agent/d4e5f6
7g8h9i    Update README      ● CREATE_PR       Idle / resumable       agent/7g8h9i
```

If a ticket shows **Idle / resumable**, use `devvy resume <id>` to continue from where it left off.

### Resume an interrupted task

If devvy is killed mid-run (Ctrl-C, system restart, etc.) the ticket state is preserved in the local database. Resume from where it left off:

```bash
devvy resume <ticket-id>
```

devvy re-attaches to the running container if it is still alive, or spawns a fresh container over the existing workspace directory if not. The cloned repo and any code changes are preserved.

### Check task status

```bash
devvy status <ticket-id>
```

Shows the current FSM state, branch name, PR number, retry count, timestamps, and any error message.

### View task logs

```bash
devvy logs <ticket-id>
```

Renders the full timestamped log for a ticket, grouped by phase.

---

## Storage

All state is stored locally:

| Path | Contents |
|---|---|
| `~/.devvy/devvy.db` | SQLite database — tickets, FSM state, opencode session IDs, PR numbers, logs |
| `~/.devvy/workspaces/<ticket-id>/` | Cloned repo for each active ticket — deleted on `MERGED` or `FAILED` |
| `~/.coding-agent.toml` | devvy config (mode 600) |

### Supported models

Any model that opencode supports can be used. The `devvy init` picker lists 16 GitHub Copilot models. Models from other providers can be typed in manually. The format is `provider/model`, e.g.:

- `github-copilot/claude-sonnet-4.6` (default)
- `github-copilot/gpt-4.1`
- `github-copilot/gemini-2.5-pro`
- `anthropic/claude-opus-4-5`
- `openai/gpt-4o`
