The provider-agnostic AI development pipeline

Use your own keys. Mix providers per stage. Pay per token, not per seat.

Anvil ships features end-to-end — clarify, plan, build, review, PR —
across every repo in your project, on whatever model is cheapest for each stage.
No vendor lock-in. No markup. No hosted plan.

_{Anvil is an open-source, self-hosted AI coding agent — an end-to-end LLM pipeline (clarify → plan → build → review → PR) that runs on Claude, GPT, Gemini, and OpenRouter, or fully local via Ollama & OpenCode. It speaks the Model Context Protocol (MCP) and uses your own API keys. Written in TypeScript.}

<sub>Dashboard preview — pipeline orchestration, live agent activity, knowledge graph, cost ledger.

Click the gif to watch the full demo</sub>

Why teams pick Anvil

Quick start

# 1. Install
npm install -g @esankhan3/anvil-cli

# 2. Set up a project (interactive — answers a handful of questions)
anvil init

# 3. Open the dashboard and ship
anvil dashboard

That's the whole onboarding. anvil init creates ~/.anvil/,
seeds models.yaml, scaffolds your project's factory.yaml, and
runs a health check. anvil dashboard boots the WebSocket
control plane and opens the UI.

First time? The full walk-through — prerequisites, where to
get provider keys, what anvil init will ask you, troubleshooting
— lives in docs/getting-started.md.

Provider-agnostic by design

Eight providers ship in the box. One config file picks them per
stage. Each adapter speaks the same streaming format, the same
UpstreamError retry shape, the same per-call cost calculation.

One run, three providers, fourteen cents

Routing is per-stage, not per-run. The same feature can flow
through three providers without you lifting a finger:

  clarify     →  Ollama / OpenCode   local           ~ $0.00
  plan        →  Claude Sonnet       deep analysis   ~ $0.05
  build       →  Ollama / OpenCode   local           ~ $0.00
  test        →  Ollama / OpenCode   local           ~ $0.00
  validate    →  Claude Haiku        cheap + fast    ~ $0.01
  review      →  Claude Sonnet       judgment-heavy  ~ $0.08
  ship        →  Ollama / OpenCode   local           ~ $0.00
                                                  ──────────
                                                    ~ $0.14

It's just YAML in ~/.anvil/stage-policy.yaml. Premium models only
appear where premium models actually matter. Read-only research
and the fix-retry loop are locked to free tier — they cannot
escalate, by design. A typical run with Ollama or OpenCode burns
single-digit dollars on cloud calls.

Auto-failover when a provider misbehaves

If a model 429s, 5xx's, hits a quota wall, or fails its liveness probe
mid-run, Anvil's chain-walker burns it for the rest of the run and
falls through to the next entry in the same tier — same provider or
different, your call. The pipeline doesn't pause, doesn't surface a
stack trace at the user, and doesn't double-charge by retrying the same
broken model. Every fallback hop emits a routing event so you can see
exactly which model was skipped and why.

clarify   →  adk:gemini-2.5-flash   ❌  (provider liveness fail)
          ↪  opencode/kimi-k2.6     ✅  (next in chain, same tier)
build     →  opencode/qwen3.5-plus  ❌  (429 — Alibaba upstream)
          ↪  opencode/glm-5.1       ✅  (model burned for run, fallback proceeds)

Two layers of detection: a proactive liveness probe at run start
(Ollama /api/tags, env-var presence for cloud) and a reactive
duck-typed UpstreamError check on every adapter call. Configurable
per-run cap on retry attempts in models.yaml (walker.max_attempts).

One GPU, many models — exclusive slot serialization

Big local models can't all share a single GPU at the same time.
If your clarify and build stages both want a heavy Ollama
model, naive concurrency ends in an OOM. Anvil's
exclusive_slot: true flag puts those models behind a
process-local FIFO queue so only one exclusive model is ever
GPU-resident at a time.

The queue does the dance for you:

