The codemate that remembers, reasons, and stays yours.

The environment

This is the Anvil desktop app. Read down the steps on the right — each one describes a part of the workshop floor. (Real screenshots, captured on a fresh demo instance with sample data and no provider keys set — so a housekeeping job fails, naming the keys it's missing; your own install shows your data.)

1The panel switcher

Top-right icons open every workspace — skills, the reading list, the blueprint, the board, the Crucible, the shell, and settings. The brand on the left always shows where you are.

2What Anvil is doing

The top pane narrates the daemon's work in plain language — "I looked through your memory and grounded the answer on 5 notes." No black box: you see it think.

3Your memory, as a living graph

The workspace renders the substrate as a graph (2D or a 3D galaxy). Each dot is a memory, coloured by whether it has held up or been corrected — grey means no evidence yet.

4The event stream

Filter the live workshop-floor stream by Thinking, Tool, Verifier, Memory, or Skill — a recall that grounded a turn, a route to a provider, a finding staged for review.

5Reason with any model

Ask directly from the chat bar — pick the project scope, the router role, and the permission mode for the turn, then send. Or type / for a command.

Prefer to watch it work from a terminal? anvil watch streams the same workshop-floor events to your shell, and anvil status is the one-line health ping.

What Anvil is

Modern AI coding assistants are brilliant and forgetful. They solve a hard problem with you on Monday and have no memory of it by Tuesday. They repeat the mistakes you already corrected. They can't tell you what your project decided six weeks ago, because nothing kept the decision.

Anvil is the layer that fixes that. It runs quietly on your machine as a small always-on service — a daemon — and becomes the durable brain for your assistant. As you work in Claude Code, Codex, or a similar tool, Anvil captures what was learned, distils it into clean memory, and feeds the right pieces back into future sessions automatically. When a choice is genuinely hard, it can convene a Crucible: a cast of directed expert personas who argue the problem from different angles and resolve it into a better answer than any single pass would give.

Everything stays local. Anvil reasons through the models you already have — your coding subscription, a free provider key, or a model running on your own hardware — and stores everything it learns in an encrypted store on your disk. There is no Anvil cloud your data flows through, and no third bill for tokens you're already paying for.

What it is, what it isn't, and what we set out to build

Anvil was built around a few firm convictions. Knowing them makes the rest of these docs click into place.

What we set out to accomplish

We wanted a coding assistant that compounds. Every corrected mistake, every architectural decision, every hard-won gotcha should make the next session smarter — automatically, without anyone remembering to write it down. And we wanted that intelligence to belong to you: portable, inspectable, deletable, and never held hostage in someone else's cloud.

The convictions underneath

What Anvil does — and what it deliberately doesn't

Most tools hand you a feature list and let you discover the edges yourself. Anvil keeps the whole truth inside the product: run anvil capabilities and it prints this exact map from your own build, in four honest states — shipped and working, partial by design, planned, and deliberately absent. Here it is.

This map is maintained in the code, not in marketing — if a capability moves from Planned to Shipped, anvil capabilities and this section move with it.

How it works

Anvil has three moving parts you interact with, and one that hums along on its own.

From zero to grounded in a few minutes

Anvil ships as complete, pre-built binaries. Install them, start the daemon, connect your coder, and you're running.

1 · Install & start the daemon

Once installed, the daemon runs in the background and stays up across restarts. Confirm it's alive:

❯ anvil status
anvild: up (~/.anvil/daemon.sock)
plan: free

2 · Connect your assistant

The connect step wires Anvil's memory and tools into the coder you use. It writes only that assistant's own config and prints the directives that make Anvil its brain. Preview it first with --dry-run — it changes nothing.

❯ anvil connect --dry-run            # see exactly what would change
❯ anvil connect --client code        # wire into Claude Code
❯ anvil connect --client chatgpt     # or Codex / ChatGPT

Clients: code, desktop, chatgpt, copilot, both, or all. Omit --client to auto-detect your installed assistant.

3 · Give Anvil a way to reason

Anvil reasons through the models you provide. Your coder covers assistant-driven work; for Anvil's own background reasoning (titling memories, distilling sessions), add one free provider key — it never touches your subscription. Keys live encrypted in the vault (see The vault).

4 · Confirm everything's healthy

❯ anvil doctor
✓ daemon      responding on the IPC socket
✓ providers   ready
✓ vault       unlocked
✓ memory      healthy
✓ recall      alive — recall path healthy
· overall: ✓ healthy

Everything Anvil gives you

Each component below explains what it is, how to use it in the desktop app, and — in the expandable panel — exactly how to do the same thing from the command line, with examples.

The Brain — memory

Anvil's memory is a private, semantic store of everything worth keeping: decisions, corrections, gotchas, facts about your project. You write to it in plain language and search it by meaning, not keywords — ask "how did we handle auth errors?" and the relevant notes surface even if they never used those words.

Most of the time you never touch it directly. As you work, Anvil captures findings, distils them into clean "Category · Name" entries, and — once you approve them — folds the right ones into future sessions automatically. Under the hood it keeps quality high on its own: near-duplicates are merged, facts a newer note has overtaken are quietly superseded, and its own recall quality is continuously measured. (The retrieval machinery that makes this fast and accurate is Anvil's own — you get the results without managing the mechanism.)

Your data is yours at every moment: export the whole corpus to a portable file, back it up on a schedule, and exercise a verifiable right to forget that purges matching rows and proves none remain. The store is encrypted at rest.

1Write in plain language

Type what you learned — no schema, no fields. Anvil generates a clean "Category · Name" title for you.

2Check before you save

The optional check tells you instantly whether a note is genuinely new, a duplicate, an update, or a contradiction of something you already hold.

3Browse & recall

See what was just added, and search the whole corpus by meaning. Remove any row with a confirm-and-backup Undo — your data, always in your hands.

# Write a note — a title is generated if you omit one
❯ anvil memory write "Auth errors fall through the chain, they never cap a provider" --tag auth
# Search by meaning (semantic, not keyword)
❯ anvil memory recall "how do we handle authentication failures?"
# See what you just added / check before saving
❯ anvil memory recent --limit 10
❯ anvil memory classify "We use SQLCipher for the store"   # new / duplicate / update / contradiction
# Your data — export, back up, forget
❯ anvil memory export --out ~/anvil-memory.jsonl
❯ anvil memory backup                     # timestamped snapshot, with retention
❯ anvil memory forget --tag auth --yes          # verifiable right-to-forget

Providers & routing

A provider is any model Anvil can reason through: your coding assistant, a hosted API, or a model running locally on your own hardware. A role (orchestrator, worker, verifier, vision…) is a job to be done, and each role has an ordered chain of providers to try. If the first is down, rate-limited, or over budget, the router falls through to the next — your work continues instead of failing.

This is what lets Anvil be genuinely model-agnostic. You can lead a role with a premium model and back it with a free one, put a verifier on a different model than the worker for an independent second opinion, or run entirely on local models with no cloud at all. Per-role budgets bound how hard a role may lean on premium providers before it degrades to a free hop. And before anything leaves your machine, the scrubber redacts credential-shaped strings.

1Any model is a provider

Your coding assistant, a hosted API, or a model on your own hardware — Anvil reasons through whatever you give it. No lock-in to one vendor.

2Roles lead with a chain

Each job (worker, verifier, vision…) leads with one provider and lists backups behind it. Put a verifier on a different model for a genuine second opinion.

3Graceful failover

If the lead is down, rate-limited, or over its budget, the router falls through to the next hop — your work continues instead of failing. Per-role budgets bound premium spend.

# The whole routing picture at a glance
❯ anvil providers list
# See per-role budgets and today's premium spend
❯ anvil budget
# Ask the router to reason directly (streams tokens)
❯ anvil reason "draft a migration plan for the store schema"
# Preview what the scrubber would redact before any send
❯ anvil redact "my key is sk-ant-... and the db is at /srv"

The Crucible

Some decisions deserve more than one pass. The Crucible convenes a cast of Embers — directed expert personas such as a Skeptic, a Pragmatist, and a Security Hawk — who open on a question, cross-examine each other's reasoning, and resolve it into a single sharpened answer. You get the disagreement and the synthesis, written so a non-technical reader can follow every step.

You choose the room. Fuse a persona with a skill (skeptic+rust-development) to give it domain teeth, pick how many cross-examination rounds to run, and decide whether the Embers must reach consensus or a neutral chair synthesizes. Save a room you like as a named cast and reuse it. Because a Crucible can spend real tokens, --plan previews the room, the knowledge in play, and a rough cost before you commit — no tokens used.

1A cast of expert critics

Directed personas — a Skeptic, a Pragmatist, a Security Hawk, or a room you build — open on the question from genuinely different angles.

2They cross-examine each other

Over the rounds you choose, the Embers sharpen or concede each other's points. You watch the reasoning happen, live and legible.

3Resolved into one answer

A neutral chair synthesizes the debate (or the room must reach consensus) into a single sharpened answer — which you can promote straight into memory.

# Preview the room and rough cost — spends nothing
❯ anvil crucible "should we adopt an event bus here?" --plan
# Run it: a security-focused Rust room, 2 rounds, promote the answer
❯ anvil crucible "review this auth design" \
    --embers skeptic+rust-development,pragmatist,security-hawk \
    --rounds 2 --promote
# Save the room for reuse, then run it by name
❯ anvil crucible "…" --save rust-review
❯ anvil cast list

Connect your coder

Anvil is the brain for the assistant you already use. The connector registers Anvil's tools with your coder and hands it the directives that make it recall before answering, remember what it learns, and reach for a Crucible when a decision is hard. You keep using your own tool and your own subscription; Anvil rides alongside.

Sign-in always happens inside your assistant's own app, exactly as its terms require — Anvil never automates your login and never stores your assistant's credentials. Supported clients today are Claude Code, Claude Desktop, ChatGPT (Codex), and GitHub Copilot. After an Anvil update, --refresh re-applies the latest directives to everything already connected.

In the app: the Connect panel detects your installed assistants and wires them with a click, showing exactly what it will write first.

❯ anvil connect --dry-run                # preview — writes nothing
❯ anvil connect --client all            # wire every installed assistant
❯ anvil connect --refresh                # re-apply directives after an update

Skills

A skill is a distilled, reusable playbook — "how we do X well" — that fires automatically when a session's context calls for it, injecting a short directive rather than a wall of text. Anvil ships a curated set of engineering best-practice skills (safe code changes, git discipline, systematic debugging, security fundamentals, test-driven development, and more) so your assistant follows good habits without being told each time.

You can search the catalogue by name and contents, read any skill, and — on a paid plan — author your own from a simple SKILL.md and attach on-demand sub-files (scripts, references) it can pull in when needed. Dropped-in skills go live immediately, no rebuild. Skills are portable in the open agentskills.io format, so you can export and share them.

In the app: the Skills panel lists the catalogue, shows each skill's body, and (on Pro) lets you create and edit your own.

❯ anvil skill list
❯ anvil skill search 'name:deploy OR git'       # AND / OR / NOT + field filters
❯ anvil skill show systematic-debugging
# Author your own (Pro) — from a file or piped from chat
❯ anvil skill create < my-skill.md
❯ anvil skill export git-essentials --out git.md   # portable open format

Tasks & the board

Anvil keeps a real task board — first-class records with priorities, status, projects, and optional automatic completion checks. Tasks aren't just a to-do list: they hang off your project's flow map (the blueprint), so the work you have left is always mapped onto the thing you're building. A task can carry a check — a command or a skill — that, when it passes, flips the task to done automatically.

1Real tasks, real priorities

Every task is a first-class record with a priority, status, and project — sorted so the work that matters sits on top.

2Mapped to what you're building

Tasks hang off your project's blueprint, so what's left is always tied to the component it advances — never a floating to-do.

3Auto-completing checks

Give a task a check — a command or a skill. When it passes, the task flips to done on its own. The Done column stays capped so finished work never drowns the view.

❯ anvil task add "Wire the vault into first-run" --priority high --project anvil
❯ anvil task list --project anvil --status open
❯ anvil task show 512                      # id or unique prefix
❯ anvil task update 512 --status done
❯ anvil task check 512                     # run its check; passes → done
❯ anvil task park 512 / unpark 512        # drop off / return to the active board

Blueprint & roadmap

The blueprint is a project's flow map — the logical order of what your app actually has to do, with each step's tasks hanging off it. It's not a file you maintain by hand: Anvil can compile one from scratch by reading your code tree, memory, and backlog, then keep it current as work lands. The roadmap is a strategic lens on top of it — flow-map nodes grouped into tracks with live task roll-ups, so you can see ship-sequence at a glance.

1Your system, as a map

Each node is a real component of what you're building, in logical order. Anvil compiles the map by reading your code, memory, and backlog — you don't draw it by hand.

2Tasks hang off the map

Every node shows its live task count, so you can see exactly where the remaining work sits across the whole system.

3Stays current on its own

As work lands, a rebuild keeps the map honest. A large system folds into collapsible modules so it never becomes a hairball.

# Bootstrap a map from scratch by reading the code tree (dry-run unless --apply)
❯ anvil blueprint compile --project anvil --apply
❯ anvil blueprint show --project anvil
❯ anvil blueprint rebuild --project anvil --apply    # keep an existing map current
# The strategic lens
❯ anvil roadmap show --project anvil
❯ anvil roadmap add-track --project anvil --name "Ship prep"

The vault

Provider API keys are secrets, and Anvil treats them like it. The vault is an encrypted store, unlocked by a passphrase (and optionally your device biometrics), that holds your keys at rest so they never sit in plaintext config. On first init it prints a one-time recovery PDF — the only way back in if you forget the passphrase — which you print and store offline.

The vault has a full terminal path for headless machines (servers, CI, self-hosted) where there's no desktop to click. Lock it to drop keys from memory; unlock it to make them usable again. If you have keys in legacy plaintext config, import migrates them into the encrypted vault and securely wipes the plaintext.

1Locked or unlocked

Unlock to make your keys usable; lock to drop them from memory. A passphrase (and optionally your device biometrics) is the gate.

2Keys, encrypted at rest

Provider API keys live inside the vault, encrypted on disk — never in plaintext config. Legacy plaintext keys can be migrated in and wiped.

3Your recovery PDF

On first init Anvil prints a one-time recovery page — the only way back if you forget the passphrase. Print it, store it offline, never cloud-sync it.

# First run — set the passphrase (headless: read it from stdin)
❯ printf '%s' "$PASSPHRASE" | anvil vault init --passphrase-stdin
❯ anvil vault status                    # present / unlocked, key count, fingerprint
❯ anvil vault unlock                    # make keys usable for the daemon
❯ anvil vault lock                      # drop keys from memory
❯ anvil vault import                    # migrate legacy plaintext keys, then wipe them

Directives & base

Two mechanisms keep every session grounded before it even starts. Directives are standing operating rules that apply in every project — the cross-project constitution, injected on the first prompt of each session no matter where you're working. The base digest is the opposite lens: a compact, per-project brief compiled from that project's highest-signal memories, the one small doc a session should read before recalling anything else. Keep the directive set small — every session pays for it.

❯ anvil directives                     # the global operating rules
❯ anvil memory write "Always back up before a destructive migration" --global
❯ anvil base --project anvil            # the compiled per-project brief

Review & staging — the learning loop

This is the safety valve behind "Anvil learns as you work." Nothing it discovers is trusted automatically. While a session runs, findings land in a per-session staging table — a holding area that can never influence a live session. When the session closes, they're distilled into candidate memories and placed in the review inbox. Only after you approve an item can it ground a future turn.

Routine, low-stakes items can be auto-approved by a housekeeping pass; anything that changes a rule or installs a skill is always held for you. Every decision is logged, so a bad one can be traced to the exact moment it entered.

In the app: the review inbox shows each staged item with a plain-language recommended action — clearing it is one read and one keystroke.

❯ anvil review list
❯ anvil review triage                  # plain-language recommended action per item
❯ anvil review show a1b2                # full content before deciding
❯ anvil review approve a1b2  # or:  anvil review deny a1b2
❯ anvil staging list                 # what each live session has learned so far

Schedules

Anvil runs its own scheduler — no OS cron needed. Register a recurring reasoning turn with a standard five-field cron expression and a role, and Anvil fires it locally on cadence: a morning summary of today's tasks, a weekly review, a nightly digest. Enable, disable, or fire one on demand.

❯ anvil schedule add --name morning --cron "0 8 * * 1-5" \
    --role orchestrator --prompt "Summarise today's tasks"
❯ anvil schedule list
❯ anvil schedule run morning            # fire now, ignore the cron

Reading list

A quick-capture list for URLs you want to research later, without breaking flow. Drop a link now, come back to it, mark it done with an outcome. Small, but it keeps research threads from getting lost.

❯ anvil read add https://example.com/paper --note "retrieval eval method"
❯ anvil read list
❯ anvil read done 3 --outcome "adopted the bounded-window idea"

Image generation

Anvil can generate images through the same provider seam, local-first. The default backend runs on-device — your prompt never leaves the machine. A keyed cloud tier is available as an explicit, opt-in fallback (its key lives in the vault), and a non-private browser tier is deliberately refused.

❯ anvil image generate "a forge glowing in a dark workshop"   # on-device by default
❯ anvil image generate "…" --backend cloud            # opt-in keyed tier (vault key)

Shell

Sometimes Anvil (or you) needs to run a real command — a build, a test, a check. The shell surface runs one allow-listed command through the daemon and returns its output, token-compacted. No pipes, no redirects, no shell hop: a single command whose name you've explicitly added to your allow-list. It's a deliberate, consented capability, not an open terminal.

In the app: the Shell panel runs an allow-listed command and renders the result inline as inert, untrusted text, and lets you edit the allow-list.

# The command name must be listed in ~/.anvil/shell-allow.txt
❯ anvil shell "cargo test --workspace"

Self-improvement, under governance

Anvil watches its own performance and proposes ways to get better — but never changes itself behind your back. When a turn goes wrong, it can attribute the failure to a named cause, draft a self-RFC (an improvement proposal), and measure whether a change would actually help. Everything is propose-only: a human reads the proposal and decides whether it becomes a task. Every autonomous change the system does make to itself is written to a content-free, auditable, reversible change ledger, with rate-caps so it can never run away.

You never need to touch this to use Anvil — it's the machinery that keeps quality trending up. But it's fully inspectable when you want to look.

❯ anvil substrate                    # one health view across the whole loop
❯ anvil rfc                          # proposals awaiting your call
❯ anvil change                       # the reversible self-change ledger
❯ anvil diagnosis                    # confirm the cause of a novel failure

Health & logs

Anvil is legible when something goes wrong. doctor gives one aggregate health report across the daemon, providers, vault, memory, and recall — and can write a shareable, issue-ready failure report (it never files the issue for you). status is a quick liveness ping. logs reads Anvil's own daily log files directly, so it answers "what went wrong and when" even while the daemon is down — which is exactly when you ask. activity replays a content-free trail of what each action did, so a session can be reconstructed from references without ever exposing your content.

❯ anvil doctor                       # one health report
❯ anvil doctor --report              # write a shareable failure report
❯ anvil logs                         # reads the daily files directly — works when the daemon is down
❯ anvil activity                     # content-free trail of what each action did
❯ anvil snapshot                     # honest, token-budgeted workspace snapshot

Configuration — where to set what

Anvil keeps everything under one home directory. Two files carry your configuration; secrets live encrypted in the vault.

The config sections

Inside config.toml, each block tunes one part of the system. You rarely need most of them — defaults are sensible — but everything is adjustable:

Plans & tiers

Anvil comes in three tiers. Memory, your data, and the local-first guarantees are never gated — the paid tiers add reasoning depth and, for teams, a shared substrate. Dropping to a lower tier degrades gracefully; it never deletes your knowledge or locks you out.

Activate a paid plan with a signed, offline license token — anvil license activate <token> — stored sealed and encrypted at rest. No plan phones home to decide what you can do.

Privacy & security

Local-first isn't a slogan here — it's the architecture. A few guarantees worth stating plainly.

Want the ground truth for what Anvil can do, what's planned, and what's deliberately absent? Run anvil capabilities — the maintained answer, so nobody has to infer it.

CLI reference

Everything in the app is a command. These are the top-level commands; each has --help with its full options. This is the complete surface — nothing in the product is app-only.