ktg-plugin-marketplace/plugins/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	Opus-4.7-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
/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

Deterministic Scanners

Node.js scanners (zero external dependencies), run via node scanners/scan-orchestrator.mjs <path>. Posture CLI: node scanners/posture.mjs <path> [--json] [--global] [--full-machine] [--output-file path]. Scanner CLI: node scanners/scan-orchestrator.mjs <path> [--global] [--full-machine] [--no-suppress].

Scanner	Prefix	Detects
claude-md-linter.mjs	CML	Structure, length, sections, @imports, duplicates, TODOs
settings-validator.mjs	SET	Schema, unknown/deprecated keys, type mismatches, permissions
hook-validator.mjs	HKV	Format, script existence, event validity, timeouts
rules-validator.mjs	RUL	Glob matching, orphan rules, deprecated fields, unscoped rules
mcp-config-validator.mjs	MCP	Server types, trust levels, env vars, unknown fields
import-resolver.mjs	IMP	Broken @imports, circular refs, deep chains, tilde paths
conflict-detector.mjs	CNF	Settings conflicts, permission contradictions, hook duplicates
feature-gap-scanner.mjs	GAP	25 feature checks across 4 tiers — shown as opportunities, not grades
token-hotspots.mjs	TOK	Cache-breaking volatile content, redundant tool permissions, deep import chains, oversized cascade, bloated SKILL.md descriptions, MCP tool-schema budget (Opus 4.7 patterns)
cache-prefix-scanner.mjs	CPS	Volatile content in lines 31–150 of CLAUDE.md cascade (beyond Pattern A's top-30 window)
disabled-in-schema-scanner.mjs	DIS	Tools listed in BOTH permissions.deny AND permissions.allow — deny wins, allow entries are dead config
collision-scanner.mjs	COL	Cross-plugin skill name collisions (low); user-vs-plugin overlaps (medium); details.namespaces payload

Scanner Lib (scanners/lib/)

Module	Purpose
severity.mjs	Severity constants, risk scoring, verdict logic, WEIGHTS named export (v5 F3)
output.mjs	Finding objects (CA-XXX-NNN format), scanner results, envelope, optional details payload (v5 N6)
file-discovery.mjs	Config file discovery: single-path, multi-path (discoverConfigFilesMulti), full-machine (discoverFullMachinePaths)
yaml-parser.mjs	Frontmatter parsing, JSON parsing, @import/section extraction
string-utils.mjs	Line counting, truncation, similarity, key extraction
scoring.mjs	Severity-weighted scoreByArea (v5 F3), health scorecard, dedup-by-area (v5 N3), scoringVersion: 'v5'
backup.mjs	Backup creation, manifest parsing, checksum verification
diff-engine.mjs	Drift diffing: diffEnvelopes(), formatDiffReport()
baseline.mjs	Baseline save/load/list/delete for drift detection
report-generator.mjs	Unified markdown reports: posture, drift, plugin health
suppression.mjs	.config-audit-ignore parsing, finding suppression, audit trail
active-config-reader.mjs	Read-only inventory: readActiveConfig(), detectGitRoot(), walkClaudeMdCascade(), readClaudeJsonProjectSlice() (longest-prefix match), enumeratePlugins(), enumerateSkills(), readActiveHooks(), readActiveMcpServers() (with cache → package.json tool-count fallback), estimateTokens() (v5: 'mcp' kind = 500 + toolCount × 200)
tokenizer-api.mjs	Anthropic count_tokens wrapper for --accurate-tokens (v5 N5); 5s AbortController timeout, exponential 429 backoff, key masking
humanizer.mjs	Plain-language output translator (v5.1.0): humanizeFinding, humanizeFindings, humanizeEnvelope, computeRelevanceContext. Pure functions; never mutate inputs. Adds userImpactCategory, userActionLanguage, relevanceContext fields and replaces title/description/recommendation when a translation exists. Bypassed by --raw and --json paths.
humanizer-data.mjs	TRANSLATIONS table for 13 scanner prefixes (CML/SET/HKV/RUL/MCP/IMP/CNF/COL/TOK/CPS/DIS/GAP/PLH). Three-step lookup: exact title → regex pattern → _default → fall through to original

Action Engines (scanners/)

Module	Purpose
fix-engine.mjs	planFixes(), applyFixes(), verifyFixes() — 9 fix types
rollback-engine.mjs	listBackups(), restoreBackup(), deleteBackup()
fix-cli.mjs	CLI: node fix-cli.mjs <path> [--apply] [--json] [--global]
drift-cli.mjs	CLI: node drift-cli.mjs <path> [--save] [--baseline name] [--json]
whats-active.mjs	CLI: node whats-active.mjs <path> [--json] [--verbose] [--suggest-disables] — read-only active-config inventory
token-hotspots-cli.mjs	CLI: node token-hotspots-cli.mjs <path> [--json] [--global] [--output-file path] [--accurate-tokens] [--with-telemetry-recipe] — Opus-4.7 token hotspots ranking with optional API calibration
manifest.mjs	CLI: node manifest.mjs <path> [--json] — ranked system-prompt token-source table (v5 N2)

Standalone Scanner

Module	Prefix	Purpose
plugin-health-scanner.mjs	PLH	Plugin structure, frontmatter, cross-plugin conflicts (runs independently)
self-audit.mjs	—	Runs all scanners + plugin health on this plugin itself

Knowledge Base (knowledge/)

File	Content
claude-code-capabilities.md	Feature register: 18 config surfaces, Anthropic guidance, relevance table
configuration-best-practices.md	Per-layer best practices (v5: Opus 4.7 cache-stability guidance replaces Sonnet-era 200-line rule)
anti-patterns.md	Common mistakes mapped to scanner IDs
hook-events-reference.md	All 26 hook events with details
feature-evolution.md	Feature timeline for staleness detection
gap-closure-templates.md	Config-specific templates for closing gaps
opus-4.7-patterns.md	Token-cost dynamics for Opus 4.7 era — patterns powering the TOK scanner
cache-telemetry-recipe.md	Manual jq recipe for verifying prompt-cache hit rate from session transcripts (v5 M7)

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

Plain-Language Output (v5.1.0)

Default output of all 18 commands routes through humanizeEnvelope from lib/humanizer.mjs. Findings are decorated with three additive fields and may have title/description/recommendation replaced when a translation exists.

Output modes

Flag	Behavior
(default, no flag)	Plain-language: humanizer applied, findings group by user-impact, titles lead with prose. Self-audit terminal render also humanized.
--raw	Byte-stable v5.0.0 verbatim — humanizer bypassed, technical IDs and severity-only labels. For tooling that scrapes stderr from v5.0.0.
--json	Unchanged from v5.0.0 — humanizer bypassed, byte-stable JSON envelope. Always preferred for programmatic consumption over --raw.
--output-file <path>	Writes raw v5.0.0-shape JSON (humanizer bypassed). Posture-specific.

--raw is threaded through every CLI: posture.mjs, scan-orchestrator.mjs, token-hotspots-cli.mjs, manifest.mjs, whats-active.mjs, fix-cli.mjs, drift-cli.mjs, self-audit.mjs.

Vocabularies

User-impact category (added to each finding as userImpactCategory, derived from scanner prefix):

Label	Scanners
Configuration mistake	CML, SET, HKV, RUL, MCP, IMP, PLH
Conflict	CNF, COL
Wasted tokens	TOK, CPS
Dead config	DIS
Missed opportunity	GAP

Action language (added to each finding as userActionLanguage, derived from severity):

Severity	Phrase
critical	Fix this now
high	Fix soon
medium	Fix when convenient
low	Optional cleanup
info	FYI

Relevance context (added to each finding as relevanceContext, computed from finding's file path):

Value	When
test-fixture-no-impact	Path contains /tests/fixtures/ or /test/fixtures/
affects-this-machine-only	Basename matches *.local.* (e.g., settings.local.json)
affects-everyone	Default — assumed shared/committed config

Wave 5 lessons

• Posture's stderr scorecard is rendered prose-side and is not part of the JSON envelope; humanized.areas[].titleHumanized referenced by command templates lives only in the prose render.
• Posture's --output-file writes raw v5.0.0-shape JSON because posture.mjs does not call humanizeEnvelope. If session-files should later be humanized, posture needs its own humanize pass — out of v5.1.0 scope.
• The default-output snapshot at tests/snapshots/default-output/posture.json is frozen — change requires UPDATE_SNAPSHOT=1 plus intent confirmation.

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

Testing

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

792 tests across 52 test files (15 lib + 28 scanner + 1 hook + 1 agent + 3 commands + 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.

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