ktg-plugin-marketplace/plugins/config-audit

Config-Audit Plugin for Claude Code

Know if your configuration is correct. Find what could improve it. Fix it automatically.

Built for my own Claude Code workflow and shared openly for anyone who finds it useful. This is a solo project — bug reports and feature requests are welcome, but pull requests are not accepted.

A Claude Code plugin that checks configuration health, suggests context-aware improvements, and auto-fixes issues — CLAUDE.md, settings.json, hooks, rules, MCP servers, @imports, and plugins. 7 quality scanners for correctness, context-aware feature recommendations, auto-fix with backup/rollback. Zero external dependencies.

---

Table of Contents

• What Is This?
• The Configuration Problem
• Quick Start
• Feature Opportunities
• Workflow Examples
• Commands
• Deterministic Scanners
• Agent Architecture
• Hooks & Safety
• Skills
• Suppressions
• Examples & Self-Audit
• Scanner Library
• Knowledge Base
• Testing
• Gotchas
• Data Storage & Safety Guarantees
• What This Plugin Does Not Cover
• Version History
• License

---

What Is This?

Claude Code reads instructions from at least 7 different file types across multiple scopes: CLAUDE.md, settings.json, .claude/rules/, hooks.json, .mcp.json, .claudeignore, and settings.local.json. Each can exist at project level, user level, or both. Plugins add more. The system is powerful — but nobody tells you what you're using wrong, what you're missing, or what's silently conflicting.

This plugin provides three layers of configuration intelligence:

• Health — 7 deterministic scanners verify correctness across every configuration file, catching broken imports, deprecated settings, conflicting rules, format errors, and permission contradictions
• Opportunities — context-aware recommendations for Claude Code features that could benefit your specific project, backed by Anthropic's official guidance
• Action — auto-fix with mandatory backups, syntax validation, rollback support, and a human-in-the-loop workflow for anything non-trivial

Tip

Start with /config-audit posture for a 30-second scorecard, then /config-audit for the full picture.

---

The Configuration Problem

You've been using Claude Code for weeks — maybe months. It works fine. But there's a gap between "works fine" and "configured well," and it's invisible until someone shows you.

These are not hypotheticals. They come from running the posture scanner on real setups:

• Your global CLAUDE.md says "never use mocks" but a project rule says "prefer mocks" — Claude gets confused and you don't know why
• You've written dozens of projects but have never set up hooks, rules, or keybindings because you didn't know they existed
• Three plugins define hooks for the same event with conflicting behavior
• Your settings.json has a deprecated key that silently does nothing
• An @import in your CLAUDE.md points to a file you deleted last week
• You're using maybe 30% of what Claude Code can do — and you don't know what the other 70% is

The plugin ships with two example projects. Run them yourself:

examples/minimal-setup/ — just a CLAUDE.md, nothing else

> node scanners/posture.mjs examples/minimal-setup/

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Config-Audit Health Score
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 Health: A (99/100)    7 areas scanned

 Area Scores
 ───────────
 CLAUDE.md ............ A (90)
 Settings ............. A (100)   Hooks ............... A (100)
 Rules ................ A (100)   MCP ................. A (100)
 Imports .............. A (100)   Conflicts ........... A (100)

 22 opportunities available — run /config-audit feature-gap for recommendations

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Grade A — nothing is broken. The health grade only reflects real issues, and this setup has none. The 22 opportunities are not failures — they're features you could use. Run /config-audit feature-gap to see which ones are relevant to your project.

examples/optimal-setup/ — full configuration across all 4 tiers

> node scanners/posture.mjs examples/optimal-setup/

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Config-Audit Health Score
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 Health: A (93/100)    7 areas scanned

 Area Scores
 ───────────
 CLAUDE.md ............ A (100)   Settings ............ A (90)
 Hooks ................ A (100)   Rules ............... B (80)
 MCP .................. A (90)    Imports ............. A (100)
 Conflicts ............ A (90)

 3 opportunities available — run /config-audit feature-gap for recommendations

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Also Grade A — with only 3 opportunities remaining. This project has CLAUDE.md split via @imports, permissions scoped to specific tools, path-scoped rules (different rules for src/ vs. tests/), hooks covering multiple events, and MCP servers. Both setups are healthy — the difference is how much of Claude Code's surface area you're choosing to use.

---

Quick Start

Prerequisites

• Claude Code installed
• Node.js 18+ (for standalone CLI tools)

Installation

Add the marketplace and browse plugins with /plugin:

claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git

Or enable directly in ~/.claude/settings.json:

{
  "enabledPlugins": {
    "config-audit@ktg-plugin-marketplace": true
  }
}

