Claude Code Integration

Integrate Beads with Claude Code using CLI hooks for efficient context injection

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
   

   What gets installed?

   • 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

Approach	Token Overhead	Best For	Compute Cost
CLI + Hooks	~1-2k tokens	Claude Code, Cursor, Windsurf	Low
MCP Server	~10-50k tokens	Claude Desktop (MCP-only)	High

Always prefer CLI + hooks when shell access is available. It’s 10-50x more efficient.

Related Files

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