Get Anvil working with your assistant.

Install Anvil.

Get the file for your system from the download page, which has the install steps for each one. Here is what the installer puts on your machine.

First run.

Open Anvil. The first time, it walks you through these steps.

1. Create your vault. Anvil opens Settings › Vault & secrets for you. Pick a passphrase and save the recovery PDF. Your memories and keys are encrypted with it, and nothing else opens until the vault exists.

   

   Setting up takes a minute or two on a slower computer. Keep the window open: when it is done, Anvil shows your recovery PDF, and nothing moves on until you have saved it.

   

   

   

   Keep the recovery PDF somewhere outside the Anvil folder, such as a USB stick or your password manager. If you set the vault up from the terminal (anvil vault init), the PDF is saved inside ~/.anvil by default, and that folder is deleted if you ever uninstall Anvil.

   After you unlock the vault, Anvil keeps an unlock key in your system's credential store (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux), so you aren't asked every time it starts. On macOS, click Always Allow when the Keychain asks.

   If your system can't keep that key (some Linux desktops have no credential store), Anvil asks for your passphrase after each restart instead:

   

2. Connect your assistant. Anvil lists the assistants it found, all ticked. Click Connect, or choose Not now to be asked again next time. Anvil then lists every file it changed. Step 3 covers this in detail.

   

   

3. Give Anvil a way to think. Anvil needs a model for its own work, such as sorting and summarising your memories. Pick one:
   • Claude or ChatGPT. Uses your existing sign-in, so you don't need a key.
   • An API key from Groq, Google AI, Cerebras, OpenRouter, OpenAI or Anthropic. Keys are stored only in your encrypted vault. Anvil won't save a key until the vault exists.

     

   • A local model. Anvil talks to Ollama, llama.cpp, MLX and vLLM, but it doesn't install them. Install one yourself, start it and download a model. For example, Anvil looks for Ollama at 127.0.0.1:11434.
4. That's the Free plan. You don't need an account. Free includes the whole memory brain with one active model provider. The Crucible, custom skills and Blueprint come with the paid plans.

Connect your assistant.

Connecting is what lets your assistant use Anvil's memory. You can do it three ways.

1. On the setup screen the first time you open Anvil.
2. Any time later in Settings › Assistants, under What Anvil sets up in your assistants. For Claude Code and Codex you can switch each part on or off there. Your choice applies as soon as you click Save and apply.
3. From a terminal. anvil connect finds your assistant and asks before each change. To pick one yourself, name it. To see what would change without changing anything, add --dry-run.
   anvil connect --client code --dry-run

Cursor, Windsurf and Gemini CLI aren't connected automatically yet. Any assistant that supports MCP can still use Anvil if you add the anvil-mcp server to its settings yourself.

What Anvil changes in your assistant.

The same rules apply to every assistant:

• Only Anvil's own entries. Everything else in the file stays exactly as you had it.
• A backup first. Before Anvil edits a file for the first time, it saves a copy next to it as <file>.anvil-bak. That copy is never overwritten.
• Safe writes. Each file is written in full to a temporary copy, then swapped in, so a crash can't leave it half-written.
• Repeatable. Connecting again updates Anvil's entries rather than adding duplicates.

In the paths below, ~ is your home folder. On Windows that's C:\Users\<you>.

What you do by hand.

After you connect

Your assistant only reads its settings when it starts, so:

• Claude Code: start a new session.
• Claude Desktop, ChatGPT: quit the app completely and open it again.
• VS Code with Copilot: reload the window, then turn on anvil in the tools picker in Copilot Chat.
• LM Studio: turn on anvil under Program › Integrations.

After every Anvil update

Updates can bring new instructions and settings. Apply them to the assistants you've already connected:

It changes only assistants that are already connected, and it doesn't ask any questions.

On a Mac

• Open Anvil after you restart your Mac. Nothing starts it at login yet. Until you open it, your assistant's Anvil tools and hooks do nothing, and they don't show an error.
• Installed from the disk image? Put the anvil command on your PATH so you can type anvil in Terminal (Homebrew does this for you):
  echo 'export PATH="/Applications/Anvil.app/Contents/MacOS:$PATH"' >> ~/.zshrc
  Then open a new Terminal window.

If memory files appear anyway

Assistants sometimes write their own memory files despite the instructions. anvil doctor warns you when it finds them. To move what's in them into Anvil:

How we run it ourselves.

We build Anvil with Anvil connected to Claude Code and Codex. This is our setup, if you want to work the same way.

1. Every default left on. Recall before each prompt, the warning before tool use, saving when the assistant finishes, saving before an automatic compact, and the instructions block. Each one covers a different moment where knowledge gets lost.
2. Anvil as the only memory. We never use the assistants' own memory files. Two memory stores drift apart and contradict each other, and that's worse than one. If anvil doctor finds memory files, we move them in with anvil memory tripwire --ingest.
3. Anvil's personality on. The same working style in every session and every assistant.
4. AI credit lines off. Commits and pull requests carry only the person who's responsible for them.
5. Hard calls go to the Crucible. For risky or contested decisions, the assistant asks the Crucible rather than guessing (paid plans).
6. anvil connect --refresh after every update, so every assistant has the current instructions.

To match this, open Settings › Assistants, tick Anvil's personality and Leave AI credit lines off commits and pull requests for each assistant, and click Save and apply.

Make sure it's all running.

1. Is Anvil running?
   anvil status
2. Is it healthy? anvil doctor checks the background service, your settings, model providers, the vault, memory and more, and says how to fix anything that's wrong. It doesn't check your assistant connections; step 3 does that.
   anvil doctor
3. Or use the app. Settings › System has the same check.

   

4. Can your assistant see Anvil? In Claude Code, type /mcp: anvil should be listed as connected. Then tell your assistant something worth remembering, start a new session and ask about it.

Disconnect, or uninstall.

Disconnect one assistant

• Claude Code and Codex: in Settings › Assistants, untick Connect Anvil to this assistant and click Save and apply. Or run anvil connect --client code (or codex) and answer n to the first question. Either way removes Anvil's MCP server, hooks, instructions block and the credit-line setting.
• Claude Desktop, Copilot, LM Studio, Cline, opencode: there's no one-click disconnect yet. Remove the anvil entry from the file listed above, or put back the .anvil-bak copy. That copy is the file as it was before Anvil first changed it, so it won't include changes you made since.

Uninstall

anvil uninstall takes Anvil out of every assistant, stops it, and deletes what it created. Run it without --yes first to see the list.

Tell us.

In the app, open Settings › System and choose Report a bug, or run anvil report-bug "what happened". Reports never include your memories, prompts or code. For the full feature reference, see the Anvil docs.