config-audit/CLAUDE.md

Config-Audit Plugin

Claude Code Configuration Intelligence — know if your configuration is correct, find what could improve it, fix it automatically.

What this plugin does

Analyzes and optimizes Claude Code configuration across three pillars:

• Health — Deterministic scanners verify correctness, consistency, and completeness
• Opportunities — Context-aware recommendations for features that could benefit your project
• Action — Auto-fix with backup/rollback

Commands

Core (just run /config-audit to get started)

Command	Description
/config-audit	Full audit with auto-scope detection (no setup needed)
/config-audit posture	Quick health scorecard (A-F grades, 10 quality areas incl. Token Efficiency, Plugin Hygiene)
/config-audit tokens	prompt-cache-aware token hotspots (6 patterns: cache-breaking, redundant perms, deep imports, oversized cascade, bloated SKILL.md desc, MCP tool-schema budget) — optional --accurate-tokens API calibration, --with-telemetry-recipe cache-hit recipe pointer
/config-audit manifest	Ranked table of every system-prompt token source (CLAUDE.md, plugins, skills, MCP, hooks) sorted by estimated tokens
/config-audit feature-gap	Context-aware feature recommendations grouped by impact (incl. a conditional disableBundledSkills lever when the active skill listing is over budget — remediation companion to SKL CA-SKL-002)
/config-audit fix	Auto-fix deterministic issues with backup + verification
/config-audit rollback	Restore configuration from backup
/config-audit plan	Create action plan from audit findings
/config-audit implement	Execute plan with backups + auto-verify
/config-audit help	Show all commands

Additional

Command	Description
/config-audit drift	Compare current config against saved baseline
/config-audit plugin-health	Audit plugin structure, frontmatter, cross-plugin coherence
/config-audit whats-active	Read-only inventory of plugins, skills, MCP, hooks, CLAUDE.md active for a repo (with token estimates)
/config-audit discover	Run discovery phase only
/config-audit analyze	Run analysis phase only
/config-audit interview	Gather user preferences (opt-in)
/config-audit status	Show current session state
/config-audit cleanup	Clean up old sessions

Agents

Agent	Role	Model	Color	Tools
scanner-agent	Find config files	sonnet	cyan	Read, Glob, Grep, Write
analyzer-agent	Generate report	sonnet	blue	Read, Glob, Grep, Write
planner-agent	Create action plan	opus	yellow	Read, Glob, Write
implementer-agent	Execute changes	sonnet	magenta	Read, Write, Edit, Bash, Glob
verifier-agent	Verify results	sonnet	purple	Read, Glob, Grep
feature-gap-agent	Context-aware feature recommendations	opus	green	Read, Glob, Grep, Write

Hooks

Event	Script	Purpose
PreToolUse	auto-backup-config.mjs	Auto-backup config files before Edit/Write
PostToolUse	post-edit-verify.mjs	Verify config files after Edit/Write, block on new critical/high
SessionStart	session-start.mjs	Checks for active (unfinished) sessions
Stop	stop-session-reminder.mjs	Reminds about current session phase

Reference docs (read on demand)

• Scanner inventory, lib modules, action engines, knowledge base: docs/scanner-internals.md
• Plain-language output (v5.1.0), humanizer vocabularies, output modes: docs/humanizer.md

Plain-Language Output (v5.1.0) — summary

Default output of all 18 commands routes through humanizeEnvelope from lib/humanizer.mjs. Findings get three decorated fields:

• userImpactCategory — Configuration mistake / Conflict / Wasted tokens / Dead config / Missed opportunity
• userActionLanguage — Fix this now / Fix soon / Fix when convenient / Optional cleanup / FYI (derived from severity)
• relevanceContext — affects-everyone (default) / affects-this-machine-only (*.local.* files) / test-fixture-no-impact

--raw bypasses the humanizer for byte-stable v5.0.0 output. --json is also byte-stable. Full detail and Wave 5 lessons: docs/humanizer.md.

Suppressions

Create .config-audit-ignore at project root to suppress known findings:

CA-SET-003          # Exact ID
CA-GAP-*            # Glob pattern (all GAP findings)

Suppressed findings tracked in envelope's suppressed_findings for audit trail. Disable with --no-suppress.

Architecture

Workflow

/config-audit  →  discover + analyze (auto)  →  plan  →  implement  →  verify

Default: auto-detects scope from git context. Override with /config-audit full|repo|home|current. Delta mode: --delta (incremental).

Session Directory

