✓ Copied to clipboard
◆

AgentBrain

how it worksmcp
github

v1.4.20 · live on npm

Your agent doesn't know your codebase. Doesn't follow a plan.Can't tell when it's stuck.

One command fixes all three. Works with Claude Code, Cursor, and Windsurf.

$npx agentbrain setup

free · byok · any repo

01 / full setup

Scans your repo, generates three context docs, injects them into your agent files, and installs a git hook. One time.

$npx agentbrain setup

output

$ npx agentbrain setup

scanning 1,223 files... selected 183 relevant files summarising in parallel... ✓ .agentbrain/context.md ✓ .agentbrain/dependency-map.md ✓ .agentbrain/patterns.md ✓ CLAUDE.md · .cursorrules · .windsurfrules ✓ git hook installed 💸 $0.33 · 94 seconds · never again

02 / spec-driven dev

Five questions. One spec file. Your agent reads it before touching any code. No more vague asks, no more wrong implementations.

$agentbrain spec "add stripe webhook"

output

$ agentbrain spec "add stripe webhook"

Q1: What problem does this solve? Q2: What's your approach? Q3: What should the agent NOT touch? Q4: What does done look like? Q5: Any edge cases or risks? ✓ .agentbrain/specs/add-stripe-webhook.md ✓ CLAUDE.md updated with spec reference 💸 $0.0004 · your agent reads this first

03 / doom loop detector

Detects when your agent is stuck touching the same files repeatedly. Flags it before you waste another hour going in circles.

$agentbrain doom

output

$ agentbrain doom

analyzing last 10 commits...
⚠ Possible doom loop detected
billing.service.ts 6 commits · 60% auth.service.ts 4 commits · 40% → Stop coding. Investigate root cause. 💸 $0.00 · pure git analysis

04 / auto refresh

The git hook fires on source file changes, updates context in the background, never blocks your commit. Smart cache means most runs cost $0.00.

$git commit -m "feat: add flag type"

output

$ git commit -m "feat: add flag type"

[main d9b26430] feat: add flag type 1 file changed 🧠 AgentBrain: updating context...
# 25 seconds later, in the background: ✓ 12:29:56 | Git: d9b26430 | SUCCESS | 25s commit took 0.058s · context updated silently

05 / health check

11 checks in parallel. Validates your key, hook, cache, context freshness, and all agent files. Run it when something feels off.

$agentbrain doctor

output

$ agentbrain doctor

✓ api_key anthropic detected ✓ git_hook installed · post-commit ✓ cache_valid matches HEAD: d9b2643 ✓ context_freshness 0 hours ago ✓ agent_files CLAUDE.md · .cursorrules · .windsurfrules ✓ hook_log 2 updates · last: success Score: 11/11 checks passed

05 / mcp server

For agents that call tools, not just read files.

Connect the MCP server and your agent pulls context on demand. Required for Claude Desktop. Recommended alongside the CLI for Cursor and Windsurf.

claude_desktop_config.json

{
  "mcpServers": {
    "agentbrain": {
      "command": "npx",
      "args": ["-y", "@agentbrain/mcp-server"]
    }
  }
}

tools

cli pathyour anthropic/openai key · ~$0.33 first run · $0.00 cached

mcp pathuses your existing claude/cursor subscription · no api key needed

core

load_context

Full codebase context at session start

core

load_standards

Your coding standards mid-session

core

save_handoff

Session handoff at end of session

new

load_spec

Load spec file for current task

new

detect_doom_loop

Check git history for stuck patterns

free

scan_repo

Repo structure scan. No API key needed.

works with

Claude Code

CLAUDE.md

Cursor

.cursorrules

Windsurf

.windsurfrules