beads/docs/integrations/cursor.md
Bee 75d9dabf83
docs(cursor): re-review docs/integrations/cursor.md against cmd/bd/setup/cursor.go (#7333)
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>
2026-10-08 08:20:31 +00:00

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 one bd setup codex installs. Cursor loads .agents/skills/ natively.
  • .cursor/hooks.json — sessionStart, preCompact, and postToolUse hooks that run bd cursor-hook <event>. Entries you added yourself are left alone; only the bd cursor-hook entries 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

  • sessionStart injects the full bd prime output as additional context for the new session.
  • preCompact arms a one-shot refresh marker and shows a short note that the workflow context will be re-injected on the next tool call.
  • postToolUse is a no-op on every tool call unless that marker is present, in which case it injects bd prime once 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.