antibody

Herd immunity for coding-agent fleets. When one agent beats an error, every agent running beside it becomes immune.

Status: M6, fixes that travel between machines. antibody installs as a Claude Code plugin, and antibody setup adds it to Gemini CLI and Codex CLI. Hooks capture errors, claims keep two agents from diagnosing the same new one, and a recorded fix reaches the other sessions in the repository at their next tool call, whichever CLI they run. Five MCP tools let any agent look errors up and record fixes, and antibody watch shows the fleet live, down to each lead's subagents. Fixes reach other clones through a committed file or an optional relay. The benchmark that will measure it is built; its real runs come next, and the roadmap has the rest.

_{The overview in antibody watch, beside four agents in Claude Code, Codex CLI and Gemini CLI, driven through antibody's real hooks. One claims a missing .env while the others hold; once it records the fix, each gets it at its next tool call, and a second error goes the same way.}

At a glance

The problem

Running many coding agents in parallel is now normal. Tools like herdr, vibe-kanban, superset, claude-squad and paperclip will happily start eight Claude Code, Codex and Gemini CLI sessions on one repo, each in its own git worktree.

Then all eight hit the same wall. A fresh worktree has no .env. The generated Prisma client is missing. Playwright has no browsers. Port 3000 belongs to another agent's dev server. Someone changed package.json and the lockfile is stale. Each agent diagnoses the same failure on its own, from scratch, and each diagnosis costs 800 to 3,000 tokens of thinking and trial.

The bigger the fleet, the more you pay for the same answer. Nothing in the current tools passes a fix from one running agent to the next.

What antibody does

antibody is a small layer that sits underneath whatever runs your agents. It does not start agents, manage worktrees or plan tasks. It watches for errors and moves fixes between agents.

1. Capture. A hook fires when a tool call fails. antibody normalizes the message (ports, paths, timestamps and ids become placeholders) and turns it into a 12-character fingerprint, so every agent's copy of an error matches.
2. Claim. The first agent to hit a new fingerprint claims it. An agent that hits the same error while the first is still working on it is told a peer is already on it, instead of starting a second diagnosis.
3. Store. When the claimant gets past the error, its fix goes into shared memory: a redacted, human-editable ANTIBODIES.md plus an event log.
4. Inject. Every agent that hits that fingerprint afterwards gets the fix pushed into its context through the harness's own hook, capped at 120 tokens, before it starts guessing.

sequenceDiagram
    participant A as claude-1
    participant M as antibody memory
    participant B as codex-2
    participant C as gemini-1
    A->>M: ECONNREFUSED 127.0.0.1:<port> (new fingerprint)
    M-->>A: opens E-0001, claimed by claude-1
    B->>M: same fingerprint
    M-->>B: claude-1 is already diagnosing this
    A->>M: fixed: docker compose up -d db
    M-->>B: fix from claude-1 (96 tokens)
    C->>M: same fingerprint, ten minutes later
    M-->>C: fix injected, solved in one step

Shared memory lives in the repository's common git directory (git rev-parse --git-common-dir), which every worktree of the repo already shares. It needs no server, no database and no configuration, and it is never committed unless you export it.

Setup fixes up front, if you want them. With ANTIBODY_BROADCAST=1 in the agents' environment, a session that starts gets the memory's setup fixes before it does anything: a missing .env, browsers the test runner never downloaded, an ungenerated client, dependencies not installed, a stale lockfile. They arrive as one block of at most 300 tokens, the most hit first, and only trusted fixes are sent, never one waiting for your review. A fix counts as setup when its error reads like something a fresh checkout is missing, or the fix installs, generates, copies a .env or starts a service. It is off by default until the benchmark shows it saves more than it costs.

Where it sits

flowchart TB
    subgraph fleet["Any orchestrator, or a few terminals"]
        A["Claude Code<br/>a lead and its subagents"]
        B["Codex CLI<br/>worktree b"]
        C["Gemini CLI<br/>worktree c"]
    end
    M[("antibody memory<br/>in .git, shared by every worktree")]
    A --> M
    B -- "hooks: errors in, fixes out" --> M
    C --> M
    W["antibody watch"] -. reads .-> M
    M <-- "relay sync, optional" --> R["antibody relay<br/>other machines"]
    M -- "antibody export" --> F["ANTIBODIES.md<br/>committed, for other clones"]

antibody only touches the agents' own hooks and its memory. Starting agents, worktrees and tasks stay with whatever runs them.

Install in Claude Code

antibody needs Node.js 22.13 or newer, first on your PATH or named by ANTIBODY_NODE (see below). In Claude Code:

/plugin marketplace add Shyboy0499/antibody
/plugin install antibody@antibody

Then restart Claude Code. The plugin is the repository itself: its hooks run the committed dist/antibody.mjs, so there is nothing to build. From then on every session in every git repository takes part. Sessions in different worktrees of one repository share a memory, and sessions in different repositories do not.

A project that pins an older Node through mise, asdf, nvm or volta puts that Node first on PATH inside the project, and the hooks would start under it. They start through hooks/launch.cjs, which older Node versions can still read: on one of those it hands over to the binary named by ANTIBODY_NODE. Without one it writes the reason to stderr and exits quietly, so the session carries on but antibody, its MCP tools included, is off in that project. Point it at a Node 22.13 or newer, for example in your shell profile:

export ANTIBODY_NODE=<path>/node

What happens next is automatic:

• A tool call fails. The hook fingerprints the error. If it is new, this session claims it and records it in ANTIBODIES.md, and the agent sees nothing.
• Another session hits the same error. If the first is still on it, the second is told who is diagnosing it, and waits for the fix instead of starting over. If a fix is known, it is pushed into the agent's context, within 120 tokens.
• The agent gets past the error. antibody notices the next comparable call succeed, or the same command fail on a different error, and asks once for the fix, which the agent records with antibody_record. The sessions that were waiting get it at their next tool call.

antibody says at most one thing per tool call and three per turn. In a long turn, such as a headless run, the three start again every ten tool calls. Telling an agent that a peer is on its error, and then handing it the peer's fix, never counts against the three. A request for a fix that could not be sent yet waits for the next call.

The MCP server gives every session five tools: antibody_lookup, antibody_record, antibody_list, antibody_forget and antibody_stats. The memory is plain files you can read and edit:

cat "$(git rev-parse --git-common-dir)/antibody/ANTIBODIES.md"

A hook never blocks or breaks a session. Outside a repository, on any error, or past three seconds it prints nothing. Set ANTIBODY_DEBUG=1 to see why on stderr.

Measured

scripts/e2e.mjs runs the M2 check against the committed bundle, the way Claude Code calls it, and CI runs it on every push. Two sessions in two worktrees hit the same missing-.env error. The fix the first session records reaches the second on its next tool call: 48 ms later on a GitHub Actions runner, and about 65 ms later in the development container. It then plays the same exchange between Claude Code, Gemini CLI and Codex CLI agents in all six directions, and each fix arrives about 50 ms after it is recorded.

Each hook call is a separate Node.js process, so most of its cost is starting one. A hook loads nothing beyond Node's own start-up: it starts no git process, hashes in plain JavaScript instead of loading node:crypto, and keeps the streams stack out. The median hook call takes:

The roadmap's target is under 50 ms per call. On the runner every kind of call meets it; in the development container a failing call is still about 10 ms over.

antibody stats and antibody watch count a reused fix at what its diagnosis was measured to cost. When an agent records a fix, antibody reads the claimant's own transcript (every supported CLI names it in its hook calls) and adds up the tokens the model newly read or wrote between the claim and the fix, leaving out the context it re-read from its prompt cache. Where there is no transcript to read, a diagnosis is assumed to cost 800 tokens, and both commands say how many costs were measured.

Install in Gemini CLI and Codex CLI

Neither CLI can share this repository as a plugin, so antibody setup writes antibody into their own settings. Clone the repository anywhere, then run setup for each CLI you use:

git clone https://github.com/Shyboy0499/antibody ~/.local/share/antibody
node ~/.local/share/antibody/dist/antibody.mjs setup gemini   # ~/.gemini/settings.json
node ~/.local/share/antibody/dist/antibody.mjs setup codex    # ~/.codex/hooks.json

• Gemini CLI gets hooks on SessionStart, BeforeAgent, AfterTool, SessionEnd, AfterAgent and Notification, plus the MCP server. Restart Gemini CLI to load them.
• Codex CLI gets hooks on SessionStart, UserPromptSubmit, PostToolUse, SessionEnd, Stop and PermissionRequest. Codex runs new hooks once you trust them in /hooks, and setup prints the codex mcp add command for the MCP server. Codex gives a hook a shell command's output but not its exit code, so antibody counts a command as failed only when its output ends in an error line, and never for commands that only display text (cat, grep, git log and the like).

The hooks and the MCP server start through hooks/launch.cjs, as Claude Code's do, so a project that pins an older Node needs ANTIBODY_NODE here too (see Install in Claude Code). Run setup again after moving the clone, after updating it (a newer antibody may hook more events), or to move hooks written by an older setup over to the launcher. --remove takes antibody out again, --print shows the result without writing it, and a settings file with comments is never rewritten.

Other agents

Any agent that speaks MCP can use the tools. It pulls fixes instead of having them pushed. Point it at the server, named after the agent:

{
  "mcpServers": {
    "antibody": {
      "command": "node",
      "args": ["/path/to/antibody/hooks/launch.cjs", "mcp", "cursor"]
    }
  }
}

and add one line to the project's AGENTS.md:

When a command fails with an error you have not seen, call antibody_lookup before
diagnosing it; when you get past it, record the fix with antibody_record.

The server finds the repository from the directory it starts in, so configure it per project.

See it

antibody watch is the live fleet view, in your terminal next to the agents. Run it from any worktree of the repository, with the bundle from your clone:

node ~/.local/share/antibody/dist/antibody.mjs watch

It opens on a dashboard of the agents, laid out the way Grok Build's agent dashboard is. The agents are grouped by what they need from you: needs you (it finished its turn, or asked for your permission), working (diagnosing an error it claimed, holding for a peer's fix, just made immune by one, or at work), idle (five quiet minutes) and done (a subagent that handed its work back). Each row says what the agent is on, what it is doing and how long ago it was last seen. Up and down pick an agent, and the panel below peeks at it: its task, its lead or its team, and its latest events. antibody only watches, so the peek shows what happened and does not answer the agent; it gives the turn-end and permission hooks no answer either.

