settings.json is the settings authority; settings.user.json is retired¶
- Date: 2026-08-25
- Status: Accepted
- Tags:
tooling
Context¶
The harness mirror recorded settings.user.json as the authored source and treated
settings.json as a build artifact. inventory.py said so in a comment:
settings.user.json is the authored source. settings.json carries
_generated{by: merge-plugin-hooks.py}— a build artifact, not config.
That was backwards, and the mirror had been recording a stale file as the truth.
Claude Code loads settings.json, and the CLI's /config writes it directly. So the
"generated" file accumulates real choices the "source" never sees, and the source rots.
Measured 2026-08-25: settings.user.json was four days behind and still held 66 Bash
permissions.allow rules — the complete pre-arbiter set, Bash(aws *) included — which
had just been deliberately reduced to 5.
merge-plugin-hooks.py reads that file and overwrites settings.json. It now lives under
plugins/marketplaces/rlm-claude-code/scripts/legacy/, is wired to nothing, and is
manual-invocation only. Measured via its own --dry-run, a regenerate would have deleted
effortLevel: "high", all 9 skillOverrides, skipWorkflowUsageWarning,
tui: "fullscreen" and permissions.defaultMode: "auto", and re-enabled four
deliberately-disabled plugins. Keeping the stale file in place kept a loaded gun pointed at
the live configuration.
Two details made the wrong belief durable. The _generated block inside settings.json
announced the file as generated, so every reader — human and script — reasonably concluded
it was derived. And inventory.py already read settings.json as live in
plugin_inventory() for enabledPlugins, so the script contradicted itself and neither
half looked wrong on its own.
Decision¶
~/.claude/settings.json is the authority. Specifically:
inventory.pymirrorssettings.json, redacted, and no longer mirrorssettings.user.json.settings.user.jsonis retired to~/.claude/backups/2026-08-25-settings-user-json-retired/with a README recording why. The generator's source no longer exists, which defuses it without deleting a third-party script that a plugin update would restore anyway.- The
_generatedblock is removed fromsettings.json. The file is not generated; that block was the single thing convincing readers otherwise. bash-arbiter.pydropssettings.user.jsonfrom its deny-rule sources.
Mirroring settings.json is safe despite it carrying a live 64-char OBSIDIAN_API_KEY:
redact() blanks the whole env dict and substitutes every ≥16-char literal before
anything is written. Verified for this run — the key appears nowhere under
claude/harness/.
Alternatives Considered¶
| Option | Why Rejected |
|---|---|
Re-seed settings.user.json from the live file |
Preserves the two-file split whose only function is to let them diverge. The next /config write re-opens the same gap, silently. |
Delete merge-plugin-hooks.py |
It lives inside a plugin marketplace checkout; a plugin update restores it. Removing its input is durable, removing the script is not. |
| Leave the file, fix only the comment | The 66 stale allow rules stay one manual command away from overwriting the live config. A comment does not disarm that. |
Keep mirroring settings.user.json and also mirror settings.json |
Records two settings files with no statement of which is authoritative — the ambiguity that caused this. |
Consequences¶
Positive:
- The mirror records what Claude Code actually loads.
- The generator cannot silently revert live configuration: its input is gone.
- One settings file, one authority, stated in one place.
Negative / Trade-offs:
- The mirrored
settings.jsonshowsenvas<redacted>, so the mirror is not a restore-from-backup source for env values. It never was forsettings.user.jsoneither. settings.jsonchanges more often than the stale file did, so this path will show up in more weekly diffs. That is the mirror doing its job.
Ongoing obligations:
- If a future Claude Code version reintroduces a real generated-settings flow, supersede this ADR rather than editing it.
secret_values()still scanssettings.user.jsondeliberately, so a restored copy holding the same key is still caught. Leave that in.
ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.