Skip to content

Use CLAUDE.local.md instead of CLAUDE.md for Claude Code project context - #78

Open
rickalee wants to merge 4 commits into
10up:mainfrom
rickalee:feature/use-claude-local-md
Open

rickalee wants to merge 4 commits into
10up:mainfrom
rickalee:feature/use-claude-local-md

Conversation

@rickalee

@rickalee rickalee commented Jun 1, 2026

Copy link
Copy Markdown
Contributor

Closes #77

Summary

  • Changes the Claude Code agent target to write site context into CLAUDE.local.md instead of CLAUDE.md
  • Updates .gitignore entry from CLAUDE.md to CLAUDE.local.md
  • Adds a one-time migration (migrateClaude) that removes any existing Agent Tools marker block from CLAUDE.md on the next enable or regenerate — leaving the rest of the file intact

Why

CLAUDE.local.md is Claude Code's native file for machine-specific, uncommitted project context. It loads automatically alongside CLAUDE.md without interfering with it. Writing to CLAUDE.md causes friction for teams that have a committed CLAUDE.md with shared project instructions — either the add-on appends to it (requiring a gitignored workaround) or users reach for git update-index --skip-worktree.

Test plan

  • Enable Agent Tools on a fresh site with no CLAUDE.md → context appears in CLAUDE.local.md, not CLAUDE.md
  • Enable Agent Tools on a site that already has a committed CLAUDE.mdCLAUDE.md is not modified
  • Enable Agent Tools on a site that has an old-style CLAUDE.md with marker block → block is removed from CLAUDE.md and written to CLAUDE.local.md
  • Disable Agent Tools → CLAUDE.local.md is cleaned up; CLAUDE.md unchanged
  • Regenerate config → same migration behaviour as enable

🤖 Generated with Claude Code

Claude Code's CLAUDE.local.md is the correct home for machine-specific,
uncommitted project context — it sits alongside a committed CLAUDE.md
without interfering with it. This change updates the claude agent target
to write there instead, and adds a one-time migration that strips any
existing Agent Tools marker block from CLAUDE.md on the next enable or
regenerate.

Fixes 10up#77
@rickalee
rickalee requested a review from christianc1 as a code owner June 1, 2026 16:55
@claytoncollie

Copy link
Copy Markdown
Contributor

@christianc1 quick one on this PR from @rickalee. It moves the generated Claude Code context file from CLAUDE.md to CLAUDE.local.md and adds a one-time migration that strips our marker block out of any existing CLAUDE.md. The reasoning holds up: the file contains machine-specific paths, the MCP port, and the site id, which is exactly what Claude Code says CLAUDE.local.md is for. It also stops us from writing into a file that teams commit.

One trade-off. A team that committed the generated block on purpose will see it removed on the next enable or regenerate.

I caught the branch up with main today and pushed three small fixes so it is ready to go:

  • The legacy CLAUDE.md cleanup now also runs on disable, project directory change, and agent add or remove. Before, those paths only removed the new file, so an upgraded user could keep a stale block in CLAUDE.md that was no longer gitignored.
  • The marker check moved into a tested helper in src/helpers/utils.ts, which also cleared the Prettier failure.
  • README and changelog now name CLAUDE.local.md, and the changelog links this PR.

CI is green. Any objection to merging?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Use CLAUDE.local.md instead of CLAUDE.md for Claude Code project context

2 participants