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).
208 lines
5 KiB
Markdown
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
|