baz-plugin CLAUDE.md

baz-plugin

Plugin for Claude Code, Codex CLI, and Cursor that adds Baz indexed search tools. All three platforms wire a session-start hook that surfaces two values — the agent's session ID and the repository the working directory belongs to — so baz can correlate tool calls, and a PostToolUse hook that watches for the agent writing its final plan to the session's scratch plan file (.baz-plan-<sessionId>.md in the plugin's private directory; see Scratch-file lifecycle) — that file-write is the cross-platform "I'm done planning" signal that prompts the agent to ask the user whether to upload the plan. Only on the user's yes does it call mcp__baz__update_plan, which persists the plan, emits the planner_session_completed event, and returns a shareable plan link. An uploaded plan is an object teammates open, comment on, and review inside Baz, the way a pull request lives in GitHub.

Repo layout

.claude-plugin/plugin.json      CC plugin manifest (MCP server + skills + hooks)
.codex-plugin/plugin.json       Codex CLI plugin manifest
.cursor-plugin/plugin.json      Cursor plugin manifest

tests/hooks.test.js             Process-level hook tests, no dependencies: `node tests/hooks.test.js`. CI runs them.

hooks/
  hook-io.js                    Shared: failSoft() + readHookInput(). Every hook calls both first — see "Hooks must never exit non-zero".
  session-start.js              Shared: emits additionalContext telling the assistant the session id + cwd repo (allowlist-validated), so it passes them through to baz MCP tools for session correlation. Handles `cwd` (CC/Codex) and `workspace_roots[0]` (Cursor).
  plan-complete.js              Shared completion trigger: prompts the agent to ASK the user whether to upload the plan, then call mcp__baz__update_plan only on a yes (see "Upload requires user consent"). Branches on tool_name — ExitPlanMode (CC plan mode) always fires; file-write tools (Write/Edit/apply_patch/edit_file/write_file) fire only when the path's basename matches .baz-plan-<sessionId>.md, wherever the scratch directory resolves to. CC wires both branches; Cursor/Codex have no ExitPlanMode and rely on the file-write branch. Exits quietly if the plan text can't be extracted — update_plan requires content.
  post-tool-use.js              Shared: increments per-tool counter in the scratch dir on each Baz MCP call
  session-end.js                Shared: prints call summary to console at session end, cleans up the scratch dir (and reaps pre-upgrade /tmp leftovers)

  plan-attach.js                Claude Code only: PreToolUse on mcp__baz__update_plan and mcp__baz__link_plan_to_pr. Fills update_plan with the plan parked by plan-complete.js, so the plan is generated once instead of being re-typed into the call, and fills link_plan_to_pr's planId with the session id. Adds only what is missing, so a call that already carries content (Codex/Cursor) or its own planId passes through.

  hooks.json                    CC hooks: SessionStart + PreToolUse (mcp__baz__update_plan|mcp__baz__link_plan_to_pr) + PostToolUse (mcp__baz__ + Write|Edit) + SessionEnd, ${CLAUDE_PLUGIN_ROOT}
  hooks.codex.json              Codex hooks: SessionStart + PostToolUse (mcp__baz__ + apply_patch|Write|Edit) + Stop, ${PLUGIN_ROOT}
  hooks.cursor.json             Cursor hooks: sessionStart + postToolUse (mcp__baz__ + edit_file|write_file|Write|Edit) + stop (stop-token-tally.js only). No session-end wiring — Cursor's validator does not accept `sessionEnd`; see Hook counter mechanics for the counter-file trade-off. ${CURSOR_PLUGIN_ROOT}

skills/baz-codebase-exploration/SKILL.md   Reference skill: auto-loaded tool-routing rules
skills/plan-with-baz/SKILL.md              Task skill: manual /baz:plan-with-baz planning command
skills/get-plan-comments/SKILL.md          Task skill: /baz:get-plan-comments pulls a plan's review comments back
skills/review/SKILL.md                     Task skill: /baz:review diff review, cross-repo checks via Baz
.cursor/rules/baz-codebase-exploration.mdc Reference skill, Cursor rules format (always-apply)