Skip to main content
Beads integrates seamlessly with Claude Code through a lightweight CLI + hooks approach, providing workflow context without the overhead of MCP tool schemas.

​
Why CLI + Hooks?

Claude Code integration uses bd prime and hooks instead of MCP for better efficiency:
  • Lower token overhead: ~1-2k tokens vs 10-50k for MCP schemas
  • Reduced compute cost: Fewer tokens means less processing per inference
  • Better latency: Smaller prompts process faster
  • Universal compatibility: Works in any environment with shell access
For MCP-only environments like Claude Desktop, see the MCP Server documentation.

​
Installation

1

Install Claude Code hooks

Install hooks globally (for all projects):
bd setup claude
Or install for the current project only:
bd setup claude --project
  • SessionStart hook: Runs bd prime when Claude Code starts a session
  • PreCompact hook: Runs bd prime before context compaction to preserve workflow instructions
2

Verify installation

Check that hooks are properly installed:
bd setup claude --check
You should see confirmation that both hooks are installed.
3

Start using Claude Code

Launch Claude Code in your project directory. The hooks will automatically inject Beads workflow context at the start of each session.

​
Configuration Options

​
Stealth Mode

Use stealth mode to flush context without git operations: 
bd setup claude --stealth
This is useful if you want context injection without automatic git sync behavior.

​
Remove Hooks

To uninstall Claude Code hooks: 
bd setup claude --remove

​
How It Works

​
Automatic Context Injection

When you start a Claude Code session, the SessionStart hook automatically runs: 
bd prime
This injects ~1-2k tokens of workflow context, including:
  • Available bd commands
  • Issue tracking workflow
  • Priority levels and issue types
  • Best practices for AI agents

​
Context Preservation

Before Claude Code compacts context (to manage token limits), the PreCompact hook runs bd prime again, ensuring workflow instructions persist throughout long sessions.

​
Usage Examples

​
Starting Work

Simply ask Claude Code: 
What issues are ready to work on?
Claude will run: 
bd ready

​
Creating Issues

Create a bug for the login timeout issue
Claude will run: 
bd create "Fix login timeout" --description="Users experiencing timeouts..." -t bug -p 1

​
Updating Issues

Claim bd-42 and start working on it
Claude will run: 
bd update bd-42 --claim

​
Completing Work

Close bd-42 as completed
Claude will run: 
bd close bd-42 --reason "Implemented fix and added tests"

​
Best Practices

Let hooks do the work

Don’t manually run bd prime - the hooks inject context automatically

Use natural language

Claude understands your intent - describe what you want in plain English

Trust the workflow

Claude knows the bd workflow from context injection

Review before push

Always review Claude’s changes before running bd sync

​
Troubleshooting

​
Hooks not running

Check hook installation: 
bd setup claude --check
Reinstall hooks: 
bd setup claude --remove
bd setup claude

​
Claude not using bd commands

Manually inject context: 
bd prime
Copy the output and paste it into your Claude Code session. Verify bd is in PATH: 
which bd
bd --version

​
Context gets lost during long sessions

The PreCompact hook should prevent this, but if context is lost:
  1. Check that the PreCompact hook is installed: 
    bd setup claude --check
  2. Manually run bd prime to reinject context

​
Wrong database detected

Bd uses tree-walking to find the .beads/ directory. Ensure you’re in the correct project directory: 
bd doctor
This shows which database bd will use.

​
CLI vs MCP Comparison

ApproachToken OverheadBest ForCompute Cost
CLI + Hooks~1-2k tokensClaude Code, Cursor, WindsurfLow
MCP Server~10-50k tokensClaude Desktop (MCP-only)High
Always prefer CLI + hooks when shell access is available. It’s 10-50x more efficient.
For developers extending Beads:
  • cmd/bd/prime.go - Context generation logic
  • cmd/bd/setup/claude.go - Hook installation code
  • cmd/bd/doctor/claude.go - Integration verification
  • docs/CLAUDE.md - General Claude Code guidance

​
See Also

MCP Server

Alternative integration for MCP-only environments

Copilot Integration

Use Beads with GitHub Copilot in VS Code

Aider Integration

Integrate with Aider for AI pair programming

Quick Start

Get started with Beads basics

Build docs developers (and LLMs) love

Get started for freeTalk to us