Command-line interface for AgentBrain. Automatically generates and maintains context documentation that helps coding agents (Claude, Cursor, Windsurf) understand your codebase instantly.

Installation

Global Installation (Recommended)

npm install -g @agentbrain/cli

Local Installation

npm install --save-dev @agentbrain/cli

Verify Installation

agentbrain --version

Quick Start

One-Command Setup

cd /path/to/your/project
agentbrain setup

That's it! AgentBrain now:

✓ Generates context automatically on every commit
✓ Injects loading instructions into your agent files
✓ Detects and warns about doom loops
✓ Keeps everything in sync with your codebase

What Gets Created

.agentbrain/context.md - Full repository intelligence
.agentbrain/dependency-map.md - Service relationships
.agentbrain/patterns.md - Coding patterns and conventions
CLAUDE.md / .cursorrules / .windsurfrules - Agent loading instructions
.git/hooks/post-commit - Smart auto-regeneration hook

Core Concepts

Smart Context Generation

AgentBrain analyzes your codebase and generates three intelligence documents:

Context - Architecture, key files, and technical overview
Dependency Map - How services/modules relate to each other
Patterns - Coding patterns, conventions, and best practices

Automatic Regeneration

After setup, context updates automatically in the background when you commit source file changes. Commits complete instantly (~0.05s) while regeneration happens in the background.

Smart Filtering: Only regenerates when source code changes (skips docs/config updates to save time and API costs).

Doom Loop Detection

AgentBrain automatically detects when you're modifying the same files repeatedly in commits - a sign you may be stuck in a loop. When detected:

⚠ Warning displayed on next CLI command
🔔 Alert included in MCP tool responses
📝 Appended to handoff documents
💡 Suggests running agentbrain spec to plan a fix

Check manually:

agentbrain doom

Commands

`setup` - Complete Automated Setup

One-command setup for AgentBrain in your repository.

agentbrain setup [options]

Options:

--path <path> - Repository path (default: current directory)
--skip-hooks - Skip git hooks installation
--skip-agent-files - Skip agent file injection
--no-confirm - Skip all confirmation prompts

What it does:

Detects which agents you use (Claude Code, Cursor, Windsurf)
Generates initial context documentation
Injects context loading instructions
Installs smart git hooks
Sets up doom loop detection

Cost: ~$0.02-0.05 for initial generation (cached repeats are free)

`init` - Regenerate Context

Manually regenerate all context documentation.

agentbrain init [options]

Options:

--path <path> - Repository path
--no-confirm - Skip confirmation prompt
--silent - Suppress output (for scripts)

Use when:

You want to force a fresh regeneration
Context feels stale or inaccurate
After major codebase changes

Cost: ~$0.02-0.05 per regeneration (same git hash = free from cache)

`spec` - Create Task Specifications

Generate AI-guided task specifications with problem analysis and architecture planning.

agentbrain spec "<task description>" [options]

Options:

--path <path> - Repository path
--load <slug> - Load existing spec by slug

Examples:

# Create new spec
agentbrain spec "add user authentication with OAuth"

# Load existing spec
agentbrain spec --load add-user-authentication

What it creates:

Problem analysis and context
Technical approach and architecture
Implementation steps
Testing strategy
Done criteria

Specs are saved to: .agentbrain/specs/<task-slug>.md

Cost: ~$0.01-0.03 per spec generation

`doom` - Detect Doom Loops

Analyze git history to detect if you're modifying the same files repeatedly.

agentbrain doom [options]

Options:

--path <path> - Repository path
--commits <n> - Number of recent commits to analyze (default: 10)
--threshold <n> - Minimum occurrences to flag (default: 4)
--json - Output as JSON for programmatic use

Example Output:

Analyzing last 10 commits...

⚠ Doom loop detected!

These files appear repeatedly:
  apps/api/src/main.ts (9 times · 90%)
  apps/api/src/auth.ts (6 times · 60%)

Suggestions:
  → Stop coding. Investigate root cause first.
  → Run: agentbrain spec "fix [problem description]"

Automatic Detection: After commits, doom detection runs in the background. Warning shown on next command if detected.

`doctor` - Health Diagnostics

Run health checks on your AgentBrain setup.

agentbrain doctor [options]

Options:

--path <path> - Repository path
--json - Output as JSON

Checks:

✓ Git repository status
✓ Context files exist and are valid
✓ Agent files are configured
✓ Git hooks installed correctly
✓ API configuration

Use when:

Setup isn't working as expected
Context generation fails
Git hooks not firing

`status` - Auto-Update Status

View status of background context updates.

agentbrain status [options]

Options:

--path <path> - Repository path

Shows:

Recent update history from .agentbrain/update.log
Success/failure status
Update duration
Git hash for each update

`standards` - Generate Coding Standards

Generate coding standards documentation based on your codebase patterns.

agentbrain standards [options]

Options:

--path <path> - Repository path

Creates: .agentbrain/standards.md

Cost: ~$0.01-0.02 per generation

`handoff` - Generate Session Handoff

Generate session handoff document with recent changes and context.

agentbrain handoff [options]

Options:

--path <path> - Repository path
--goal <goal> - Session goal (optional)
--commits <n> - Number of recent commits (default: 5)

Creates: .agentbrain/handoff.md

Includes:

Recent changes summary
Session context
Next steps recommendations
⚠ Doom loop warning (if detected)

Cost: ~$0.01-0.02 per generation

`config` - Configure API Settings

Configure AI provider API keys and settings.

agentbrain config

Interactive setup for:

Provider selection (OpenAI, Anthropic, or both)
API key configuration
Model selection

