[jpmontez]

Problem

~/.claude/settings.json is stowed from this repo, but Claude Code owns that file — it rewrites the whole thing whenever a runtime option changes. Every /model switch left the tree dirty with a key reorder plus a one-line model change.

There's no env var or setting to redirect where Claude Code persists this; the only non-written settings source is the --settings flag, which is per-invocation and wouldn't cover desktop-app or IDE launches (so the permissions.deny rules would silently not apply there).

Fix, in two halves

Neither half is sufficient alone.

1. Clean filter — keeps commits clean. .gitattributes routes the file through claude-settings-clean.py, which drops the keys Claude Code writes back as machine state (model, theme, sandbox, modelSettings) and sorts the rest, so a rewrite in a different key order isn't a diff either. Invalid JSON round-trips untouched rather than wedging git.

2. skip-worktree — keeps git status clean. A clean filter alone does not quiet git status: git's index-refresh path hashes the worktree file raw, and only the diff machinery applies the filter. So the file reads as modified even when it cleans to exactly the committed blob:

$ git status --porcelain     #  M claude/.claude/settings.json
$ git diff --numstat         #  (empty)
$ git hash-object --path claude/.claude/settings.json claude/.claude/settings.json
730cd9e...                   #  identical to the index blob

Reproduced in an isolated repo on git 2.55.0; filter.<name>.required does not change it.

Wiring

Both are per-clone git state that .gitattributes can't carry, so bootstrap.sh sets them and doctor.sh reports a clone missing either — the same install/detect split as the Brewfiles.

== Repo
  ✓ Claude settings clean filter registered
  ✓ Claude settings marked skip-worktree
  ✓ working tree clean

Cost

Committing a deliberate change to that settings file needs a toggle (--no-skip-worktree, commit, --skip-worktree). Documented in CLAUDE.md, since while it's hidden git ignores edits you meant to keep.

Verification

Simulated a /model switch (model + theme changed, top-level keys reordered) against a clean tree: git status stayed empty, and the live file kept every setting. shellcheck bootstrap.sh doctor.sh lib.sh macos/*.sh clean. ./doctor.sh green.

Also ignores **/.claude/.cc-writes/, which Claude Code creates inside the repo.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AEPYeZgMsmFPVBbRvkFtM2