imageAnvil — the system of record for agent teams

Anvil

The system of record for agent teams — durable, evidence-gated, lease-coordinated state for multi-agent software work.

imageLicense: MIT imageVersion imagePyPI imageDocs imageTests

Anvil is a local-first state layer that lets multiple AI coding agents — and the humans working alongside them — execute the same plan without overwriting each other. It records requirements, tasks, claims, and evidence in SQLite, and exposes them through a CLI (anvil) and an MCP server that any harness (Claude Code, Codex, Cursor, Copilot, …) can drive.

Two ideas separate it from an issue tracker:

• Claims are enforced, not conventional. A claim is a database row with a lease and heartbeat — single-winner coordination that holds across sessions, parallel loops, and machines, not "assign a label and hope."
• Status is downstream of proof. Completion is evidence-gated: agents submit typed proofs, reviews gate acceptance, and every accepted task mints a signed, replayable AcceptanceProof you can verify off-host.

Beta — v0.6.13. The core loop is stable and dogfooded; some command surfaces may change before 1.0.

What changed in v0.6.7

• Verified local projection repair — anvil repair projection --yes reconstructs a diverged local projection from immutable event history while retaining an online backup.

• Historical project registration repair — anvil repair project first reports a unanimous immutable PRD-owner decision, then --yes appends one audited current project registration with a backup and replay verification.

• Revision-safe PRDs — review, approval, planning, and new claims bind the exact source revision (#180, #192).

• Transactional Git claims — branch/worktree setup now commits completely or rolls claim state back cleanly (#180).

• Versioned provider reads — bounded project snapshots and PRD content are available without internal-database coupling (#178).

• Safer task routing — PRD scope, strict 1-5 risk ceilings, and actor review history agree across CLI and MCP (#56, #109).

• Faster Windows tests — the maintained parallel suite and focused contract slice run without UAC or junction-dependent collection (#118).

See the v0.6.7 changelog for the complete release-candidate-to-release history and related fixes.

Install

uv tool install anvil-state      # installs the `anvil` CLI + `anvil-mcp` server
anvil install <harness>          # wire anvil into Codex, Cursor, VS Code, …

Python 3.11+ and uv are the only requirements. Upgrading or uninstalling later? See Upgrading and uninstalling.

Other ways to install (Claude Code plugin · one-line script · from source)

As a Claude Code plugin — registers the hooks, MCP server, and agents:

/plugin marketplace add fakoli/anvil
/plugin install anvil@anvil

One-line harness setup (installs anvil-state, then runs anvil install):

curl -fsSL https://raw.githubusercontent.com/fakoli/anvil/main/scripts/install.sh | sh -s -- <harness>

From source:

git clone https://github.com/fakoli/anvil.git && cd anvil/bin
uv sync && uv run anvil --help

For MCP clients without an in-place writer, anvil mcp-config <client> prints a paste-ready config block.

Development

Run the same locked lint gate as CI from the source checkout:

cd bin
uv sync --locked --extra custom
uv run --locked ruff check ..
cd ..
uv run --project bin pytest

Quick start

anvil init --with-sample     # seed a runnable sample project
anvil next                   # → the next ready task, immediately
anvil claim T001             # lease it; a git branch is created for the work
anvil packet T001            # the exact intent, acceptance criteria, and scope
anvil submit T001 --commands "pytest" --files-changed src/foo.py
anvil apply T001 --approve   # evidence-gated → done, with a signed proof

That is the whole loop. The getting-started guide walks through it on your own PRD.

What you get

• A canonical plan, not free-form text. PRDs parse into validated tasks scored across six dimensions (complexity, parallelizability, context load, blast radius, review risk, agent suitability) that drive routing. Optional typed assumptions remain visible through planning and execution, while anvil prd assess gives advisory, testability-focused feedback before design.
• Work packets built for agents. anvil packet T012 renders exact intent, acceptance criteria, and non-goals — no summarizing an issue thread.
• A tamper-evident audit trail. Every mutation appends to an event log; replaying it reconstructs the database — an invariant checked in CI.
• Runtime-neutral by design. The CLI and MCP server aren't coupled to any one agent runtime, and multi-PRD projects, GitHub Issues sync, and multi-provider LLM planning (Anthropic · Bedrock · OpenAI-compatible) all ship today.

Anvil vs. an issue tracker

Proven in real sessions

Numbers from recorded working sessions (post-session-findings), not projections:

• 32 tasks, 21 PRs, and a release from one 23.7-hour autonomous session — the loop stayed coherent across 28M generated tokens under ~2 dozen human messages.
• Two concurrent agent loops finished an 18/18-task PRD in 16.7 hours — the lease model deconflicted both sessions with zero explicit negotiation (in the benchmark, file collisions dropped 3.0 → 0.0 vs. a shared-markdown control).
• The review gates catch real defects every time they run — a fail-open deny gate, log-injection bugs, and a semantically broken "clean" merge, each caught before it shipped.

Documentation

Full documentation: fakoli.github.io/anvil

• Getting started — first project, end to end
• Using anvil on any harness — Cursor, VS Code, Zed, Codex, …
• Architecture · CLI reference · MCP reference
• FAQ — installing, storage, backups, and common gotchas
• Roadmap · CHANGELOG

Status

Beta (v0.6.13). The full PRD → plan → claim → execute → verify → finish loop works today, alongside GitHub Issues sync and multi-provider LLM support. Near-term focus is provider expansion, usability, and remaining pre-1.0 contract hardening; Linear/Monday providers and webhook sync are on the roadmap.

License

MIT — see LICENSE. Built by Fakoli (@fakoli).