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.

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