beads/docs/integrations/claude-code.md
Chris Sells 5c2fe0d496 docs: loss-check merge legacy docs/ originals into the site pages
Sixteen same-ground pairs reconciled: the ported website page won and every
fact living only in the older docs/ original was merged in before deleting
it (INSTALLING, SETUP, ARCHITECTURE, CONFIG, GIT_INTEGRATION, ADVANCED,
TROUBLESHOOTING, FAQ, MOLECULES, ROUTING, MULTI_REPO_AGENTS, and the five
agent-integration guides). The two divergent FAQs are now one canonical
FAQ with the comparison-first framing leading and pre-1.0 version gating
removed.

The routing pair inverted: the ported page described a routing system that
does not exist (bd routes, bd hydrate, .beads/routes.jsonl); the page was
rebuilt from the accurate sources (ROUTING.md + MULTI_REPO_AGENTS.md)
against the real surface (routing.mode config, role detection,
repos.primary/additional hydration, --repo override).

Every claim was verified against the Go source or the generated CLI
reference. Phantom surfaces removed across the corpus: bd pin/hook/pour/
wisp/routes/hydrate/reserve/lock/merge/stats, bd hooks status, bd vc
conflicts/log, bd dolt set shared-server, fictional beads_* MCP tool names
(real names taken from beads-mcp server.py), import.orphan_handling and
export.error_policy config keys, database.wal_mode/cache_size, stale
.beads/dolt/sql-server.log paths, and SQLite-era file paths. Notable
corrections: min_hash_length default is 3, .beads/metadata.json is
git-tracked, tombstone status is removed, wisps live in the main database
under an ephemeral flag.

Freshness markers moved with their content (configuration, ide-setup) and
the freshness gate + DOC_INVENTORY ledger now point at the new locations.
Load-bearing anchors preserved: #branchless-workflows-jujutsu--jj,
#circuit-breaker-server-appears-down-failing-fast, #extensible-database,
#multi-repo-hydration. Pointer stubs remain at docs/{SETUP,INSTALLING,
GIT_INTEGRATION}.md because released binaries print those paths
(allowlisted in the docsync guard).

Gates: go test ./test/docsync PASS; generate-cli-docs.sh --check PASS;
check-doc-freshness.sh PASS; mint broken-links: no broken links; mint dev
serves all sections (11 routes spot-checked at 200).
2026-07-12 10:37:07 -07:00

208 lines
5 KiB
Markdown

---
title: Claude Code
---
How to use beads with Claude Code.
## Setup
### Quick Setup
```bash
bd setup claude
```
This installs:
- **SessionStart hook** - Runs `bd prime --hook-json` when a session starts. SessionStart also fires after context compaction, so the same hook refreshes context automatically.
- **CLAUDE.md pointer** - A minimal beads section in your project's `CLAUDE.md` (skipped if `CLAUDE.md` is a symlink).
By default the hook is written to the project's `.claude/settings.json`. Variants:
```bash
bd setup claude --global # Install to ~/.claude/settings.json instead
bd setup claude --stealth # Stealth mode: flush only, no git operations
bd setup claude --remove # Remove the hook and the CLAUDE.md section
```
If the [beads plugin](/integrations/claude-code-plugin) is enabled, `bd setup claude` skips writing hooks - the plugin provides its own, and duplicates would run `bd prime` twice per session.
### Manual Setup
Add to `.claude/settings.json` (project) or `~/.claude/settings.json` (global):
```json
{
"hooks": {
"SessionStart": [
{
"matcher": "",
"hooks": [
{ "type": "command", "command": "bd prime --hook-json" }
]
}
]
}
}
```
The `--hook-json` flag wraps the output in the hook JSON envelope Claude Code expects. No `PreCompact` hook is needed - SessionStart fires again after compaction.
### Verify Setup
```bash
bd setup claude --check
```
## How It Works
1. **Session starts** → `bd prime` injects ~1-2k tokens of context
2. **You work** → Use `bd` CLI commands directly
3. **Session compacts** → SessionStart fires again and `bd prime` refreshes workflow context
4. **Session ends** → `bd dolt push` syncs changes
### Why CLI + hooks instead of MCP?
Context efficiency. MCP tool schemas can add 10-50k tokens to every request; `bd prime` adds ~1-2k tokens of workflow context - 10-50x less overhead, which means lower cost, lower latency, and better model attention. Prefer CLI + hooks in any environment with shell access; use the [MCP server](/integrations/mcp-server) only where the CLI is unavailable, such as Claude Desktop.
### Why not Claude Skills?
Beads doesn't ship or require Claude Skills (`.claude/skills/`). `bd prime` already delivers the workflow context, and the workflow fits a simple command set (ready → create → update → close → sync). Skills are also Claude-specific, which would break beads' editor-agnostic approach - the same CLI works in Cursor, Windsurf, and every other shell-capable editor. You can create your own Skills on top of beads, but none are needed.
## Essential Commands for Agents
### Creating Issues
```bash
# Always include description for context
bd create "Fix authentication bug" \
--description="Login fails with special characters in password" \
-t bug -p 1 --json
# Link discovered issues
bd create "Found SQL injection" \
--description="User input not sanitized in query builder" \
--deps discovered-from:bd-42 --json
```
### Working on Issues
```bash
# Find ready work
bd ready --json
# Start work
bd update bd-42 --claim --json
# Complete work
bd close bd-42 --reason "Fixed in commit abc123" --json
```
### Querying
```bash
# List open issues
bd list --status open --json
# Show issue details
bd show bd-42 --json
# Check blocked issues
bd blocked --json
```
### Syncing
```bash
# ALWAYS run at session end
bd dolt push
```
## Best Practices
### Always Use `--json`
```bash
bd list --json # Parse programmatically
bd create "Task" --json # Get issue ID from output
bd show bd-42 --json # Structured data
```
### Always Include Descriptions
```bash
# Good
bd create "Fix auth bug" \
--description="Login fails when password contains quotes" \
-t bug -p 1 --json
# Bad - no context for future work
bd create "Fix auth bug" -t bug -p 1 --json
```
### Link Related Work
```bash
# When you discover issues during work
bd create "Found related bug" \
--deps discovered-from:bd-current --json
```
### Push Before Session End
```bash
# ALWAYS run before ending
bd dolt push
```
## Plugin (Optional)
For slash commands and enhanced UX, install the [beads plugin](/integrations/claude-code-plugin):
```bash
# In Claude Code
/plugin marketplace add gastownhall/beads
/plugin install beads
# Restart Claude Code
```
Adds slash commands:
- `/beads:ready` - Show ready work
- `/beads:create` - Create issue
- `/beads:show` - Show issue
- `/beads:update` - Update issue
- `/beads:close` - Close issue
## Troubleshooting
### Context not injected
```bash
# Check hook setup
bd setup claude --check
# Manually prime
bd prime
```
### Changes not syncing
```bash
# Force push
bd dolt push
# Check system health
bd doctor
```
### Database not found
```bash
# Initialize beads
bd init --quiet
```
## See Also
- [Beads Claude Code Plugin](/integrations/claude-code-plugin) - Packaged plugin with slash commands
- [MCP Server](/integrations/mcp-server) - For MCP-only environments
- [IDE Setup](/getting-started/ide-setup) - Other editors