The page still described the rules-file-only Cursor setup from before #4649 and the old --remove scope. Rewrite it against what bd installs today: - project setup: .cursor/rules/beads.mdc, the shared .agents/skills/beads/ skill, and .cursor/hooks.json with sessionStart/preCompact/postToolUse hooks running `bd cursor-hook <event>` (user entries left alone) - `bd init` runs the project setup unless --skip-agents/--stealth or bare - --global: ~/.cursor/hooks.json + ~/.agents/skills/beads/, no rules file - hook lifecycle: sessionStart injects bd prime; preCompact arms a refresh marker; postToolUse re-injects once and clears it; markers live in the user cache dir keyed by conversation_id + workspace root - --check scope per mode and the exit/hint on a missing piece - --remove keeps user hooks, deletes hooks.json once only `version` remains, keeps the skill while the Codex integration still uses it - a manual hooks.json fallback in the shape bd writes README.md: `bd init` also installs the Cursor integration, not only Claude Code and Codex (the default init route in cmd/bd/init.go). Follow-up to #7268 (bd-gy483w, the README line from bd-erf5vx). Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
4.4 KiB
| title | description |
|---|---|
| Cursor | Set up beads for Cursor with an always-applied rules file, the beads agent skill, and agent hooks that survive compaction |
Use Beads with Cursor through an always-applied project rules file, the shared
beads agent skill, and Cursor agent hooks that load bd prime on session
start and recover it after a context compaction.
bd setup cursor
bd setup cursor --check
Project setup writes three things:
.cursor/rules/beads.mdc— an always-applied rule with the canonical Beads workflow guidance (the same content every other editor integration uses). Because it is always applied, Cursor re-includes it every turn..agents/skills/beads/— the Beads agent skill, the same onebd setup codexinstalls. Cursor loads.agents/skills/natively..cursor/hooks.json—sessionStart,preCompact, andpostToolUsehooks that runbd cursor-hook <event>. Entries you added yourself are left alone; only thebd cursor-hookentries are managed.
The hooks invoke bd, so make sure bd is on PATH for Cursor. Restart
Cursor (or start a new cursor-agent session) after installing so the rule
and hooks load.
bd init runs this project setup by default, alongside the Claude Code and
Codex setup, unless --skip-agents or --stealth is used (or the repository
is bare).
Global install
bd setup cursor --global
bd setup cursor --global --check
--global writes the hooks to ~/.cursor/hooks.json and the skill to
~/.agents/skills/beads/. It does not write a rules file: Cursor has no
file-based global rules location (global rules live in Cursor Settings →
Rules), so either add the guidance there or run bd setup cursor per project.
--check in global scope verifies the hooks and the skill only.
Hook lifecycle
sessionStartinjects the fullbd primeoutput as additional context for the new session.preCompactarms a one-shot refresh marker and shows a short note that the workflow context will be re-injected on the next tool call.postToolUseis a no-op on every tool call unless that marker is present, in which case it injectsbd primeonce more and clears the marker.
preCompact alone cannot inject context, so the marker plus the first
postToolUse after compaction is the recovery path. If bd prime fails, the
marker stays in place and a later tool call retries.
Refresh markers live in a user cache directory keyed by the Cursor
conversation_id and the first workspace root. They are not written to
tracked files or to the Beads database.
These events fire in the Cursor IDE and in recent cursor-agent CLI builds
(early-2026 CLI builds only fired shell hooks). Where the agent hooks do not
fire, the rules file and skill still apply; run bd prime by hand after a
compaction.
Verifying it works
bd setup cursor --check
This reports the rules file (project scope only), the three managed hooks, and the agent skill, and exits non-zero with the setup command to run if any is missing.
In a session, the agent should know your bd workflow without being told — ask
it what work is ready and it should run bd ready. If it doesn't, confirm
.cursor/rules/beads.mdc exists, that bd is on PATH for Cursor, and
restart Cursor.
Remove
bd setup cursor --remove
bd setup cursor --global --remove
Project removal deletes the rules file and removes only the bd cursor-hook
entries from .cursor/hooks.json, keeping any hooks of your own (the file is
deleted once nothing but its version remains). The shared
.agents/skills/beads/ skill is removed unless the Codex integration is still
installed, in which case it is kept and bd says so. --global removes the
same from ~/.cursor/hooks.json and ~/.agents/skills/beads/.
Manual fallback
If you manage .cursor/hooks.json by hand instead of running
bd setup cursor, the equivalent shape is:
{
"version": 1,
"hooks": {
"sessionStart": [{ "command": "bd cursor-hook sessionStart" }],
"preCompact": [{ "command": "bd cursor-hook preCompact" }],
"postToolUse": [{ "command": "bd cursor-hook postToolUse" }]
}
}
bd setup cursor --check recognises these entries by their
bd cursor-hook command prefix.
Related
- IDE Setup — all editor integrations
- Claude Code
- Codex