AgentBrain

One project. Any coding agent. No lost context.

AgentBrain is a local-first continuity layer for AI coding agents. It keeps the execution state of a software task — objective, progress, decisions, failures, Git state, next action — with the repository, so the task can move from one agent to another without starting the conversation over.

Git tells you what the code looks like. AgentBrain tells the next agent what was happening and what to do next.

Switch it on from any terminal, even inside an agent session, and it becomes the control room beside your agents: it shows every agent at work, keeps the shared memory, and decides whose work counts, by one lead agent or by a council that votes and checks the evidence itself.

AgentBrain is not an IDE, a model provider, or a replacement for Git. It never commits on its own (merging an approved task's branch is the one Git write it makes, and only when you have set reviewers), and never stores file contents.

Install

git clone <this repo> && cd agentbrain
npm install
npm run build
npm link          # puts `agentbrain` on your PATH
agentbrain doctor # checks the installation and project integration

Requires Node 20+ and Git.

Related MCP server: AgentBridge MCP

The console

cd your-project
agentbrain

Opens the AgentBrain console, built like an agent CLI: a prompt box, slash commands, and a live transcript. What you type is delegated: it becomes a task with its own worktree, your worker agent picks it up (Copilot in the VS Code chat you already have open, or a headless agent), and its edits, commands and progress stream into the console. When it finishes, the result comes back for review with AgentBrain's own checks: /approve merges it, /changes <what to fix> sends it back. /help lists the rest (/status, /review, /continue, /worker, /lead, /council, /checks, /dashboard).

AgentBrain only sets itself up inside a project (a Git repository), never in your home folder. agentbrain top is the older full-screen live view.

Control plane

agentbrain on                  # from any terminal in a project, or `! agentbrain on` inside Claude Code

One idempotent step: it initializes the repo if needed, connects every agent to AgentBrain over MCP, streams Claude Code's prompts, edits and commands into the activity feed (hooks in .claude/settings.local.json), installs the commit hook, and opens the control room in your browser, beside your terminal:

• Home: a prompt box to delegate from the browser, what needs you (results to review, with checks, flags and votes), and what is in progress, each task with its stage (delegated, working, checks, review, done) and its latest activity.

• Activity: the live feed of prompts, edits, commands, commits, progress, decisions, handoffs and verdicts, from every agent.

• Brain: the shared memory as a graph of tasks, agents, decisions, files and flags (also written as an Obsidian vault in .agentbrain/vault).

• Settings: who new tasks go to, who decides, and the checks.

agentbrain off stops streaming and closes the control room; state is kept. Details: docs/control-plane.md.

Who decides: a lead or a council

agentbrain lead claude-code                       # one agent reviews everyone else's work
agentbrain council claude-code codex gemini cursor --quorum 0.67
agentbrain checks "npm test" "npx tsc --noEmit"   # AgentBrain runs these itself on every result
agentbrain review                                 # what is waiting, with claims, diff, checks, flags, votes
agentbrain review <task-id> --approve             # or --changes "<what to fix>"

With reviewers set, an agent that finishes a task doesn't close it: the task waits in review. A lead approves or sends it back. A council votes:

• Evidence first. AgentBrain runs your checks in the task's folder itself. Failing checks block approval whatever the votes say.

• Sealed votes. Reviewers can't see each other's votes until they have voted, so they judge the work, not each other.

• Reputation as stake. Votes are weighted by each agent's track record: agreeing with outcomes earns weight, dissent and false claims cost it.

• Quorum. A result passes with the quorum's share of the weight (default two thirds). With equal weights, n reviewers survive ⌊n/3⌋ broken, compromised or hallucinating members: 4 tolerate 1, 7 tolerate 2.

• Flags. Claims that the evidence contradicts are shown on the result and in the brain: "tests pass" when AgentBrain's run failed, "done" with no changes, files that don't exist (in the work or in a review), and votes against the consensus.

Approval merges the task's worktree branch and marks it done. Changes become the task's remaining items and hand it back. Your verdict, from the CLI or the control room, always decides (recorded as an override).

Agents talking to each other

Agents working on the same project at the same time can coordinate through AgentBrain: "my uncommitted change to README.md blocks your merge", "I'm editing the API, hold off on the client", "can you review this?".

agentbrain message vscode "hold off on page.ts, I'm editing it"   # or: all, claude-code, codex…
agentbrain inbox                                                    # messages for you

Agents send with the agentbrain_message MCP tool and receive messages in their next AgentBrain tool result; Claude Code also gets them through its hooks (including just before it stops), and Copilot gets them in its VS Code chat when it is idle. In the console: /message <agent|all> <text>.

The memory palace (an Obsidian vault)

.agentbrain/vault is a real Obsidian vault, kept current by AgentBrain: open the folder in Obsidian and the graph view shows the project's memory, coloured by room.

• Onboarding: the first note any agent reads, new or returning: how work happens here, who reviews, the checks, and what to read next.

• Lessons: what reviewers sent back, claims that didn't match the evidence, known failures. New sessions get the latest lessons in their first context.

• Agents, Tasks, Decisions (one note per decision, linked to its task and agent), Code map (files the agents changed and which tasks did), Daily log.

• Memory: lasting notes agents save with agentbrain_remember, plus anything you write anywhere in the vault. AgentBrain never overwrites them.

Agents search all of it with agentbrain_recall; you can too:

agentbrain recall "how do we handle auth tokens"

Choosing the agent

Each prompt goes to the agent best placed to do it right now: who is free, whose results were approved or sent back in this project, reputation, recent usage limits and crashes, and your preferences. The console shows the pick and the reasons (Shift+Tab switches, @claude … / @codex … / @copilot … / @any … at the start of a prompt overrides). Agents AgentBrain can start itself: Copilot in your open VS Code chat, Claude Code (claude -p, including the copy inside the Claude desktop app) and Codex (codex exec), with no window (agentbrain run claude-code|codex [task] --print), and ACP agents. Everything else that speaks MCP (the Claude app, Cursor, Windsurf, the Claude Code / Codex / Cline extensions in VS Code) can pull work: @any leaves the task waiting, and the next agent you open on the repo is told about it.

Claude Code as a reviewer is asked to review automatically: when it finishes a turn with results waiting, its stop hook hands it the review queue once per result. Other agents see the queue in their MCP instructions and tools.

Limits, stated plainly: reviewers built on the same model can share the same blind spot, so mix vendors in a council. Flags catch claims that can be checked mechanically, not every wrong answer.

Use it

Five-minute walkthrough

Follow these steps from the root of the project you want agents to work on.

1. Install AgentBrain.

   npm install
   npm run build
   npm link

   These install dependencies, build the CLI, and put agentbrain on your PATH. You should see a successful TypeScript build and be able to run agentbrain --help.

2. Initialize the project.

   agentbrain init

   This creates the local .agentbrain/ state directory. You should see a confirmation that the project is initialized.

3. Connect your coding agents.

   agentbrain connect

   This configures MCP, writes agent instructions, and installs the Git hook. You should see the targets that were configured and the files that were written.

4. Create a task in its own worktree.

   agentbrain task create "Implement OAuth login" --worktree

   This creates and activates a task with an isolated Git worktree. You should see the task ID, its agentbrain/<task-id> branch, and its worktree path.

5. Start the first agent.

   agentbrain run claude

   This launches Claude with the task brief and asks it to record progress as it works. You should see Claude working in the task's worktree; in Copilot or Cursor, open the connected project and say continue instead.

6. Let AgentBrain capture the handoff.

   agentbrain status

   When the agent exits because it finishes, reaches a usage limit, or stops, AgentBrain writes a handoff checkpoint automatically. You should see the task's progress, stop reason, and next action in the status output.

7. Route the task to another agent.

   agentbrain route
   agentbrain run codex

   The first command suggests the next agent and explains why; the second starts it with the saved brief. You should see the new agent continue from the previous checkpoint rather than starting from scratch.

8. Watch the task live.

   agentbrain

   This opens the live terminal view of tasks, agents, checkpoints, and diffs. You should see the active task and its current status update as work progresses.

9. Finish by merging the worktree.

   agentbrain worktree merge <task-id>

   This merges the completed task branch into the project and removes its worktree. You should see the merge result and a clean-up confirmation.

How it works

AgentBrain persists coordination state alongside the project:

.agentbrain/
├── project.json
├── tasks/<task-id>/task.json
├── tasks/<task-id>/checkpoints/<checkpoint-id>.{json,md}
└── agents/<agent-id>/sessions/<session-id>.{json,prompt.md}

The same state reaches agents through three integration paths:

• MCP: agentbrain connect configures clients to read briefs, update progress, checkpoint, and hand off through the MCP server.

• Instruction files: agentbrain rules writes the protocol into files such as AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md.

• Launching agents: agentbrain run <agent> starts a terminal agent with the current brief and records an automatic handoff when it exits.

cd your-project
agentbrain init
agentbrain task create "Implement OAuth login"
agentbrain rules          # teach your agents the protocol (see below)

Live state for every agent (MCP)

To connect the agents installed in your editor to the same live AgentBrain state, run this once from the project:

agentbrain connect

This configures the MCP server, writes the agent instruction files, and installs the post-commit hook. A new chat receives the current task brief when it connects, so you do not need to paste a brief or say resume first. Agents can read the brief and timeline, get routing suggestions, update progress, checkpoint, hand off, create a task, and list tasks through MCP. Routing only suggests; the developer decides, and disconnecting while an agent owns a running task creates an automatic handoff checkpoint.

The generated files are:

Use agentbrain connect --only <ids> to configure selected targets. The operation is repeatable and preserves unrelated configuration.

Terminal agents

agentbrain run claude     # Claude Code works on the task...
                          # ...hits its usage limit and exits
                          # → AgentBrain writes a handoff checkpoint automatically
agentbrain run codex      # Codex starts with the full brief and continues

run launches the agent's normal interactive UI with the AgentBrain brief as its first message. The brief tells the agent to record progress as it goes:

agentbrain task update --done "OAuth callback" --todo "Refresh-token rotation" \
  --decision "httpOnly cookies, not localStorage" --next "Implement rotation"

status and the brief number the remaining items and known failures, so --done 2 completes remaining item 2, --drop 1 removes a wrong or duplicate item without marking it finished, and --fixed 1 clears failure 1.

When the agent exits without handing off (usage limit, crash, Ctrl-C, closed terminal), AgentBrain records a handoff with the reason. Built in: claude, codex, gemini, cursor (cursor-agent), copilot (Copilot CLI), aider. VS Code's GitHub Copilot agent mode is also available as a detached launcher:

agentbrain run vscode

This opens the project in VS Code, starts Copilot agent mode, and attaches the continuation brief as a file. VS Code owns the task after its launcher exits; the agent records progress and hands off through AgentBrain. Anything else:

agentbrain run --agent my-agent -- my-agent-cli --message {prompt}

Automatic capture

To record a checkpoint after every successful commit while the active task is running, install the Git hook:

agentbrain hooks install

The hook respects Git's core.hooksPath and preserves existing hook content. It can be removed with agentbrain hooks uninstall. AgentBrain failures never fail or delay a commit.

IDE agents (Cursor, Copilot in VS Code, Windsurf, …)

These live inside the editor, so AgentBrain can't launch them. Instead, agentbrain rules writes instruction files they read automatically:

Existing content in those files is preserved; AgentBrain only manages its own marked block. Then, in the agent's chat (agent mode):

Continue the AgentBrain task.

The agent runs agentbrain resume --agent cursor, gets the brief, records progress, and runs agentbrain handoff when you switch away. You can also switch by hand at any time:

agentbrain handoff --reason "switching to Cursor for the UI work"
agentbrain resume          # prints the brief — paste it into any agent

agentbrain run vscode <task-id> --here sends the task to the Copilot chat you already have open instead of opening the task's folder in a new window; the message tells Copilot the exact directory to work in.

Parallel agents: one worktree per task

agentbrain init --worktrees (or "worktreeByDefault": true in .agentbrain/project.json) gives every new task its own worktree; pass --no-worktree to opt a single task out.

agentbrain task create "Add prune command" --worktree   # .agentbrain/worktrees/<id>, branch agentbrain/<id>
agentbrain run vscode <task-id>                         # the agent works only in that folder
agentbrain worktree merge <task-id>                     # merge the branch back, remove the worktree

Every worktree shares the project's AgentBrain state, and commands, the MCP server and the commit hook inside a worktree apply to that worktree's task. Git state, changed files and stall warnings are per task, so two agents on two tasks never see, or trip over, each other's edits. worktree merge stops on conflicts and leaves them for you; worktree remove refuses to discard uncommitted work unless you pass --force.

Headless: no window at all

agentbrain run claude-code <task-id> --headless --timeout 30

Runs an agent that speaks the Agent Client Protocol (claude-code-acp, gemini --experimental-acp, codex-acp, or any ACP command after --) with no UI, in the task's own worktree. AgentBrain answers the agent's requests on your behalf: file reads and writes only inside that worktree; edits allowed, but shell commands, deletes and network calls rejected unless you pass --allow read,edit,execute,.... The agent records progress through AgentBrain's MCP server, gets "continue" while it is making progress (--max-turns, default 3), and the run always ends with the task in review or handed off, plus a transcript you can read afterwards.

Tested with a stand-in ACP agent; not yet run against the real ones.

Live web dashboard

agentbrain ui                 # run the control room in this terminal (agentbrain on runs it in the background)
agentbrain ui --port 5050     # choose a port (a busy default port is replaced automatically)

The dashboard shows every task, agent progress, diffs, timelines, and live headless transcripts. It runs on localhost and requires its private URL token.

When an agent goes quiet

agentbrain status (and every brief) warns when:

• the agent that owns a running task has shown no activity for 10 minutes — no AgentBrain updates and no file changes; it may have stopped or be waiting on an approval prompt;

• an agent keeps changing files but hasn't recorded progress for 10 minutes;

• files changed after a handoff but no agent has taken the task over.

Set "stallMinutes" in .agentbrain/project.json to change the threshold.

Live view

agentbrain top                 # full-screen live view of every task and agent
agentbrain notify              # desktop notifications for settled or stalled tasks
agentbrain notify --print      # print notifications instead of using the desktop

The notifier runs until stopped with Ctrl-C and reports tasks that move to review, done, blocked, failed, or handoff, plus newly detected stall warnings.

Run agentbrain with no arguments for a live terminal view of every task and agent: status lights (running, stalled, handed off, in review), the brief, the uncommitted diff in each task's worktree, the timeline, routing suggestions, and the live output of background (headless) agents. Select with the arrow keys or the mouse. o opens the task's folder in VS Code without stopping anything; m sends a message to a background agent (it becomes the agent's next turn in the same session); s stops it.

Everything else

agentbrain status                 # active task, progress, last checkpoint, stall warnings
agentbrain status --json          # machine-readable JSON for status, task list, log, or route
agentbrain checkpoint             # snapshot without stopping
agentbrain log                    # timeline of agent sessions and checkpoints
agentbrain route [task-id]        # which agent should take the task next, with reasons
agentbrain queue add <task-id>... # line up tasks for one agent
agentbrain queue list             # what's queued (queue remove <task-id> to drop one)
agentbrain queue run vscode --here # hand queued tasks to the agent one after another
agentbrain attach <session-id>    # watch a background (headless) agent live and message it
agentbrain stop <session-id>      # stop a background agent; its task is handed off
agentbrain export [task-id]       # export a portable Markdown brief and history
agentbrain worktree add [task-id] # give a task its own Git worktree
agentbrain worktree remove [task-id] # remove a task worktree
agentbrain worktree list          # task worktrees and their branches
agentbrain worktree prune         # clean up worktrees of finished, merged tasks (--branches, --dry-run)
agentbrain prune [task-id]        # remove old checkpoints (use --keep N, --all, or --dry-run)
agentbrain connect                # configure MCP, rules, and the Git hook
agentbrain on                     # enable AgentBrain and start the control room
agentbrain off                    # stop the control room and activity hooks
agentbrain lead <agent-id>        # set the reviewing lead agent
agentbrain council <agent-id>...  # configure a reviewing council
agentbrain checks <command>...    # configure checks for submitted work
agentbrain review [task-id]       # inspect or decide pending reviews
agentbrain doctor                 # check setup and print fixes for anything missing
agentbrain vault                  # regenerate the Obsidian Markdown vault
agentbrain mcp                    # run the MCP server (normally started by an agent)
agentbrain hooks install          # install automatic post-commit checkpoints
agentbrain task list / task use <id>
agentbrain agents                 # which agents are installed + session history
agentbrain --help

What's stored

.agentbrain/
├── project.json                      # active task, redaction patterns
├── tasks/<task-id>/
│   ├── task.json                     # objective, status, progress, decisions, ...
│   └── checkpoints/<cp-id>.{json,md} # snapshots + rendered handoffs
└── agents/<agent-id>/sessions/
    ├── <session-id>.json             # start/end, stop reason, checkpoint
    └── <session-id>.prompt.md        # exactly what the agent was given

Plain JSON and Markdown — commit it with the repo to share task state, or add it to .gitignore to keep it local. Checkpoints follow schemas/checkpoint.schema.json.

Secrets are redacted from everything AgentBrain stores (API keys, tokens, private keys, password= values, credentials in URLs). Add project patterns with "redactPatterns": ["..."] in .agentbrain/project.json.

Status

• Tested: the full CLI, Git capture, redaction, instruction files, and run (including auto-handoff) against stub agents that behave like the real CLIs. MCP is tested with stub clients. npm test runs it all.

• Verified live with GitHub Copilot in VS Code: after agentbrain connect, a brand-new chat given only the word "continue" called agentbrain_brief, picked up the task another agent had handed off, recorded its progress and moved it to review. Other agents' MCP configs are written but not yet tried live.

• Not built yet: headless execution over ACP, worktree isolation, agent routing. See SPEC.md for the spec and roadmap.

Development

npm test         # type-checks, then runs unit + end-to-end tests
npm run smoke    # full CLI workflow in a throwaway repo

License

MIT