Quick Start
Six tools. One loop. Safer AI code.
Step 1: Install
Pick your editor and add the MCP server config:
.cursor/mcp.json
{"mcpServers": {"agentbrain": {"command": "npx","args": ["-y", "@agentbrain/mcp-server"],"env": {"AGENTBRAIN_API_KEY": "your-api-key"}}}}Restart your editor. The API key is optional for core features. Get a free key to unlock postflight_check and Playbook.
Step 2: Load context
At the start of every session, tell your agent:
First run takes 2-3 minutes to generate context. Every session after is instant.
Step 3: Run preflight before task
Before any feature, run preflight_check. Loads context, Playbook, and spec in one call:
preflight_check({ repo_path: "/path/to/repo", task: "add OAuth login" })
Step 4: Agent codes
Your agent builds the feature with full context. It knows your folder conventions, protected files, test strategy, and design decisions.
Step 5: Run postflight after agent codes
After the agent finishes, run postflight_check. It analyzes what changed and returns a verdict:
postflight_check({ repo_path: "/path/to/repo", task: "add OAuth login" })
Returns: SAFE, REVIEW, BLOCK, or ERROR.
Step 6: Merge or fix
Based on the verdict:
SAFE: Merge with confidence
REVIEW: Check warnings before merging
BLOCK: Critical violation — fix before merging
Documentation
AgentBrain is a merge gate for AI-generated code.
It works as an MCP server — drop it into Cursor, Windsurf, Claude Code, or VS Code and your agent gets 6 tools for context loading, pre-flight checks, and post-flight validation.
No API key required for core features
Add an API key for postflight_check and Playbook.
New to AgentBrain?
Start by installing the MCP server, then set up your Playbook to define how your team builds.
Installation
.cursor/mcp.json
{"mcpServers": {"agentbrain": {"command": "npx","args": ["-y", "@agentbrain/mcp-server"],"env": {"AGENTBRAIN_API_KEY": "your-api-key"}}}}Restart your editor. AgentBrain tools appear in the tool list immediately.
Want postflight checks and team Playbook?
Get a free API key to unlock postflight_check (the merge gate) and your team Playbook.
Get API key →MCP Tools
postflight_check
Your merge gate — run this after EVERY agent task
Run after your agent finishes any task. Checks what the agent actually did against your Guardrails, Standards, and Spec. Returns a verdict: SAFE, REVIEW, or BLOCK. This is your merge gate for AI-generated code.
Parameters
repo_path: string
Absolute path to repository
task: string
What the agent just did. e.g. "add OAuth login", "refactor auth module"
spec_id: string (optional)
Spec ID if you want to check against a specific spec
What it checks
Protected file violations (BLOCK): Did the agent touch files marked as protected in your Guardrails?
Sensitive data exposure (BLOCK): Did the agent add secrets, API keys, or PII to the code?
Spec compliance (FAIL): Did the agent implement what the spec asked for? Did it avoid what the spec said not to touch?
Standards compliance (WARN): Did the agent follow your test strategy, PR requirements, and code style?
Scope creep detection (WARN): Did the agent modify files unrelated to the task?
Example output
Verdict: REVIEW Protected files: ✓ None modified Sensitive data: ✓ No leaks detected Spec compliance: ✗ Missing error handling for webhook failures Standards: ⚠ No tests for new OAuth flow Scope creep: ✓ Only auth files modified Action: Fix spec failures and add tests before merging.
Verdict table
| Verdict | Meaning |
|---|---|
| SAFE | All checks passed. Safe to merge. |
| REVIEW | Warnings detected. Review before merging. |
| BLOCK | Critical violation. Fix before merging. |
| ERROR | Check failed to run. Investigate. |
preflight_check
Run this before EVERY task
Loads everything your agent needs in one call: codebase context, workspace Playbook (Blueprint, Guardrails, Standards, Decisions), and active spec (if any). Returns a targeted briefing filtered for your specific task.
Parameters
repo_path: string
Absolute path to repository
task: string (optional)
What you're about to do. e.g. "implement Stripe webhook handler", "refactor auth module"
Used to filter relevant context from your codebase, Playbook, and specs
What it loads
Codebase context: Architecture, patterns, schema, dependencies, inventory
Playbook: Blueprint (folder conventions), Guardrails (protected files), Standards (test strategy), Decisions (tech choices)
Active spec: Current task requirements (if you have one in_progress)
Example
preflight_check({ repo_path: "/Users/you/myapp", task: "add GitHub OAuth" })
Why use this instead of individual tools?
preflight_check replaces calling load_context, load_blueprint, load_guardrails, load_standards, load_decisions, and load_spec separately. It loads everything in one parallel call and filters results for your specific task.
load_context
Load codebase context from .agentbrain/ directory. Returns architecture, patterns, schema, dependencies, and inventory.
Parameters
repo_path: string
Absolute path to repository
full: boolean (optional)
Load all context files (default: false, returns slim summary)
files: string[] (optional)
Load specific files only (e.g. ["schema.md", "patterns.md"])
force_refresh: boolean (optional)
Force regeneration even if cache is valid (default: false)
First time setup
If .agentbrain/ doesn't exist, load_context returns setup instructions. Follow them to generate your first context files.
Note
Most users should use preflight_check instead, which calls load_context + Playbook + spec in one shot.
load_spec
Load spec for the current task. With AGENTBRAIN_API_KEY set, fetches from cloud. Without, reads from .agentbrain/specs/ on disk.
Parameters
id: string (optional)
Fetch by public_id (exact match)
search: string (optional)
Partial match on title or slug. e.g. "stripe" matches "add-stripe-billing"
group: string (optional)
Fetch all specs in this group slug
all: boolean (optional)
Fetch all specs assigned to you
repo_path: string (optional)
If provided, caches fetched spec to disk at .agentbrain/specs/
Default behavior
If you call load_spec() with no parameters and have an API key, it returns your in_progress spec (if any).
detect_doom_loop
Detect doom loops by analyzing git history. Returns files appearing repeatedly in recent commits — a signal that your agent is stuck thrashing the same files.
Parameters
repo_path: string
Absolute path to repository
commit_count: number (optional)
Number of recent commits to analyze (default: 10)
threshold: number (optional)
Minimum commits for a file to be flagged (default: 4)
When to use
Run this when you notice your agent repeatedly changing the same files across multiple commits. It helps identify when to step back, review your approach, or simplify the spec.
save_handoff
Save a session handoff document to .agentbrain/handoff.md. Use this at the end of a session to document what you did, what worked, what failed, and what to try next.
Parameters
repo_path: string
Absolute path to repository
content: string
Full handoff content in markdown format
When to use
Run at the end of any session where you made significant progress or hit blockers. Helps future sessions (or future agents) pick up where you left off.
Playbook
How We Build Here
Your team's Playbook is a single source of truth for how you build software. It has 5 sections that together define your development standards.
The 5 sections
| Section | What it defines |
|---|---|
| Where Things Live | Folder structure, file naming, module organization (Blueprint) |
| How We Build | Code patterns, golden path examples, conventions (Blueprint) |
| What Not To Touch | Protected files, sensitive data, team boundaries (Guardrails) |
| How We Ship | Test strategy, PR requirements, code style (Standards) |
| Why Things Are | Tech choices, rejected alternatives, design decisions (Decisions) |
Set up your Playbook
Fill out your workspace Playbook at useagentbrain.com. Your agent loads it automatically via preflight_check.
Set up Playbook →Context Files
Auto-generated files
These files are generated automatically using AST parsing (tree-sitter). They require zero manual maintenance:
| File | Purpose |
|---|---|
| schema.md | Database models and schema |
| dependencies.md | Package versions from package.json |
| dependency-map.md | Module import relationships |
| inventory.md | Components, hooks, utilities list |
| environment.md | Env vars from .env.example |
| branch-context.md | Git branch + recent commits |
| testing.md | Test file locations |
| run-commands.md | Scripts from package.json |
Interpretive files
These files require human insight to create but are AI-generated once and maintained via git hook:
| File | Purpose |
|---|---|
| context.md | Architecture, modules, data flows |
| patterns.md | Code patterns and conventions |
AGENTS.md
A universal standard file recognized by all AI coding tools. AgentBrain auto-generates an AGENTS.md file in your project root with the 6-tool workflow:
## AgentBrain Context
This repo uses AgentBrain for AI-assisted development.
### Load Context
At the start of EVERY session:
**With MCP (preferred):**
Call load_context with this repo path.
**Without MCP (fallback):**
Read these files:
- .agentbrain/agent-hints.md
- .agentbrain/branch-context.md
- .agentbrain/dependencies.md
- .agentbrain/environment.md
- .agentbrain/inventory.md
### MCP Tools
- preflight_check() — run before every task. Loads all context, Playbook, and active spec in one call.
- postflight_check() — run after every task. Checks agent output against Guardrails, Standards, and Spec. Returns verdict: SAFE, REVIEW, or BLOCK.
- load_context() — codebase context
- load_spec() — current task spec
- detect_doom_loop() — stuck patterns
- save_handoff() — session handoff
### Workflow
1. Session start → load_context()
2. Before ANY task → preflight_check({ repo_path, task: "description" })
3. Agent codes
4. After task → postflight_check({ repo_path, task: "description" })
5. Merge (SAFE), review (REVIEW), or fix (BLOCK)
6. Stuck on bug → detect_doom_loop()
7. Session end → save_handoff()Privacy & Security
What leaves your machine
AgentBrain is privacy-first. Here's exactly what data goes where:
| Data | Where it goes |
|---|---|
| Your code | Never leaves your machine. Stays local in .agentbrain/ |
| Context files | Never leaves your machine. Generated and stored locally |
| Specs | Stored in cloud (optional — only if you use API key) |
| Playbook | Stored in cloud (optional — only if you use API key) |
| postflight analysis | Sends git diff to API for validation (pro feature) |
Privacy mode
Want 100% local? Enable privacy mode to disable all cloud features:
{
"mcpServers": {
"agentbrain": {
"command": "npx",
"args": ["-y", "@agentbrain/mcp-server"],
"env": {
"AGENTBRAIN_PRIVACY_MODE": "true"
}
}
}
}In privacy mode: load_context, load_spec (from disk), detect_doom_loop, and save_handoff work normally. postflight_check and cloud Playbook are disabled.