Tab switches to the overview: every agent's state, the tokens saved and the re-diagnoses avoided, every antibody with its fix and who found it, how many imported entries wait for your review, and the events as they happen. Both redraw twice a second, in place, on the terminal's alternate screen.

antibody watch --once prints a single frame for a pipe, sized by COLUMNS and LINES (--overview starts on, or prints, the overview), and antibody stats prints the ledger as text for scripts and CI.

A diagnosing agent's row carries a bar against how long a diagnosis usually takes in this memory, once three were timed. To see what each agent is working on, set ANTIBODY_WATCH_TASKS=1 in the agents' environment: the first line of each prompt, redacted and cut to 80 characters, is written to the memory's event log, and watch shows it as the agent's task. It is off by default, because a prompt is the user's own words; the event log never leaves the machine, and an export never carries it.

A team of agents

In Claude Code, watch also shows who works for whom. A session started as one of your agents, claude --agent ceo, is named after it (ceo@shop), and each subagent it hands work to gets its own row, named by its type and marked with the lead it works for. Peeking at the lead shows its team and their events together; the overview draws the subagents as a tree under their lead.

_{A ceo session in Claude Code hands work to a frontend, a tester and a reviewer, while Codex CLI and Gemini CLI work in their own worktrees, all driven through antibody's real hooks. The tester claims a missing Playwright browser while Codex holds; its fix reaches Codex at its next tool call. The CEO asks for permission, its subagents hand their work back, and it waits for you.}

An error a subagent hits is credited to it, and so is the fix it records; a subagent shows as done once it hands its work back. antibody logs only each subagent's name and when it started and finished, never what it said. It shows the team and does not run it: you still give the work to the lead. A subagent that starts another is listed under the same lead, because Claude Code says which session a subagent works in, not which agent started it. antibody keeps its memory in a git repository, so for a team that does not work on code, start Claude in a folder made with git init and run watch there.

demo/index.html is a simulated run of the same screen with eight agents. Open it in a browser and press m to turn shared memory off: the fleet goes back to paying for the same diagnosis over and over.

Share fixes with your team

The memory lives inside .git, so a teammate's clone, or a cloud agent's, starts without it. Fixes travel in a file you commit:

antibody export                  # write the fixes this fleet found to ANTIBODIES.md
git add ANTIBODIES.md && git commit -m "Share antibody fixes"

In another clone of the repository:

antibody import                  # read ANTIBODIES.md into this clone's memory
antibody review                  # read what came in
antibody allow --all             # or: antibody allow E-0004, antibody reject E-0005

A clone's first session runs the import on its own when the clone has no memory yet and the repository commits ANTIBODIES.md, and tells its agent that a person must review what came in. ANTIBODY_AUTO_IMPORT=0 turns that off.

What leaves. Only an entry with a working fix that was found in this repository. Entries without a fix, wontfix entries and fixes still waiting for review stay behind. Every text is redacted again, in case the file was edited by hand since, and the notes are left out.

What comes in is held back. The file is text someone else wrote, so an imported entry is held for review: agents are shown neither its fix nor its title, trigger or sample. An agent that meets the same error is told "seen before, no fix recorded yet", claims it and diagnoses it as usual. A fix an agent records itself is trusted at once, because it was found in this fleet. Importing never replaces a fix this memory already has, and never adds more entries than the memory has room for. antibody review strips control, zero-width and direction-changing characters, and the invisible tag characters that can hide text from a reader, from everything it prints.

Share through a relay

Cloud agents start in fresh containers, and a committed file only moves when someone commits it. A relay moves fixes as they are found: a small HTTP service that every machine's memory syncs through.

# Somewhere every agent can reach, speaking HTTPS. One secret per machine,
# separated by commas, each named; to revoke one, remove it and restart:
ANTIBODY_RELAY_TOKEN=laptop=<a long secret>,ci=<another long secret> \
  antibody relay serve --host 0.0.0.0 --cert <path>/cert.pem --key <path>/key.pem

# In each agent's environment, with that machine's own secret:
ANTIBODY_RELAY=https://relay.example.com
ANTIBODY_RELAY_TOKEN=<this machine's secret>
ANTIBODY_RELAY_TRUST=fleet       # only when every machine with the token is yours

The agents' MCP server then syncs while it runs: as it starts, every 30 seconds, and as it stops. Hooks never touch the network. antibody relay sync syncs by hand.

A name before a secret, as in laptop=<secret>, names that machine: up to 32 letters, digits, dots, dashes or underscores. The relay marks each fix with the name of the machine that pushed it, from its token, so no machine can claim another's name, and a machine that pulls the fix shows where it came from: antibody watch as laptop (relay) in the antibodies pane, and antibody review on its own line. A bare secret works as before, without a name.

Every request carries a machine's token, so a relay that machines reach over a network needs TLS. --cert and --key take a PEM certificate (chain) and its private key, and the relay speaks HTTPS itself. Without them it speaks plain HTTP, which suits a relay behind a proxy that terminates TLS, and it warns when it listens beyond the machine itself. A machine trusts the relay's certificate as it trusts any HTTPS site; for a self-signed one, point NODE_EXTRA_CA_CERTS at the certificate in each agent's environment. A sync that does not trust it fails and says why.

To remove a bad fix, the owner starts the relay with a secret of its own in ANTIBODY_RELAY_ADMIN_TOKEN and calls DELETE /v1/fixes/<fingerprint> with it. The fingerprint is then blocked, so a machine that still has the fix cannot push it back. A machine clears its copy at its next sync, whether the fix was applied or waits for review. A fix it has changed since is kept, since that is no longer the relay's copy.

• What the relay holds: what export lets leave a machine, which is entries with a working fix, redacted again, without notes. It keeps the latest fix for each error, in one JSON file.
• What comes back: by default, what a machine pulls is held for review, as an import is. With ANTIBODY_RELAY_TRUST=fleet, every machine holding the token is trusted as one fleet, and an agent meeting the error is given the fix at once. Either way, a pulled fix never replaces one the machine has.
• Limits: the token must be 16 characters or more, a push is limited in size, and a relay holds at most 5,000 fixes. A machine sends only what changed since its last sync, and never pushes back what it pulled. Each token may make 300 requests a minute, 60 of them pushes, and each address 30 requests with a missing or wrong token; past a limit the relay answers 429 with Retry-After. Behind a proxy every request comes from the proxy's address, but a good token is never refused for another client's wrong ones.

Works with

The Gemini CLI and Codex CLI adapters were written against the payloads in each CLI's own source (Gemini CLI 0.62.0, Codex CLI 0.160.1), and the end-to-end check plays those payloads in every direction. All three were then run live (Claude Code 2.1.303, Gemini CLI 0.64.0, Codex CLI 0.163.0) against a stand-in for each model API, in scripts/step0: every hook fired as expected, and a fix recorded through one CLI reached the model of each of the others.

All three read the same failure rule, src/failure-hints.ts: a shell result that names no exit code - or names a zero only a pipeline's last stage earned - is a failure when the command is not one that only displays text and its output ends on an error line. That is what catches npm test 2>&1 | tail -15, whose exit status belongs to tail.

It works under any orchestrator, because it only needs the agents' own hooks: herdr, vibe-kanban, superset, claude-squad, agent-orchestrator, paperclip, or plain git worktree add and a few terminals. Using antibody under an orchestrator has a note on each.

What works today

Built on dsh-errkb

antibody's core came from dsh-errkb, an error knowledge base for a single DeepSeek Harness agent. Its pure layer (fingerprinting, redaction, the markdown store, matching, capture, notices, fix trust, state and resolution detection) came over with its tests and keeps its MIT notice in NOTICE. antibody replaced the single-harness wiring with what a fleet needs: the shared memory directory, the event log and claims.

Development

Node 22.13 or newer and pnpm 11.

pnpm install
pnpm test            # vitest with the 99% statements and lines gate
pnpm run typecheck
pnpm run lint
pnpm run format:check
pnpm run build       # lib/ and the dist/antibody.mjs bundle, via tsdown
pnpm run e2e         # the M2 exchange end to end, plus hook latency
pnpm run bench       # the benchmark; see bench/README.md

dist/antibody.mjs is committed, because Claude Code runs the plugin straight from git. CI fails when a source change is pushed without the rebuilt bundle.

A release is a version tag: pushing v0.1.0 runs the checks and publishes the package to npm as antibodies (npm has antibody taken), from .github/workflows/release.yml. The command stays antibody. CHANGELOG.md lists what each version holds.

CI runs all of these on every push and pull request, plus a privacy guard that rejects personal paths, private e-mail addresses and credential-shaped tokens. See CONTRIBUTING.md before opening a pull request.

Documents

• Design: how capture, claims, storage, injection and the fleet view work, plus failure modes and open questions
• Landscape: the October 2026 survey of about 40 multi-agent and agent-memory projects, and the gaps it found
• Roadmap: milestones from the core port to a published benchmark
• Integrations: using antibody under herdr, vibe-kanban, superset, claude-squad, agent-orchestrator and paperclip

Star history

License

MIT. Code ported from dsh-errkb keeps its own MIT notice; see NOTICE.