• Hard eviction on switch. Going from model A → model B
  explicitly tells Ollama to release A's weights, then polls until
  the GPU has actually freed them before letting B load. No GPU
  briefly holding both.
• Intruder detection. An out-of-band Ollama session on the host
  (e.g. you ran ollama run in another terminal) gets evicted
  before the next exclusive load — so two big models can't sneak
  in side by side.
• Embeddings + rerankers bypass. They're small enough to
  co-reside, so they never touch the queue.
• Same-model calls are free. Consecutive calls to the same id
  skip the eviction step entirely. A stage fanning out across repos
  pays the model-load cost once.

Mark a model exclusive in ~/.anvil/models.yaml:

- id: ollama/qwen2.5-coder:14b
  provider: ollama
  tier: local
  vram_gb: 9
  exclusive_slot: true        # mandatory for any VRAM-heavy local

Lets you mix multiple big local models on the same machine without
manual sequencing or OOM kills, regardless of how much VRAM you
actually have.

Cost ledger, live

Every adapter call attaches a real gen_ai.usage.cost attribute
computed from a vendored LiteLLM pricing snapshot. The dashboard
shows you per-call, per-stage, per-run spend in real time. The
OpenTelemetry export carries the same numbers if you want them in
Langfuse, Tempo, or Honeycomb.

No estimates. No surprises.

What you can do with Anvil

Observability (opt-in)

Telemetry is off by default. When you turn it on, every adapter
call emits an OpenTelemetry span with GenAI semantic conventions —
prompt + completion tokens, cost, latency, model, provider, error
class. Plug in any OTLP-compatible backend.

Two switches, one env var each

# 1. Export to a real OTLP collector — Langfuse, Tempo, Honeycomb, …
echo 'OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:3000/api/public/otel/v1/traces' >> ~/.anvil/.env
echo 'OTEL_SERVICE_NAME=anvil-dashboard' >> ~/.anvil/.env

# 2. Or dump spans to stderr — useful for debugging without a collector
echo 'ANVIL_OTEL_CONSOLE=1' >> ~/.anvil/.env

Restart the dashboard and traces start flowing.

Privacy + noise controls

By default, spans carry structure but not content — model, cost,
latency, error class, all attached. Prompts and completions stay on
disk only.

Quick local stack: Langfuse

Anvil ships a tuned Langfuse compose file at
infra/observability/ — Langfuse 3.x +
Postgres + ClickHouse + Redis + MinIO, pre-wired for the OTLP HTTP
endpoint Anvil exports to. No external clone needed:

# Spin up the bundled stack on http://localhost:3000
docker compose -f infra/observability/docker-compose.yml up -d

# In ~/.anvil/.env (use the keys you create in the Langfuse UI)
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:3000/api/public/otel/v1/traces
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer pk-lf-...
OTEL_SERVICE_NAME=anvil-dashboard

Anvil's dashboard auto-detects the local Langfuse on port 3000 — if
it's running and you haven't set OTEL_EXPORTER_OTLP_ENDPOINT
yourself, the dashboard wires it up automatically. Tear down with
docker compose -f infra/observability/docker-compose.yml down -v.

What you'll see

• One anvil.agent.session parent span per pipeline stage,
  linking every adapter call and resume into a single trace.
• A gen_ai.invoke child span per LLM call, with
  gen_ai.system, gen_ai.request.model, gen_ai.usage.input_tokens,
  gen_ai.usage.output_tokens, and a real gen_ai.usage.cost
  in USD.
• gen_ai.tool.<name> child spans for every tool call the agent
  makes, closed when the matching tool_result arrives.
• A routing-decision attribute group (anvil.routing.*) on the
  invoke span so you can see why a particular model was picked, and
  which models got burned mid-run.

The OTLP export carries the same numbers the dashboard's cost panel
shows. One source of truth.

How it all fits together

