- FAQ: fix bulk migration/export commands (tracker pull/push need explicit IDs; bulk lives on sync --pull-only / --pull / --push-only / --push) and correct the cross-project isolation claim (hydration + external targets) - quickstart: replace the broken DOLT.md blob URL with site links - installation: Quick Install Script heading matches its macOS/Linux/FreeBSD body - rewrite 33 stale SCREAMING_CASE link labels to the target pages' titles - add description frontmatter to the 55 authored pages missing it - docs.json: wildcard redirects for the old /next/ and version-prefixed route spaces (1.0.0, 1.0.4, 1.0.5)
209 lines
5.1 KiB
Markdown
209 lines
5.1 KiB
Markdown
---
|
|
title: Claude Code
|
|
description: Wire beads into Claude Code with a SessionStart hook that primes context, using the CLI instead of MCP
|
|
---
|
|
|
|
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
|