* fix(setup): keep bd setup claude --global's section in ~/.claude/CLAUDE.md bd setup claude --global put its hook in ~/.claude/settings.json but wrote the managed beads section into the current directory's CLAUDE.md, and --remove --global stripped it from there. Run from $HOME it created ~/CLAUDE.md with project scaffolding, which stops Claude Code reading AGENTS.md in projects below it; run inside a project it removed the section that project's own install had written, leaving its hooks. A global install and removal now manage the section in Claude Code's user-level ~/.claude/CLAUDE.md (created holding only the section, no project scaffolding), with hints naming bd setup claude --global. With global or plugin hooks, --check reports that file when the project's instructions have no beads section; a project install is still judged on the project's file alone. Project installs are unchanged. Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(setup): render the user-level CLAUDE.md section independently of the project ~/.claude/CLAUDE.md is shared by every project, but bd setup claude --global rendered and --check judged its section with the current directory's beads config (sync.remote, sync.git-remote, no-push). From a project with a remote and one without, --check called the other's install stale and its hint flipped the file back. The user-level file now always renders with the default options, so install and --check agree across projects. Also pin --check's fallback to the project's file and project hint when neither file has a section, tell existing --global users to re-run it, and name ~/.claude/CLAUDE.md in the ide-setup recipe table. Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(setup): judge the user-level Claude files from $HOME and ~/.claude Run from the home directory, the project's .claude/settings.json is the global one, so bd setup claude --check reported a global install as project hooks and judged ~/CLAUDE.md; its "Run: bd setup claude" hint then created the ~/CLAUDE.md a global install exists to avoid. Run from ~/.claude, the project's CLAUDE.md is the user-level file, and --check judged it with that directory's render options and the project hint. --check now reports hooks as global from $HOME and judges the user-level file there and from ~/.claude with the fixed options and the --global hint. With user-level hooks and no section in either file it names --global unless the project has its own CLAUDE.md. A --remove run from $HOME, which removes the global hooks, also removes the user-level section. The init agent-artifact test ran bd setup claude with HOME at the project, so its checks would now see a home directory; it gets a separate HOME and its goldens are unchanged. Rebase note (maintainer): rebased onto main after #7678 merged; main's agent-artifact harness already runs bd with a separate HOME, so this commit's harness edits to cmd/bd/agent_artifacts_embedded_test.go were dropped. Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * test(setup): pin --check's user-level choice beside project instructions With global hooks, --check judges ~/.claude/CLAUDE.md when the project's own CLAUDE.md has no beads section but the user-level file has one, and when run from the home directory whose ~/CLAUDE.md has no section. Nothing exercised either half of that condition: replacing it with false left the suite and goldens green. Add a subtest for each; each now fails when its half of the condition is dropped. Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(setup): name --global when --check finds no hooks from $HOME From the home directory --check with no hooks said 'Run: bd setup claude'. Following it runs a project install there, which creates ~/CLAUDE.md with project scaffolding, the file that stops Claude Code reading AGENTS.md in the projects below it. The missing-section hint at home already names --global; make the missing-hooks hint match, with a subtest. Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * docs(setup): qualify the --global CHANGELOG entry; watch ~/.claude/CLAUDE.md The CHANGELOG said --check from the home directory judges the user-level files, but a beads section still in ~/CLAUDE.md is judged instead, and the --global hint for a missing section applies only when the project has no CLAUDE.md of its own. Say both, mention the new missing-hooks hint at home, and re-wrap the paragraph. The embedded agent-artifact harness comment said a global install writes $HOME/CLAUDE.md; it now writes $HOME/.claude/CLAUDE.md. Track that path too and reword the comment. The bd init goldens do not change. Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(setup): word the user-level CLAUDE.md section for repositories that use beads bd setup claude --global writes its section to ~/.claude/CLAUDE.md, which Claude Code loads in every project, but rendered it with the project wording: "This project uses bd (beads)" and "Use bd for ALL task tracking — do NOT use TodoWrite". In a repository without beads that told the agent to give up its own task tools and pointed it at bd, whose answer there is "run 'bd init'", while the global hook, bd prime, stays silent outside a workspace. RenderOpts.UserLevel rewords the opening line and the task-tracking rules of both profiles so they apply only in beads repositories. The global env fixes it through agents.UserLevelRenderOpts, so install, in-place update and --check agree on the hash from every directory, and a project-worded section left in ~/.claude/CLAUDE.md reads as stale and is reworded by --global. The new minimal-user and full-user variants are pinned by golden and hash; the project rendering is unchanged. Also pin sameDir's symlink following: --check from a symlink to $HOME or to ~/.claude still judges the user-level files. Refreshed onto main past #7692, whose --remove takes the blank lines around the section with it and whose setup appends a section after one blank line: claude-setup-global-beside-project-install.golden no longer records the old hole (an extra blank line before the appended section, two left behind by --remove --global). Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Co-authored-by: Eddie the Engineer <338826946+gascity-eddie[bot]@users.noreply.github.com>
17 KiB
| title | description |
|---|---|
| IDE Setup | Configure bd setup recipes, hooks, and instruction files for Claude Code, Cursor, Gemini, Copilot, and other coding agents |
Configure your IDE or coding agent for optimal beads integration.
Last reviewed: 2026-10-05
Freshness source: cmd/bd/setup*.go and internal/recipes/.
How bd setup Works
The bd setup command uses a recipe-based architecture: recipes define where beads workflow instructions are written. Built-in recipes cover popular tools, and you can add custom recipes for any other tool (see Custom Recipes below). Integrations complement each other — you can install several at once.
bd setup --list # Show all available recipes
bd setup claude # Install an integration (claude, cursor, gemini, ...)
bd setup claude --check # Verify installation
bd setup claude --remove # Uninstall
| Recipe | Files written | Details |
|---|---|---|
claude |
.claude/settings.json + CLAUDE.md section (or ~/.claude/settings.json + ~/.claude/CLAUDE.md with --global) |
Claude Code |
cursor |
.cursor/rules/beads.mdc + .agents/skills/beads/ + .cursor/hooks.json (with --global: ~/.cursor/hooks.json + ~/.agents/skills/beads/, no rules file) |
Cursor |
gemini |
~/.gemini/settings.json (or .gemini/settings.json with --project) + GEMINI.md section |
Gemini CLI |
copilot |
.copilot-plugin/plugin.json + .github/copilot-instructions.md |
Copilot CLI |
codex |
.agents/skills/beads/ + AGENTS.md section + .codex/ hooks (with --global: ~/.agents/skills/beads/ + $CODEX_HOME or ~/.codex) |
Codex |
factory |
AGENTS.md section |
Factory.ai Droid |
mux |
AGENTS.md section (+ .mux/ layers with --project/--global) |
Mux |
opencode |
AGENTS.md section |
OpenCode |
aider |
.aider.conf.yml + .aider/BEADS.md + .aider/README.md |
Aider |
junie |
.junie/guidelines.md + .junie/mcp/mcp.json |
Junie |
windsurf |
.windsurf/rules/beads.md |
Windsurf |
cody |
.cody/rules/beads.md |
Cody |
kilocode |
.kilocode/rules/beads.md |
Kilo Code |
kiro |
.kiro/steering/beads.md |
Kiro CLI |
bd prime is the single source of truth for operational workflow commands. Each integration's instruction file either points to bd prime (hook-enabled agents) or carries the full command reference (AGENTS-first agents).
Template Profiles
Each integration writes one of two profiles that control how much content goes into the tool's instruction file (AGENTS.md, CLAUDE.md, GEMINI.md, or .github/copilot-instructions.md):
| Profile | Used by | Content |
|---|---|---|
full |
Factory, Mux, OpenCode | Complete command reference, issue types, priorities, workflow |
minimal |
Claude Code, GitHub Copilot CLI, Gemini CLI | Pointer to bd prime, quick reference only (~60% smaller) |
Hook-enabled agents use the minimal profile because bd prime injects full context at session start. AGENTS-first agents use the full profile because their instruction file remains the primary integration surface. Codex is skill-based instead: it uses .agents/skills/beads/SKILL.md, with managed AGENTS.md guidance telling Codex when to use the skill.
Profile precedence: if a file already has a full profile section and a minimal profile tool installs to the same file (for example via symlinks), the full profile is preserved to avoid information loss.
Policy Profiles
Template profiles control how much text gets installed. Policy profiles control what an agent is authorized to do at handoff:
| Policy | Default scope | Commit/push guidance |
|---|---|---|
conservative |
Standalone projects, unknown projects, and one-off assistance | Use bd for task tracking, then report changed files, validation, and proposed commands. Do not commit, push, or run Dolt remote sync without explicit user or orchestrator approval. |
minimal |
Hook-first integrations where bd prime carries the detailed workflow |
Same git authority as conservative; the installed file stays short and points to bd prime. |
team-maintainer |
Repositories that explicitly delegate session close to agents | Agents may close beads, run quality gates, commit, run bd dolt push, and git push as part of routine work. Current "do not commit" or "do not push" instructions still override the profile. |
The generated beads section and bd prime default to conservative git authority. Set the profile explicitly with the agent.profile config key or the BD_AGENT_PROFILE environment variable (values: conservative, minimal, team-maintainer; the env var takes precedence; an unrecognized value falls back to conservative):
bd config set agent.profile team-maintainer
# or, for a single session/process:
BD_AGENT_PROFILE=team-maintainer bd prime
bd prime layers this explicit knob on top of its per-branch git-authority checks (stealth mode, no git remote, ephemeral branch, no-push); those hard constraints still take precedence, and team-maintainer remains subordinate to any explicit "do not commit"/"do not push" instruction. Beads never infers team-maintainer authority merely because a remote exists — it must be set via this knob (or, for tools without config access, via top-level project instructions).
Managed Sections
bd setup factory, bd setup mux, and bd setup opencode append a beads section to AGENTS.md, wrapped in BEGIN/END BEADS INTEGRATION HTML-comment markers. The begin marker carries version, profile, and hash metadata (e.g. <!-- BEGIN BEADS INTEGRATION v:1 profile:full hash:19cc25d9 -->) so --check can report missing, stale, or current; legacy markers without metadata are auto-upgraded on the next install or update. Re-running setup updates the existing section in place (idempotent), and --remove deletes only the managed section and the blank lines that set it off — the rest of your AGENTS.md is untouched. Running setup again after --remove appends the section to the end of the file after one blank line, so removing and re-adding it toggles between the same two files. The section bd setup claude and bd setup gemini manage in CLAUDE.md and GEMINI.md behaves the same way.
bd setup codex uses its own marker pair (BEGIN/END BEADS CODEX SETUP). Running it alongside bd setup factory or bd setup mux against the same AGENTS.md leaves two managed sections side by side; each recipe's --check inspects only its own section, and each --remove removes only its own section.
One AGENTS.md works across many tools — Factory Droid, Mux, OpenCode, Cursor, Zed, Jules, and other AGENTS.md-aware assistants — so bd setup factory is a good starting point when your team mixes AI tools.
Claude Code
The recommended approach for Claude Code:
bd setup claude # Project install: .claude/settings.json
bd setup claude --global # Global install: ~/.claude/settings.json + ~/.claude/CLAUDE.md
This installs:
- SessionStart hook - Runs
bd prime --hook-json, which wraps the workflow context in the JSON envelope Claude Code expects. SessionStart fires when a session starts, resumes, or clears, and again after context compaction — no separate compaction hook is needed. - Minimal beads section in
CLAUDE.md- A pointer tobd prime, managed with hash/version markers for safe updates and--checkfreshness detection. IfCLAUDE.mdis a thin stub that importsAGENTS.md(an@AGENTS.mdline of its own), the section is written toAGENTS.mdinstead, and a stale beads block left in the stub by an older bd is removed. A--globalinstall writes the section to your user-level~/.claude/CLAUDE.mdand leaves the current directory's files alone. Claude Code loads that file in every project, so there the section applies only in repositories that use beads.
If the beads Claude Code plugin is installed, hooks are plugin-managed and bd setup claude skips writing them, so bd prime doesn't fire twice per session.
How it works:
- SessionStart hook runs
bd prime --hook-jsonautomatically bd primeinjects ~1-2k tokens of workflow context- You use
bdCLI commands directly - Git hooks refresh exports and legacy fallbacks; Dolt remotes handle sync
Flags:
| Flag | Description |
|---|---|
--check |
Check both hooks and the managed CLAUDE.md beads section |
--remove |
Remove beads hooks and the managed CLAUDE.md beads section |
--global |
Install to ~/.claude/settings.json and ~/.claude/CLAUDE.md instead of the project |
--stealth |
Use bd prime --stealth --hook-json (flush only, no git operations) — useful in CI/CD where git operations might fail |
Restart Claude Code after installation for the hooks to take effect.
Verify installation:
bd setup claude --check
Manual Setup
If you prefer manual configuration, add the hook to your Claude Code settings:
{
"hooks": {
"SessionStart": [
{
"matcher": "",
"hooks": [
{ "type": "command", "command": "bd prime --hook-json" }
]
}
]
}
}
Cursor IDE
bd setup cursor # Project install: rules file + agent skill + hooks
bd setup cursor --global # Global install: hooks + agent skill (no rules file)
A project install writes three things:
.cursor/rules/beads.mdc- an always-applied rules file that Cursor re-includes every turn..agents/skills/beads/- the beads agent skill, the same onebd setup codexinstalls.--removekeeps it while the Codex integration still uses it..cursor/hooks.json-sessionStart,preCompact, andpostToolUsehooks that runbd cursor-hook <event>, sobdmust be onPATHfor Cursor. Your own entries inhooks.jsonare left alone.
--global writes the hooks to ~/.cursor/hooks.json and the skill to
~/.agents/skills/beads/. Cursor has no file-based global rules location, so
add global rules in Cursor Settings or run bd setup cursor per project.
Restart Cursor (or start a new cursor-agent session) after installing.
Verify:
bd setup cursor --check
See Cursor for details.
Gemini CLI
bd setup gemini # Global hooks in ~/.gemini/settings.json
bd setup gemini --project # Project hooks in .gemini/settings.json
This installs a SessionStart hook running bd prime --hook-json — Gemini requires hook stdout to be valid JSON, and --hook-json wraps the markdown in the required envelope — plus a minimal beads section in GEMINI.md. --stealth works the same as for Claude Code; --check and --remove cover both the hooks and the managed GEMINI.md section.
Verify:
bd setup gemini --check
See Gemini CLI for details.
Aider
# Setup Aider integration
bd setup aider
This writes three files:
| File | Purpose |
|---|---|
.aider.conf.yml |
Points Aider to read the instructions file |
.aider/BEADS.md |
Workflow instructions for the AI |
.aider/README.md |
Quick reference for humans |
Aider is human-in-the-loop: the AI suggests bd commands, and you run them with /run. See Aider for the workflow.
Verify:
bd setup aider --check
AGENTS.md Tools: Factory, Mux, OpenCode, Codex
bd setup factory # Factory.ai Droid — AGENTS.md section
bd setup mux # Mux — AGENTS.md section (+ --project/--global layers)
bd setup opencode # OpenCode — AGENTS.md section
bd setup codex # Codex — beads skill + AGENTS.md guidance + native hooks
bd setup codex --global # Same, under ~/.agents/skills/beads and $CODEX_HOME (or ~/.codex)
These create or update a managed section in AGENTS.md (see Managed Sections above). bd init runs the project Claude Code, Codex, and Cursor setup automatically unless --skip-agents or --stealth is used (or the repository is bare). In worktree, shared, or BEADS_DIR setups, use bd where to confirm the resolved workspace — these integrations do not require a local ./.beads. Restart the tool after setup if it is already running.
Details: Factory.ai Droid, Mux, OpenCode, Codex.
GitHub Copilot
Copilot CLI:
bd setup copilot
This installs a native Copilot CLI plugin manifest (.copilot-plugin/plugin.json, which registers bd prime hooks) and repository instructions (.github/copilot-instructions.md). See Copilot CLI.
For VS Code with GitHub Copilot, use the MCP server:
# Install MCP server
uv tool install beads-mcp
Create .vscode/mcp.json in your project:
{
"servers": {
"beads": {
"command": "beads-mcp"
}
}
}
For all projects: Add to VS Code user-level MCP config:
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/Code/User/mcp.json |
| Linux | ~/.config/Code/User/mcp.json |
| Windows | %APPDATA%\Code\User\mcp.json |
{
"servers": {
"beads": {
"command": "beads-mcp",
"args": []
}
}
}
Initialize beads and reload VS Code:
bd init --quiet
See GitHub Copilot Integration for detailed setup.
Context Injection with bd prime
All integrations use bd prime to inject context:
bd prime
This outputs a compact (~1-2k tokens) workflow reference including:
- Available commands
- Current project status
- Workflow patterns
- Best practices
- Persistent memories from
bd remember
bd prime prints memories near the top and starts with a truncation warning. If your host stores the full hook output in a file and only shows a preview, have the agent read the full file before continuing.
In hook contexts, bd prime --hook-json wraps the output in the SessionStart JSON envelope (Claude Code, Gemini CLI, Codex). For memory-only hooks:
bd prime --memories-only
Why context efficiency matters:
- Compute cost scales with tokens
- Latency increases with context size
- Models attend better to smaller, focused contexts
MCP Server (Alternative)
For MCP-only environments (Claude Desktop, no shell access):
# Install MCP server
pip install beads-mcp
Add to Claude Desktop config:
{
"mcpServers": {
"beads": {
"command": "beads-mcp"
}
}
}
Trade-offs:
- Works in MCP-only environments
- Higher context overhead (10-50k tokens for tool schemas)
- Additional latency from MCP protocol
See MCP Server for detailed configuration.
Custom Recipes
For editors or tools without a built-in recipe:
bd setup --add myeditor .myeditor/rules.md # Save a custom recipe
bd setup myeditor # Install it
bd setup myeditor --check # Check it
bd setup myeditor --remove # Remove it
Custom recipes are stored in .beads/recipes.toml (adding one requires an active beads workspace):
[recipes.myeditor]
name = "myeditor"
path = ".myeditor/rules.md"
type = "file"
For a one-off install without saving a recipe, write the template to any path — or inspect it first:
bd setup -o .my-custom-location/beads.md
bd setup --print
Recipe types:
| Type | Description | Used by |
|---|---|---|
file |
Write the template to a single file | windsurf, cody, kilocode, kiro, cursor (which also installs a skill and hooks) |
hooks |
Modify JSON settings to add hooks | claude, gemini |
section |
Inject a marked section into an existing file | factory, codex, mux, opencode |
multifile |
Write multiple files | aider, copilot, junie |
Custom recipes added via --add are always type file.
Git Hooks
Ensure git hooks are installed for export refresh and legacy fallback behavior:
bd hooks install
This installs:
- pre-commit - Runs chained hooks before commit
- post-merge - Runs chained hooks after pull/merge
- pre-push - Runs chained hooks before push
- post-checkout - Runs chained hooks after branch checkout
- prepare-commit-msg - Adds agent identity trailers for forensics
Check hook status:
bd hooks list # Installed, outdated, or missing
bd info # Shows warnings if hooks are outdated
Verifying Your Setup
Run a complete health check:
# Check version
bd version
# Check project health (includes integration status)
bd doctor
# Check git hooks
bd hooks list
# Check editor integration
bd setup claude --check # or cursor, gemini, aider, ...
Troubleshooting:
- Hooks not working? Restart your AI tool after installation, then re-run
bd setup claude --check(or your tool's recipe) and checkbd doctoroutput for integration status. - Context not appearing? Make sure
bd primeworks standalone; if it fails, fix the underlying beads issue first.