Audit Claude Code Settings

Scan the three reference pages exhaustively, cross-reference them against the user's real config, deliver a ranked report, and apply what the user picks. Tie every suggestion to a named user fact — tailored, not generic.

1. Fetch ground truth

curl -sfL https://code.claude.com/docs/en/settings.md -o /tmp/cc-docs-settings.md
curl -sfL https://code.claude.com/docs/en/settings-reference.md -o /tmp/cc-docs-settings-reference.md
curl -sfL https://code.claude.com/docs/en/env-vars.md -o /tmp/cc-docs-env-vars.md

Every docs page has a raw markdown mirror at its URL plus .md. Write to your session's scratchpad directory instead of /tmp when the harness provides one. -f makes a missing page a failed command instead of a silently saved 404 body. These three files are the only acceptable source for the scan.

settings-reference.md holds every key: the table under its ## Settings index heading is one row per key with purpose, topic, and scope, and each key has a ### \key`entry below.env-vars.mdhas the same shape under## Variables. Grep both tables for the full key lists, then read the entry of every key and variable the user sets in full — the entries carry the defaults, deprecations, and precedence the tables omit. Read settings.md` whole for scope and precedence rules. The first line of each file points to https://code.claude.com/docs/llms.txt, the index of every docs page, for follow-ups such as permission rule syntax, hooks, and sandboxing.

2. Collect the user's real config

Read every settings scope that exists: ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, and the OS's managed settings file if present. When a dotfiles repo is the source of truth, read the repo copy and run git diff on it — uncommitted drift matters in step 5.

Read ~/.claude/CLAUDE.md, the project CLAUDE.md, rules files, and auto-memory. These carry the workflow signals that make suggestions tailored: plugins, hooks, shell aliases, permission style, model choice, terminal, background-agent habits.

Done when you hold one list of every key and env var the user sets, plus a short profile of how they work.

3. Cross-reference

Two passes, both exhaustive:

• Validate (set → docs). Check every user key against all three files. Absent from all three → dead-key candidate; confirm against the binary (see Gotchas) before proposing removal. Named a legacy alias → propose the migration. Default or semantics changed → flag it. No key skipped.
• Discover (docs → unset). Walk every documented key and variable once. Keep a candidate only when a specific user fact argues for it, and name that fact in the item.

4. Report

Open with problems in the current config, ranked by impact. Then grouped suggestions: security, workflow, small ideas. Close with leave-alone items — attractive switches that break something the user relies on (example: the blanket telemetry kills also disable Remote Control, cross-session messages, and auto-updates).

Each item carries the key, what it does in one line, and the user fact that makes it relevant.

5. Apply

Offer the picks with AskUserQuestion, multiSelect, grouped like the report. When the settings file already has uncommitted changes, commit those first as their own commit.

Apply the picks and validate with python3 -m json.tool after edits — a user or project settings file with one invalid entry is rejected as a whole. Say which picks land later: model and outputStyle load at startup only, keys that shape the system prompt land on /clear or restart, and env entries reload live.

Gotchas

• WebFetch answers through a small summarizer model. On a "list everything" prompt against a long page it truncates, and on a "continue the list" prompt it fabricates plausible keys (observed: rubyCrimsionPath). The raw .md mirror is the ground truth; fetch it with curl and read it yourself.
• Undocumented is not the same as dead. A key can live on a different docs page — skillOverrides sat on the skills page before the settings page listed it. Grep all three files, then check llms.txt pages, before you call a key dead.
• The installed CLI binary has the final say on undocumented keys and env vars: strings -a "$(which claude)" | grep -o -E '.{300}<name>.{300}'. Zero hits means dead; hits mean live code reads it, and the surrounding minified code tells you what it actually does — read it before proposing any change. Observed both failure modes: a docs-only audit flagged skipAutoPermissionPrompt dead while a migration in the binary still read it, and CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 turned out to force every session to start in default (manual) permission mode, silently overriding defaultMode: "auto" with no warning shown.
• The $schema line (https://json.schemastore.org/claude-code-settings.json) gives editors validation, but the published schema lags new CLI releases. A schema warning on a recently documented key is not proof of a dead key.
• Docs churn fast. Results from a previous audit go stale; fetch fresh files every run, and treat remembered page content as expired.