devvy 0.1.0

Autonomous coding agent CLI — plans, implements, validates, and opens pull requests

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 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 — installed and authenticated with an AI provider
• An Azure DevOps repository

---

Installation

pip install devvy

Or with uv:

uv tool install devvy

---

Setup

1. Install and authenticate opencode

Follow the opencode getting started guide 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.

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

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:

git clone https://github.com/anomalyco/devvy && cd devvy
docker build -f worker.dockerfile -t devvy-worker:latest .

3. Configure devvy

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)

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:

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:

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:

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

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:

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

devvy status <ticket-id>

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

View task logs

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