beads/cmd/bd/setup
Julian Knutsen 1de9b59324
fix(setup): bd setup claude --global manages the section in ~/.claude/CLAUDE.md, not the current directory (#7696)
* 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>
2026-10-19 12:22:04 +00:00
..
testdata fix(setup): bd setup claude --global manages the section in ~/.claude/CLAUDE.md, not the current directory (#7696) 2026-10-19 12:22:04 +00:00
agent_skill.go cleanup: remove unused private helpers (#4205) 2026-05-27 17:53:16 -07:00
agents.go fix(setup): bd setup claude --global manages the section in ~/.claude/CLAUDE.md, not the current directory (#7696) 2026-10-19 12:22:04 +00:00
agents_marker_test.go fix(setup): leave a current agents-file beads section untouched (#7693) 2026-10-19 08:45:04 +00:00
aider.go fix(cli): printed doc paths point at the new docs locations 2026-07-12 10:37:17 -07:00
aider_test.go : refactor to use RunE, emit usage metrics, skip metrics in CI 2026-06-22 20:44:43 +00:00
BUILD.bazel test(setup): pin the Claude agent artifacts bd init and bd setup claude write (#7678) 2026-10-19 05:19:28 +00:00
claude.go fix(setup): bd setup claude --global manages the section in ~/.claude/CLAUDE.md, not the current directory (#7696) 2026-10-19 12:22:04 +00:00
claude_artifacts_golden_test.go fix(setup): bd setup claude --global manages the section in ~/.claude/CLAUDE.md, not the current directory (#7696) 2026-10-19 12:22:04 +00:00
claude_test.go fix(setup): bd setup claude --global manages the section in ~/.claude/CLAUDE.md, not the current directory (#7696) 2026-10-19 12:22:04 +00:00
codex.go test,ci(cmd/bd): run the Dolt-gated cmd/bd suite (advisory Bazel lane), fix in-process runner leaks and rotted tests; init --quiet stays quiet (#7185) 2026-10-04 03:06:54 -07:00
codex_test.go fix(setup): migrate legacy Codex session hook (#4953) 2026-07-22 21:20:04 -07:00
constants.go feat: add context optimization features for AI agents (#297) 2025-11-12 10:48:36 -08:00
cursor.go test,ci(cmd/bd): run the Dolt-gated cmd/bd suite (advisory Bazel lane), fix in-process runner leaks and rotted tests; init --quiet stays quiet (#7185) 2026-10-04 03:06:54 -07:00
cursor_test.go feat(cursor): bring Cursor integration to parity with Claude/Codex (#4649) 2026-07-10 13:10:46 -07:00
exit.go : refactor to use RunE, emit usage metrics, skip metrics in CI 2026-06-22 20:44:43 +00:00
factory.go : refactor to use RunE, emit usage metrics, skip metrics in CI 2026-06-22 20:44:43 +00:00
factory_test.go fix(setup): stop leaving a blank-line hole on --remove (#7692) 2026-10-19 08:28:18 +00:00
gemini.go fix(setup): route Claude hook-removal lines through the installer output (#7691) 2026-10-19 07:44:30 +00:00
gemini_test.go fix(setup): finish hook JSON migration 2026-05-08 09:21:39 -07:00
hooks_json.go feat(cursor): bring Cursor integration to parity with Claude/Codex (#4649) 2026-07-10 13:10:46 -07:00
junie.go feat: add bd unclaim command to release stuck issues (replaces #3694) (#4614) 2026-07-06 22:51:35 -07:00
junie_test.go : refactor to use RunE, emit usage metrics, skip metrics in CI 2026-06-22 20:44:43 +00:00
mux.go : refactor to use RunE, emit usage metrics, skip metrics in CI 2026-06-22 20:44:43 +00:00
mux_test.go fix(setup): harden symlink follow-up handling 2026-05-27 13:32:00 -07:00
opencode.go : refactor to use RunE, emit usage metrics, skip metrics in CI 2026-06-22 20:44:43 +00:00
opencode_test.go feat: add OpenCode recipe to bd setup 2026-03-03 13:39:56 -07:00
plugin_layout_test.go fix(plugin): make command argument hints strings (#4969) 2026-07-22 21:48:45 -07:00
project_output.go test,ci(cmd/bd): run the Dolt-gated cmd/bd suite (advisory Bazel lane), fix in-process runner leaks and rotted tests; init --quiet stays quiet (#7185) 2026-10-04 03:06:54 -07:00
project_output_test.go test,ci(cmd/bd): run the Dolt-gated cmd/bd suite (advisory Bazel lane), fix in-process runner leaks and rotted tests; init --quiet stays quiet (#7185) 2026-10-04 03:06:54 -07:00
setup_test_helpers.go : refactor to use RunE, emit usage metrics, skip metrics in CI 2026-06-22 20:44:43 +00:00
utils.go fix(setup): harden symlink follow-up handling 2026-05-27 13:32:00 -07:00
utils_test.go fix(setup): harden symlink follow-up handling 2026-05-27 13:32:00 -07:00