~/.claude/config-audit/sessions/{session-id}/
├── scope.yaml, discovery.json, state.yaml
├── findings/, analysis-report.md, action-plan.md
├── backups/, implementation-log.md
└── interview.md (if interview run)

Finding ID Format

CA-{SCANNER}-{NNN} — e.g. CA-CML-001, CA-SET-003, CA-HKV-002, CA-RUL-005, CA-TOK-005, CA-CPS-001, CA-DIS-001, CA-COL-001, CA-SKL-001

Testing

node --test 'tests/**/*.test.mjs'

936 tests across 56 test files (17 lib + 29 scanner + 1 hook + 1 agent + 3 commands + 1 knowledge + 4 top-level). Test fixtures in tests/fixtures/. Top-level humanizer tests: json-backcompat.test.mjs, raw-backcompat.test.mjs, scenario-read-test.test.mjs, snapshot-default-output.test.mjs.

CML scanner — context-window-scaled char budget

Beyond the line-count checks (200/500 lines, both MEDIUM), the CML scanner mirrors Claude Code's own startup warning — "Large CLAUDE.md will impact performance (X chars > 40.0k)" — as a char-based finding:

• Char budget — flags a CLAUDE.md over ~40.0k chars (CC's startup-warning figure at a 200k-context model). CC 2.1.169 scales that threshold with the model's context window, so the finding anchors on the conservative 200k window (we cannot observe the user's window; the anchor fires earliest) and discloses the relaxed ~200,000-char figure at 1M context. Severity MEDIUM (token cost, not an adherence cliff). New CA-CML finding.

It keys on chars, not lines, so it is complementary to the line checks: a file can be long by lines yet under budget (short lines), or short by lines yet over it (long lines). The 200k/1M window constants live in the shared scanners/lib/context-window.mjs (single source of truth, also re-exported by skill-listing-budget.mjs). The 40.0k figure and context-window scaling are verified against the CC changelog (2.1.169) and the live startup-warning text.

DIS scanner — permission-rule hygiene

Beyond deny/allow overlap, the DIS scanner now also flags:

• Ineffective allow wildcards — unanchored tool-name globs in permissions.allow (*, B*, mcp__*) that Claude Code silently skips (auto-approve nothing). Valid only as a glob-free mcp__<server>__*. New CA-DIS finding, severity low.
• Tool(*) deny-all glob — treated as equivalent to a bare deny (Bash(*) ≡ Bash), so a bare allow killed by it is correctly reported as dead config.
• Forbidden-param rules — Tool(param:value) whose key is the tool's own canonicalizing field (command for Bash/PowerShell, file_path for Read/Edit/Write, path for Grep/Glob, notebook_path for NotebookEdit, url for WebFetch). CC ignores these and emits a startup warning. Severity follows intent: deny/ask = false security (medium) — the block never applies; allow = dead config (low) — param:value matching is deny/ask-only. Valid forms (Bash(npm:*), WebFetch(domain:host), Agent(model:opus)) are never flagged. Predicate forbiddenParamRule in permission-rules.mjs.

These predicates live in scanners/lib/permission-rules.mjs (shared with the CNF conflict-detector). Behavior verified against code.claude.com/docs/en/permissions.

PLH scanner — plugin namespace collision

The standalone PLH scanner (cross-plugin checks in scan()) flags plugin namespace collisions: two or more discovered plugins that declare the same name in plugin.json. The search-first finding that shaped this check: Claude Code namespaces every plugin component by the declared name — /name:command, name:skill, agent name (verified against code.claude.com/docs/en/plugins, and observable in any session's namespaced skill listing). A plugin component therefore can never shadow a user- or project-level one; the only shadow that loses components is a same-name collision, where the namespaces collapse into one and CC must pick a winner. Resolution between two installed same-name plugins is undocumented, so the loser's commands/skills/agents go silently unreachable — hence severity MEDIUM (dead config), category: 'plugin-hygiene', with a COL-shaped details.namespaces payload ({ source: 'plugin:<dir>', name, path }).

Two design notes: (1) the check keys on the declared name field, not basename(dir) — the folder name is irrelevant to the namespace; scanSinglePlugin now returns declaredName for this. (2) Name-less plugins are excluded from the collision map (they are flagged by the missing-field check and must never group on an undefined key).

The sibling cross-plugin command-name check was corrected to match the same model. Because commands are namespaced (/name:command), a command name shared by two differently-named plugins is ambiguity — not a hard conflict — so it now mirrors COL's plugin-vs-plugin skill finding: severity LOW, category: 'plugin-hygiene', COL-shaped details.namespaces, and a group-first shape (one finding per command name listing every namespace, not pairwise). It keys on the declared namespace and fires only when a name spans 2+ distinct namespaces; when two plugins share the same declared name, the namespace-collision finding above is the right (more severe) signal, so the command check stays silent there to avoid a redundant "dup, dup" report. The earlier HIGH Cross-plugin command name conflict finding (basename-keyed, "only one wins") is gone, along with its now-inaccurate humanizer entry.

PLH scanner — plugin-folder shadowing (CA-PLH-015)

Per-plugin check (in scanSinglePlugin, right after the required-field loop): a plugin.json component-path key that replaces its default folder while that folder still exists on disk → the folder is silently ignored (dead config). Severity MEDIUM, category: 'plugin-hygiene', details: { field, ignoredDir, customPaths }. Mirrors Claude Code's own warning in /doctor, claude plugin list, and the /plugin detail view (v2.1.140+).

The field set is primary-source-pinned to the replaces category only — SHADOWING_PATH_FIELDS = commands/agents/outputStyles (defaults commands/, agents/, output-styles/). Deliberately excluded: skills (per code.claude.com/docs/.../path-behavior-rules it adds to the default skills/ scan — both load, never a shadow), and hooks/mcpServers/lspServers (own merge rules, not a folder-shadow). Experimental themes/monitors are omitted because the docs warn their manifest schema may change between releases. The check also honors the doc's explicit-address exception: a custom path that resolves into the default folder ("commands": ["./commands/x.md"]) is not flagged, because Claude Code keeps scanning the folder in that case (addressesDefaultDir predicate). The v5.4.0 plan originally listed commands/agents/skills/hooks; that set was corrected here against the live docs (Verifiseringsplikt).

PLH scanner — skills:-array validation (CA-PLH-016)

Per-plugin check (in scanSinglePlugin, after the shadow check): when plugin.json has a skills field (string or array), each entry must resolve to an existing directory inside the plugin root. The value is normalized Array.isArray(v) ? v : [v], so a single string is one entry — and a non-string top-level value (e.g. 42) is naturally caught as a single non-string entry (no separate top-level check needed). One finding per bad entry, severity MEDIUM, category: 'plugin-hygiene', details: { field: 'skills', entry, problem } where problem is one of non-string / escapes-root / not-found / not-a-directory. Mirrors claude plugin validate (~2.1.145).

Escape detection uses skillsEntryEscapesRoot (resolve + startsWith(pluginDir + sep) containment — robust against a literal ..foo dir name), backed by the docs' path-traversal rule ("Installed plugins cannot reference files outside their directory … such as ../shared-utils"). statOrNull distinguishes missing from file-vs-dir. Verifiseringsplikt note: the v5.4.0 plan claimed CC "suggests the parent directory when an entry points at a file"; that exact error text is not in the primary docs, so it was dropped — the finding asserts only the four primary-source-verified conditions. skills is deliberately not in SHADOWING_PATH_FIELDS (it adds to the default scan, never shadows).

SET scanner — autoMode validation (CA-SET)

Per-file check in settings-validator.mjs (autoMode was in KNOWN_KEYS but had no nested validation). Two sub-checks, both primary-source-verified against code.claude.com/docs/en/auto-mode-config:

1. Structure (severity MEDIUM): autoMode, if present, must be an object whose only keys are environment/allow/soft_deny/hard_deny (AUTO_MODE_SUBKEYS), each a string array (the literal "$defaults" is a valid entry, so it passes the string check for free). problem ∈ not-an-object / unknown-subkey / not-string-array in details.
2. Dead-config (severity LOW): Claude Code does not read autoMode from shared project settings — verbatim: "The classifier does not read autoMode from shared project settings in .claude/settings.json, so a checked-in repo cannot inject its own allow rules." The check keys on file.scope === 'project' (file-discovery's classifyScope returns 'project' for a committed .claude/settings.json; 'local'/'user'/'managed' are read and not flagged). problem: 'shared-project-scope'. This is why the plan's "test per-file scope first" gate passed — ConfigFile already carries scope.

The two sub-checks are independent (a malformed autoMode in shared scope yields both). SET is in the orchestrator, so SC-5 was re-checked after this change — byte-equal (the snapshot fixture has no autoMode, so the block never fires there).

Gotchas

• Session directories accumulate — use /config-audit cleanup to manage
• Scanners run on Node.js >= 18 (uses node:test, node:fs/promises)
• Plugin CLAUDE.md files in node_modules should be excluded via scope