Anvil is a TypeScript monorepo. Each package owns one concern; the
dashboard ties them together.

                         ┌────────────────────────┐
                         │     anvil dashboard    │  the control plane
                         │   (React + WebSocket)  │
                         └────────────┬───────────┘
                                      │ orchestrates
                                      ▼
                  ┌───────────────────────────────────────┐
                  │         pipeline-runner               │
                  │  9-stage walker · per-repo fan-out    │
                  │  validate-fix loop · chain-fallback   │
                  └───┬──────┬──────┬──────────┬──────┬───┘
                      │      │      │          │      │
                      ▼      ▼      ▼          ▼      ▼
                  ┌──────┐ ┌────┐ ┌──────┐ ┌──────┐ ┌──────────┐
                  │agent-│ │core│ │knwldg│ │memory│ │convention│
                  │ core │ │pipe│ │ core │ │ core │ │  -core   │
                  └──┬───┘ └─┬──┘ └───┬──┘ └───┬──┘ └────┬─────┘
                     │       │        │        │         │
                     ▼       ▼        ▼        ▼         ▼
                       ~/.anvil/  · models.yaml · stage-policy.yaml
                                  · runs/<id>/  · features/<slug>/
                                  · knowledge-base/<project>/
                                  · memories/  · conventions/

Three different fronts ride on the same engine:

• anvil CLI — init, doctor, dashboard (the front door)
• Dashboard — full pipeline control with live agent activity
• code-search-mcp — the standalone code-search product:
  MCP server, the code-search CLI (index / query / status /
  reset / daemon / serve / mcp), and the
  code-search-daemon long-running indexer. Three bins, one
  install. Works without the Anvil agent stack.

Per-package deep dives

Configuration

Three files run the show, all in ~/.anvil/:

Working examples live in examples/anvil-home/.
Bootstrap with:

cp examples/anvil-home/.env.example      ~/.anvil/.env  && chmod 600 ~/.anvil/.env
cp examples/anvil-home/models.yaml       ~/.anvil/models.yaml
cp examples/anvil-home/stage-policy.yaml ~/.anvil/stage-policy.yaml

anvil init does the equivalent for models.yaml automatically.

Project setup examples

Three opinionated starters in examples/:

• TypeScript monorepo — Next.js
  storefront + Express API, Postgres, Redis
• Go microservices — multi-service
  Go workspace
• Python ML — training + serving split

Copy a factory.yaml, adjust paths, and anvil init against your
own workspace.

Built with

We rely on the best of the open ecosystem:

tree-sitter ·
LanceDB ·
graphology ·
OpenTelemetry ·
Model Context Protocol ·
React ·
Vite ·
commander

Packages

The monorepo publishes a single user-facing CLI plus the building blocks
it sits on top of. Every package below is published with npm provenance
(sigstore attestation linking the tarball back to this repo) — npm install
verifies the chain automatically.

Package	Purpose	npm
@esankhan3/anvil-cli	The user-facing CLI + bundled dashboard. Run npx @esankhan3/anvil-cli to start.
@esankhan3/anvil-agent-core	Shared LLM stack — unified LanguageModel interface, provider adapters, agent subprocess machinery, cost calc.
@esankhan3/anvil-knowledge-core	AST chunking, tree-sitter parsing, embeddings, LanceDB vector store, hybrid retrieval.
@esankhan3/anvil-memory-core	Long-term memory — five-type taxonomy, bi-temporal facts, drift detection, sleeptime ratification. 83.4% on LoCoMo.
@esankhan3/anvil-convention-core	Convention extraction, rule engine, promotion ledger.
@esankhan3/anvil-core-pipeline	Typed Step<I,O> graph, EventBus, StepRegistry, lifecycle hooks.
@esankhan3/code-search-mcp	Standalone code-search product — MCP server + code-search CLI + code-search-daemon (file-watcher + UDS JSON-RPC).

The dashboard (@anvil-dev/dashboard) is bundled inside the cli — it is
not published as a standalone npm package.

Status

In flight: richer plan validators · deeper RAG-eval ·
additional MCP tools · cost-policy enforcement (UI scaffolded —
ships in the next minor) · notification channels (Slack + email).