---
name: audit-claude-settings
description: Use when auditing Claude Code settings and env vars against the latest docs to suggest tailored changes
allowed-tools:
  - Bash(curl -sfL https://code.claude.com/*)
  - Bash(python3 -m json.tool:*)
  - Bash(strings:*)
  - Read(~/.claude/**)
---

# 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

```bash
curl -sfL https://code.claude.com/docs/en/settings.md -o <scratchpad>/cc-docs-settings.md
curl -sfL https://code.claude.com/docs/en/settings-reference.md -o <scratchpad>/cc-docs-settings-reference.md
curl -sfL https://code.claude.com/docs/en/env-vars.md -o <scratchpad>/cc-docs-env-vars.md
```

Every docs page has a raw markdown mirror at its URL plus `.md`. `<scratchpad>` is your session's scratchpad directory, or `/tmp` when the harness provides none. `-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.md` lists every variable as one table row under `## Variables`, and that row is its whole entry. Grep both for the full lists, then read the `###` entry of every key the user sets in full — the entries carry the defaults, deprecations, and precedence the index table omits. 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 — invalid JSON makes Claude Code skip the whole file. Say which picks land later, per the "When edits take effect" section of `settings.md`.

## 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.