Supports:

OpenAI (GPT-4, GPT-4 Turbo)
Anthropic (Claude 3.5 Sonnet, Claude 3 Opus)

`disable` - Disable AgentBrain

Disable AgentBrain features in your repository.

agentbrain disable [options]

Options:

--path <path> - Repository path
--remove-hooks - Remove git hooks
--remove-agent-files - Remove agent file modifications

Use when:

Temporarily disabling automation
Troubleshooting issues
Removing AgentBrain from project

Note: Does not delete .agentbrain/ directory or context files.

MCP Integration

AgentBrain provides a Model Context Protocol (MCP) server that enables AI agents to access repository intelligence directly.

Install MCP Server:

npm install -g @agentbrain/mcp-server

See: @agentbrain/mcp-server for setup instructions.

MCP Tools Include Doom Warnings:

load_context - Returns doom_warning field if loop detected
load_spec - Returns doom_warning field if loop detected
save_handoff - Appends doom section to handoff document

Troubleshooting

Context Not Regenerating on Commits

Check git hooks:

agentbrain doctor

Verify hook is installed:

cat .git/hooks/post-commit
# or for Husky:
cat .husky/post-commit

Reinstall hooks:

agentbrain disable --remove-hooks
agentbrain setup

Hook Errors After Commits

Check update log:

cat .agentbrain/update.log

Common issues:

API key not configured: Run agentbrain config
Permission errors: Check file permissions on .agentbrain/
Path issues: Hook uses fallback paths to find agentbrain binary

Context Feels Stale

Force regeneration:

agentbrain init --no-confirm

Check cache: Cache is tied to git hash. If you haven't committed changes, old cache is used.

Doom Loop False Positives

Adjust sensitivity:

# Check last 15 commits, flag if file appears 6+ times
agentbrain doom --commits 15 --threshold 6

Excluded patterns:

Lock files (package-lock.json, etc.)
AgentBrain files (CLAUDE.md, .cursorrules, etc.)
Markdown files

API Costs Too High

Smart regeneration already optimized:

Only regenerates on source file changes
Skips docs/config updates
Caches by git hash

Further reduce costs:

Use --skip-hooks during development sprints
Manually regenerate only when needed: agentbrain init
Disable temporarily: agentbrain disable

Husky Compatibility

AgentBrain detects and supports Husky automatically.

Husky v9+ (recommended): Hook installs directly to .husky/post-commit

Custom hook paths: Detects git config core.hooksPath and installs there

No conflicts: AgentBrain hook runs alongside existing hooks

Files & Directories

Generated Files

.agentbrain/
├── context.md              # Full repository intelligence
├── dependency-map.md       # Service relationships
├── patterns.md             # Coding patterns
├── standards.md            # Coding standards (optional)
├── handoff.md             # Session handoff (optional)
├── update.log             # Auto-update history
└── specs/                 # Task specifications
    └── <task-slug>.md

Agent Files (Modified)

CLAUDE.md - Claude Code loading instructions
.cursorrules - Cursor loading instructions
.windsurfrules - Windsurf loading instructions

Git Hooks

.git/hooks/post-commit - Standard installation
.husky/post-commit - Husky installation

Best Practices

When to Use AgentBrain

✅ Good for:

Active development with AI assistants
Onboarding new developers
Complex codebases with multiple services
Keeping AI agents in sync with changes

❌ Skip if:

Early prototyping (context not stable yet)
API costs are a major concern
Repository is < 10 files

Workflow Tips

Initial setup: Run agentbrain setup once
Let automation work: Commits regenerate context automatically
Check doom warnings: If shown, investigate before continuing
Use specs: Plan complex tasks with agentbrain spec
Handoff cleanly: Generate handoff at session end

Cost Management

Initial setup: ~$0.02-0.05
Auto-regeneration: ~$0.02-0.05 per commit (only on source changes)
Specs: ~$0.01-0.03 each
Expected monthly cost: $1-5 for typical projects

License

Keywords

FAQs

What is @agentbrain/cli?

Is @agentbrain/cli well maintained?

Package last updated on 07 Apr 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@agentbrain/cli

@agentbrain/cli

Installation

Global Installation (Recommended)

Local Installation

Verify Installation

Quick Start

One-Command Setup

What Gets Created

Core Concepts

Smart Context Generation

Automatic Regeneration

Doom Loop Detection

Commands

setup - Complete Automated Setup

init - Regenerate Context

spec - Create Task Specifications

doom - Detect Doom Loops

doctor - Health Diagnostics

status - Auto-Update Status

standards - Generate Coding Standards

handoff - Generate Session Handoff

config - Configure API Settings

disable - Disable AgentBrain

MCP Integration

Troubleshooting

Context Not Regenerating on Commits

Hook Errors After Commits

Context Feels Stale

Doom Loop False Positives

API Costs Too High

Husky Compatibility

Files & Directories

Generated Files

Agent Files (Modified)

Git Hooks

Best Practices

When to Use AgentBrain

Workflow Tips

Cost Management

Links

License

Keywords

Related posts

Axios Maintainer Confirms Social Engineering Attack Behind npm Compromise

Node.js Drops Bug Bounty Rewards After Funding Dries Up

`setup` - Complete Automated Setup

`init` - Regenerate Context

`spec` - Create Task Specifications

`doom` - Detect Doom Loops

`doctor` - Health Diagnostics

`status` - Auto-Update Status

`standards` - Generate Coding Standards

`handoff` - Generate Session Handoff

`config` - Configure API Settings

`disable` - Disable AgentBrain