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 (8 patterns: cache-breaking, redundant perms, deep imports, oversized cascade, bloated SKILL.md desc, MCP tool-schema budget, MCP tool-schema deferral, stale plugin-cache disk-cleanup), each ranked hotspot tagged with its load pattern (always / on-demand / external) — cache-aware (stale ~/.claude/plugins/cache versions excluded by default; only each plugin's active version counts; --no-exclude-cache for the full walk), optional --accurate-tokens API calibration, --with-telemetry-recipe cache-hit recipe pointer
/config-audit manifest	Ranked table of every token source (CLAUDE.md, rules, agents, skills, output styles, MCP, hooks) sorted by estimated tokens, each tagged with its load pattern (always-loaded / on-demand / external) + an always-loaded subtotal ("tokens that enter context every turn")
/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 optimize	Optimization lens (mechanism-fit) — config that works but fits a better mechanism: procedure→skill (CA-OPT-001, deterministic), lifecycle→hook / unscoped path→rule / "never"→permission (prose-judgment via opus optimization-lens-agent). Hybrid motor; every finding cites a best-practices-register rule. Agent-driven, not byte-stable
/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 knowledge-refresh	Keep the best-practices register fresh — deterministic stale check (sources older than ~90d) + web candidate poll (CC changelog + Anthropic blog); human-approved writes only (Verifiseringsplikt). The "living" half of the knowledge base. Web/judgment-driven, not byte-stable
/config-audit campaign	Machine-wide audit campaign — durable ledger ABOVE sessions: per-repo lifecycle (pending→audited→planned→implemented) + machine-wide roll-up by severity + machine-wide always-loaded token bill (refresh-tokens live cross-repo sweep — shared global layer counted once + per-repo deltas) + cross-repo prioritized backlog + plan export (drop a planned repo's plan into its own docs/), resumable across sessions. Read-only report (campaign-cli) + human-approved writes via deterministic write/export CLIs. THIN: tracks+routes state, reuses existing implement/rollback for execution. Judgment-driven, not byte-stable
/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
optimization-lens-agent	Mechanism-fit precision gate (prose-judgment lens cases)	opus	orange	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, per-scanner/per-block implementation notes: 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, CA-OST-001, CA-OPT-001, CA-AGT-001

Conventions

Enforced project conventions live in .claude/rules/ (auto-loaded as project instructions):

• ux-rules.md — output/narration/formatting rules for all commands (never dump raw JSON, narrate before each step, space-separated command suggestions)
• command-development.md — required command frontmatter + plugin:action naming
• state-management.md — update state.yaml after every workflow phase

Coding style: scanners are zero-dependency Node ESM; new findings use the CA-{SCANNER}-{NNN} ID format; byte-stable CLIs are verified against frozen tests/snapshots/v5.0.0/ baselines.

Testing

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

1257 tests across 71 test files (22 lib + 39 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.

Per-scanner and per-build-block implementation notes (design rationale, primary-source verification, byte-stability lessons) live in docs/scanner-internals.md → Implementation notes.

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