First Scan

# Full audit with auto-scope detection (inside Claude Code)
/config-audit

# 30-second posture check (standalone, no LLM needed)
node scanners/posture.mjs /path/to/project

# Auto-fix issues with backup
node scanners/fix-cli.mjs /path/to/project --apply

The CLI tools work standalone — no Claude Code session needed, just Node.js 18+.

---

Feature Opportunities — Context-Aware Recommendations

Most configuration tools stop at "is it valid?" Config-audit goes further: what could improve your setup, and is it relevant to your project?

The feature opportunity scanner checks 25 dimensions and groups recommendations by impact:

Impact Level	Focus	Examples
High	Correctness & security	permissions.deny for sensitive files, basic hooks for safety automation
Worth Considering	Workflow efficiency	Path-scoped rules, modular @imports, custom agents
Explore	Nice-to-have	Keybindings, status line, output styles, agent teams

Each recommendation is context-aware — it considers what your project actually contains. A solo TypeScript project gets different suggestions than a team Python monorepo. Recommendations include why (backed by Anthropic's official guidance) and how (concrete steps).

Run /config-audit feature-gap to see what's relevant to your project.

---

Workflow Examples

1. First Time — Just Curious

You heard about this plugin and want to know where you stand:

/config-audit                          # Auto-detects scope, runs full audit
                                       # → See your grade, top issues, and gaps
/config-audit posture                  # Even faster: 30-second scorecard only

2. Monthly Configuration Checkup

A quick health check — are things still clean?

/config-audit posture                  # Quick health check (A-F grade, 7 areas)
/config-audit                          # Full audit if grade dropped
/config-audit fix                      # Auto-fix deterministic issues
/config-audit posture                  # Verify improvement

3. Deep Optimization

You want to go from C to A. The full pipeline:

/config-audit                          # Audit — understand what you have
/config-audit feature-gap              # Opportunities — context-aware recommendations
/config-audit plan                     # Plan — prioritized actions with risk assessment
/config-audit implement                # Execute — changes with backup + verification

4. Plugin Author

You maintain Claude Code plugins and want to ensure quality:

/config-audit plugin-health            # Audit plugin structure, frontmatter, cross-plugin conflicts
                                       # → Checks naming, frontmatter completeness, tool grants, duplicates

5. Track Configuration Drift

Your team configuration changes over time. Track it:

/config-audit drift                    # First run creates baseline, subsequent runs show delta
                                       # → New findings, resolved findings, unchanged, moved
/config-audit drift --save my-baseline # Save a named baseline for comparison

---

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 across 7 quality areas
/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 a previous backup
/config-audit plan	Generate prioritized action plan from audit findings
/config-audit implement	Execute plan with automatic backup + verification
/config-audit help	Show all commands with usage examples

Additional

Command	Description
/config-audit drift	Compare current config against a saved baseline
/config-audit plugin-health	Audit plugin structure, frontmatter, cross-plugin coherence
/config-audit discover	Run discovery phase only
/config-audit analyze	Run analysis phase only
/config-audit interview	Set preferences for action plan (optional)
/config-audit status	Show current session state and available actions
/config-audit cleanup	Remove old session directories

Scope

By default, /config-audit auto-detects scope from your git context. Override with: /config-audit current, /config-audit repo, /config-audit home, /config-audit full. Use --delta for incremental scanning (only new/changed findings).

---

Deterministic Scanners

8 Node.js scanners that perform structural analysis an LLM cannot reliably do: schema validation, circular reference detection, import resolution, conflict detection across scopes. Zero external dependencies.

Why deterministic? LLMs are powerful at understanding intent and context. But they cannot reliably validate JSON schemas, detect circular @import chains, or catch that your global settings.json contradicts your project-level one. These scanners fill that gap — fast, repeatable, and zero false positives on structural issues.

Scanner	Prefix	What It Catches
claude-md-linter.mjs	CML	Oversized files, missing sections, broken @imports, duplicates, stale TODOs
settings-validator.mjs	SET	Schema violations, unknown/deprecated keys, type mismatches, permission issues
hook-validator.mjs	HKV	Invalid format, missing scripts, wrong event names, timeout risks
rules-validator.mjs	RUL	Bad glob patterns, orphaned rules, deprecated fields, unscoped rules
mcp-config-validator.mjs	MCP	Invalid server types, missing trust levels, exposed env vars
import-resolver.mjs	IMP	Broken @imports, circular references, deep chains, tilde path issues
conflict-detector.mjs	CNF	Settings contradictions across scopes, permission conflicts, hook duplicates
feature-gap-scanner.mjs	GAP	25 feature checks — shown as opportunities, not grades

CLI Tools

All tools work standalone — no Claude Code session needed:

Tool	Usage
Posture	node scanners/posture.mjs <path> [--json] [--global] [--full-machine] [--output-file path]
Fix	node scanners/fix-cli.mjs <path> [--apply] [--json] [--global]
Drift	node scanners/drift-cli.mjs <path> [--save] [--baseline name] [--json]
Self-audit	node scanners/self-audit.mjs [--json] [--fix]
Full scan	node scanners/scan-orchestrator.mjs <path> [--global] [--full-machine] [--no-suppress]

---

Agent Architecture

Six specialized agents collaborate through the audit workflow, each matched to an appropriate model for cost and quality:

Agent	Model	Role	Tools
scanner-agent	Haiku	Fast filesystem scanning, file discovery	Read, Glob, Grep, Write
analyzer-agent	Sonnet	Deep analysis, hierarchy mapping, conflict detection	Read, Glob, Grep, Write
planner-agent	Opus	Action plan generation with risk assessment	Read, Glob, Write
implementer-agent	Sonnet	Change execution with mandatory backups	Read, Write, Edit, Bash, Glob
verifier-agent	Haiku	Post-implementation verification	Read, Glob, Grep
feature-gap-agent	Opus	Context-aware feature recommendations	Read, Glob, Grep, Write

Orchestration Flow

                                    +-----------+
                                    | Interview |  (optional)
                                    +-----+-----+
                                          |
+-----------+     +---------+     +-------v---+     +-----------+
| Discover  | --> | Analyze | --> |   Plan    | --> | Implement |
| (haiku)   |     | (sonnet)|     | (opus)    |     | (sonnet)  |
+-----------+     +---------+     +-----------+     +-----+-----+
                                                          |
                                                    +-----v-----+
                                                    |  Verify   |
                                                    |  (haiku)  |
                                                    +-----------+

---

Hooks & Safety

Four hooks provide automatic safety and session continuity — they activate the moment the plugin is installed:

Event	Script	What It Does
PreToolUse	auto-backup-config.mjs	Backs up any config file before Edit/Write touches it
PostToolUse	post-edit-verify.mjs	Re-scans after edits — blocks if new critical/high findings introduced
SessionStart	session-start.mjs	Checks for incomplete audit sessions so you can resume
Stop	stop-session-reminder.mjs	Shows current phase so your next session picks up where you left off

All hooks are Node.js (.mjs) for cross-platform compatibility (macOS, Linux, Windows).

Important

The PreToolUse and PostToolUse hooks only activate when config-audit is modifying configuration files. They don't interfere with your normal development workflow.

---

Skills

Skill	Trigger	Description
config-hierarchy	"CLAUDE.md hierarchy", "config file locations", "settings.json structure"	Comprehensive reference for Claude Code's configuration hierarchy — CLAUDE.md, settings.json, managed config, @imports, path-scoped rules

Skills activate automatically when your question matches their trigger patterns.

---

Suppressions

Finding ID Format

Every finding has a unique ID: CA-{SCANNER}-{NNN} — where {SCANNER} is the scanner prefix (see table above) and {NNN} is a sequential number. Examples: CA-CML-001, CA-SET-003, CA-HKV-002, CA-RUL-005.

Suppression

Some findings are expected — maybe you intentionally have a large CLAUDE.md, or a feature gap doesn't apply to your workflow. Create a .config-audit-ignore file to suppress them:

# Suppress by exact finding ID
CA-SET-003

# Suppress by scanner prefix (glob pattern)
CA-GAP-*

# Suppress all plugin health findings
CA-PLH-*

Suppressed findings are tracked in the scan envelope's suppressed_findings array for audit trail — nothing is silently hidden. Use --no-suppress to see everything.

---

Examples & Self-Audit

Example Projects

The examples/ directory contains two projects shown in the before/after demo above:

Example	Description	Grade	Opportunities
minimal-setup/	Single CLAUDE.md, nothing else	A	22
optimal-setup/	Full configuration across all 4 tiers	A	3

# Run them yourself
node scanners/posture.mjs examples/minimal-setup/
node scanners/posture.mjs examples/optimal-setup/

Self-Audit: Scanning the Scanner

The plugin runs all 8 scanners on itself via self-audit.mjs. Current result: Grade A, score 98, 0 real findings. Test fixtures and example files are automatically excluded from scoring — a security plugin that ships deliberately broken examples shouldn't fail its own audit.

node scanners/self-audit.mjs

---

Scanner Library (scanners/lib/)

Shared modules used by all scanners — useful if you're reading the source or extending the plugin:

Module	Purpose
severity.mjs	Severity constants, risk scoring, verdict logic
output.mjs	Finding objects (CA-XXX-NNN format), scanner results, envelope
file-discovery.mjs	Config file discovery: single-path, multi-path, full-machine
yaml-parser.mjs	Frontmatter parsing, JSON parsing, @import/section extraction
string-utils.mjs	Line counting, truncation, similarity, key extraction
scoring.mjs	Area scoring, health scorecard
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

Action Engines

Module	Purpose
fix-engine.mjs	planFixes(), applyFixes(), verifyFixes() — 9 fix types
rollback-engine.mjs	listBackups(), restoreBackup(), deleteBackup()
fix-cli.mjs	CLI entry point for auto-fix
drift-cli.mjs	CLI entry point for drift detection

---

Knowledge Base (knowledge/)

Reference documents that inform the feature-gap agent and context-aware recommendations:

File	Content
claude-code-capabilities.md	Feature register: 18 config surfaces, Anthropic guidance, relevance table
configuration-best-practices.md	Per-layer best practices
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

---

Testing

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

486 tests across 27 test files (10 lib + 16 scanner + 1 hook). Test fixtures in tests/fixtures/. Requires Node.js 18+ (node:test).

---

Gotchas

• Session accumulation — session directories at ~/.claude/config-audit/sessions/ grow over time. Use /config-audit cleanup to manage
• Node.js version — scanners require Node.js 18+ (uses node:test, node:fs/promises)
• Plugin CLAUDE.md in node_modules — these should be excluded via scope to avoid false positives

---

Data Storage & Safety Guarantees

Where Data Lives

All data stays local at ~/.claude/config-audit/sessions/:

~/.claude/config-audit/sessions/{session-id}/
  scope.yaml              # Scan boundaries
  discovery.json          # File manifest
  findings/               # Individual issues (YAML)
  analysis-report.md      # Full report
  action-plan.md          # Prioritized actions
  backups/                # Pre-modification copies
  implementation-log.md   # Change log
  state.yaml              # Phase tracking

Safety Guarantees

This plugin is cautious by design — configuration files are important, and a bad edit can break your entire Claude Code setup:

Guarantee	How
Backups mandatory	Every file is copied before modification — no exceptions
Read-only audit	/config-audit and /config-audit posture analyze without changing anything
Rollback support	/config-audit rollback restores from any backup
Syntax validation	Every change is validated before finalization
Verification pass	A separate agent confirms changes actually work
Human-in-the-loop	You approve the plan before anything is implemented
Post-edit guard	Hook blocks the session if a new critical/high finding is introduced

---

What This Plugin Does Not Cover

• Runtime behavior — this plugin audits configuration files, not what Claude actually does at runtime. For runtime defense, see claude-code-llm-security
• Secret scanning — config-audit checks for structural issues, not leaked credentials. Use llm-security for secret detection
• Custom scanner rules — scanners check against known Claude Code configuration schemas. Custom rule definitions are not supported
• Remote/team configuration — managed settings, SSO-provisioned config, and organization-level policies are detected as gaps but not managed

---

Version History

Version	Date	Highlights
3.0.1	2026-04-04	Cross-platform fix: Windows path separators. 486 tests
3.0.0	2026-04-04	Health redesign: quality-only grades, context-aware opportunities (replaces utilization/maturity/segment), Anthropic guidance. 482 tests
2.2.0	2026-04-04	Fixture filtering (test findings excluded from grades), session path fix, UX polish. 461 tests
2.1.0	2026-04-03	UX redesign: auto-scope, zero questions, simplified commands (15 from 17). 441+ tests
2.0.0	2026-04-03	Complete rewrite: 8 scanners, 25 gap dimensions, auto-fix, drift, suppressions, self-audit. 408+ tests
1.6.0	2026-04-03	Report generator, suppression engine, self-audit CLI, PostToolUse hook
1.5.0	2026-04-03	Diff engine, baseline manager, drift CLI, plugin health scanner
1.4.0	2026-04-03	Fix engine, rollback engine, fix CLI, PreToolUse hook
1.3.0	2026-04-03	Scoring module, posture CLI, feature-gap agent
1.2.0	2026-04-03	4 advanced scanners (MCP, import, conflict, feature-gap)
1.1.0	2026-04-03	4 core scanners, scan orchestrator, test infrastructure
1.0.0	2026-02-11	Cross-platform support
0.7.0	2026-02-07	Initial version (version reset from inflated 1.2.0)

See CHANGELOG.md for full details.

---

License

MIT License — Copyright (c) 2025-2026 Kjell Tore Guttormsen