* 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>
416 lines
17 KiB
Markdown
416 lines
17 KiB
Markdown
---
|
|
title: IDE Setup
|
|
description: 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.
|
|
|
|
```bash
|
|
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](/integrations/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](/integrations/cursor) |
|
|
| `gemini` | `~/.gemini/settings.json` (or `.gemini/settings.json` with `--project`) + `GEMINI.md` section | [Gemini CLI](/integrations/gemini) |
|
|
| `copilot` | `.copilot-plugin/plugin.json` + `.github/copilot-instructions.md` | [Copilot CLI](/integrations/copilot-cli) |
|
|
| `codex` | `.agents/skills/beads/` + `AGENTS.md` section + `.codex/` hooks (with `--global`: `~/.agents/skills/beads/` + `$CODEX_HOME` or `~/.codex`) | [Codex](/integrations/codex) |
|
|
| `factory` | `AGENTS.md` section | [Factory.ai Droid](/integrations/factory) |
|
|
| `mux` | `AGENTS.md` section (+ `.mux/` layers with `--project`/`--global`) | [Mux](/integrations/mux) |
|
|
| `opencode` | `AGENTS.md` section | [OpenCode](/integrations/opencode) |
|
|
| `aider` | `.aider.conf.yml` + `.aider/BEADS.md` + `.aider/README.md` | [Aider](/integrations/aider) |
|
|
| `junie` | `.junie/guidelines.md` + `.junie/mcp/mcp.json` | [Junie](/integrations/junie) |
|
|
| `windsurf` | `.windsurf/rules/beads.md` | [Windsurf](/integrations/windsurf) |
|
|
| `cody` | `.cody/rules/beads.md` | [Cody](/integrations/cody) |
|
|
| `kilocode` | `.kilocode/rules/beads.md` | [Kilo Code](/integrations/kilocode) |
|
|
| `kiro` | `.kiro/steering/beads.md` | [Kiro CLI](/integrations/kiro) |
|
|
|
|
`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).
|
|
|
|
<Note>
|
|
Commit the instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, as applicable) to git so all team members and AI tools get the same instructions.
|
|
</Note>
|
|
|
|
### 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`):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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 to `bd prime`, managed with hash/version markers for safe updates and `--check` freshness detection. If `CLAUDE.md` is a thin stub that imports `AGENTS.md` (an `@AGENTS.md` line of its own), the section is written to `AGENTS.md` instead, and a stale beads block left in the stub by an older bd is removed. A `--global` install writes the section to your user-level `~/.claude/CLAUDE.md` and 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](/integrations/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:**
|
|
1. SessionStart hook runs `bd prime --hook-json` automatically
|
|
2. `bd prime` injects ~1-2k tokens of workflow context
|
|
3. You use `bd` CLI commands directly
|
|
4. 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:**
|
|
```bash
|
|
bd setup claude --check
|
|
```
|
|
|
|
### Manual Setup
|
|
|
|
If you prefer manual configuration, add the hook to your Claude Code settings:
|
|
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"SessionStart": [
|
|
{
|
|
"matcher": "",
|
|
"hooks": [
|
|
{ "type": "command", "command": "bd prime --hook-json" }
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
## Cursor IDE
|
|
|
|
```bash
|
|
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 one
|
|
`bd setup codex` installs. `--remove` keeps it while the Codex integration
|
|
still uses it.
|
|
- **`.cursor/hooks.json`** - `sessionStart`, `preCompact`, and `postToolUse`
|
|
hooks that run `bd cursor-hook <event>`, so `bd` must be on `PATH` for
|
|
Cursor. Your own entries in `hooks.json` are 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:**
|
|
```bash
|
|
bd setup cursor --check
|
|
```
|
|
|
|
See [Cursor](/integrations/cursor) for details.
|
|
|
|
## Gemini CLI
|
|
|
|
```bash
|
|
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:**
|
|
```bash
|
|
bd setup gemini --check
|
|
```
|
|
|
|
See [Gemini CLI](/integrations/gemini) for details.
|
|
|
|
## Aider
|
|
|
|
```bash
|
|
# 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](/integrations/aider) for the workflow.
|
|
|
|
**Verify:**
|
|
```bash
|
|
bd setup aider --check
|
|
```
|
|
|
|
## AGENTS.md Tools: Factory, Mux, OpenCode, Codex
|
|
|
|
```bash
|
|
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](/integrations/factory), [Mux](/integrations/mux), [OpenCode](/integrations/opencode), [Codex](/integrations/codex).
|
|
|
|
## GitHub Copilot
|
|
|
|
**Copilot CLI:**
|
|
|
|
```bash
|
|
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](/integrations/copilot-cli).
|
|
|
|
**For VS Code with GitHub Copilot**, use the MCP server:
|
|
|
|
```bash
|
|
# Install MCP server
|
|
uv tool install beads-mcp
|
|
```
|
|
|
|
Create `.vscode/mcp.json` in your project:
|
|
|
|
```json
|
|
{
|
|
"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` |
|
|
|
|
```json
|
|
{
|
|
"servers": {
|
|
"beads": {
|
|
"command": "beads-mcp",
|
|
"args": []
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Initialize beads and reload VS Code:
|
|
|
|
```bash
|
|
bd init --quiet
|
|
```
|
|
|
|
See [GitHub Copilot Integration](/integrations/github-copilot) for detailed setup.
|
|
|
|
## Context Injection with `bd prime`
|
|
|
|
All integrations use `bd prime` to inject context:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
# Install MCP server
|
|
pip install beads-mcp
|
|
```
|
|
|
|
Add to Claude Desktop config:
|
|
```json
|
|
{
|
|
"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](/integrations/mcp-server) for detailed configuration.
|
|
|
|
## Custom Recipes
|
|
|
|
For editors or tools without a built-in recipe:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```toml
|
|
[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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:**
|
|
```bash
|
|
bd hooks list # Installed, outdated, or missing
|
|
bd info # Shows warnings if hooks are outdated
|
|
```
|
|
|
|
## Verifying Your Setup
|
|
|
|
Run a complete health check:
|
|
|
|
```bash
|
|
# 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 check `bd doctor` output for integration status.
|
|
- *Context not appearing?* Make sure `bd prime` works standalone; if it fails, fix the underlying beads issue first.
|