brain-kit

Your coding agent forgets everything. Make it stop.

One file it reads first and writes last. A crew where no agent grades its own homework.Hooks that make both non-optional.

npx agent-brain-kit setup

Website · The receipts · Hall of Gotchas · A real brain

---

Not a weekend demo

Everything here was extracted from a private fleet that has run it every day since July 2026. Names removed, numbers not (how each was counted):

53	repos running the brain: web apps, a desktop app, firmware, data pipelines, research code, games in four engines
3,142	commits that wrote a brain: about one in three of all commits
~2,600	gotchas written down, each learned the hard way exactly once
57	times an independent QA agent failed work the builder had reported as done
296	reviewer REVISE verdicts, sent back with the exact miss
8,098	tests in the biggest repo, built by the crew

The crew is the part people underestimate. Without it, every one of those 57 failures would have been merged as "done".

---

The problem

If you work with coding agents for any length of time you already know the failure:

• Knowledge scatters across chat sessions and dies with them.
• A chat gets too big, so you write a handover, and the handover is lossy.
• The same investigation gets re-run weeks later, burns tokens, and sometimes returns a different answer than last time.
• The agent says "done, all tests pass", and the thing does not run.

The usual fix is better prompts or a bigger context window. Neither works, because the problem is not recall. It is that nothing durable was ever written down, and nothing independent ever checked the claim.

The fix

1. READ    BRAIN.md, in full, before any work
2. WORK    planner → builder → test-writer → qa → reviewer
3. WRITE   BRAIN.md, before the session ends

Step 3 is the one everybody skips, and skipping it is what makes step 1 worthless. A brain updated usually is worse than no brain, because you cannot trust it, so you re-investigate anyway. Trust requires discipline: read every time, write every time.

The payoff is that handovers stop existing. The brain is the handover, continuously. Start new chats freely; nothing is lost.

A real run, not a mock-up

The animation at the top is an illustration. This one is not. It shows a sample repo, the published package, and one real Claude Code session given only the prompt setup suggests:

The session was asked to fill §1–§2. It also wrote a changelog entry, a "left off" pointer and a fresh date, because the loop in .claude/CLAUDE.md tells every session to. Nobody prompted those. 60 → 85. §5 stays empty until something actually bites, because a gotcha has to be earned. Every line is real output (raw captures); the 74-second session is sped up.

---

Quickstart

One command (recommended)

From the root of any repo:

npx agent-brain-kit setup

  created  BRAIN.md
  created  .claude/CLAUDE.md            brain loop
  created  .claude/agents/              7 agents: builder, explore, planner, qa, researcher, reviewer, test-writer
  created  .claude/hooks/               7 hooks: _json, brain-check, format, guard, notify, secret-scan, subagent-gate
  created  .claude/settings.json        6 hooks wired

  17 created · 0 kept · 0 merged

Next:
  1. Open Claude Code in this repo and ask it to "fill BRAIN.md §1–§2 from the codebase".
  2. Check the brain's health any time: npx agent-brain-kit doctor

It never overwrites a file you already have. Run it twice and everything is kept. An existing settings.json is merged (our hooks added once, nothing of yours removed, a backup kept).

flag	does
--dry-run	print the plan, write nothing
--full	compose the full project constitution instead of just the brain loop
--no-crew	skip the seven agents
--no-hooks	skip the hooks and settings.json

Just the brain (no tooling)

This is most of the value, and it works with any agent:

cp templates/BRAIN.template.md  /path/to/yourrepo/BRAIN.md
cat BRAIN_DISCIPLINE.md      >> /path/to/yourrepo/.claude/CLAUDE.md   # or AGENTS.md, .cursorrules, a system prompt

---

Is your brain healthy? doctor

npx agent-brain-kit doctor

Grades a repo's brain in under a second and prints a one-line fix for every miss: all sections present, §1–§2 actually filled, how fresh "Last updated" is, real gotchas (not template placeholders), a "left off" pointer on the newest changelog entry, an outstanding table that parses, the read-first loop present in CLAUDE.md/AGENTS.md, and the size limits that bite in practice.

  ✔ 15/15  core sections §1–§7 all present
  ✖  0/15  §5 GOTCHAS has no real entry (template placeholders only)
           → record the first thing that cost you an hour — the most valuable section, and the one that is normally lost
  ✔ 15/15  .claude/CLAUDE.md carries the read-first / write-before-ending loop
  ...
  ██████████████░░░░░░░░░░  60/100  needs work  (pass mark 70)

--json for machines. Exits 1 below 70, so it can gate CI. CRLF-safe.

This is the beginning of the README. Read the rest at the original. Read the full README ↗