Skip to content

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.py mirrors settings.json, redacted, and no longer mirrors settings.user.json.
  • settings.user.json is 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 _generated block is removed from settings.json. The file is not generated; that block was the single thing convincing readers otherwise.
  • bash-arbiter.py drops settings.user.json from 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.json shows env as <redacted>, so the mirror is not a restore-from-backup source for env values. It never was for settings.user.json either.
  • settings.json changes 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 scans settings.user.json deliberately, 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.