# Config-Audit Plugin for Claude Code

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

> **Solo-maintained, fork-and-own.** This plugin is a starting point, not a vendor product. Issues are welcome as signals; pull requests are not accepted. See [GOVERNANCE.md](GOVERNANCE.md) for the full model and what upstream provides.

*AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)*

![Version](https://img.shields.io/badge/version-5.1.0-blue)
![Platform](https://img.shields.io/badge/platform-Claude_Code_Plugin-purple)
![Scanners](https://img.shields.io/badge/scanners-12-cyan)
![Commands](https://img.shields.io/badge/commands-18-green)
![Agents](https://img.shields.io/badge/agents-6-orange)
![Hooks](https://img.shields.io/badge/hooks-4-red)
![Tests](https://img.shields.io/badge/tests-792+-brightgreen)
![License](https://img.shields.io/badge/license-MIT-lightgrey)

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. 12 deterministic scanners across 10 quality areas, context-aware feature recommendations, auto-fix with backup/rollback, an Opus-4.7-aware Token Hotspots scanner with optional API-calibrated `--accurate-tokens` mode, plus cache-prefix stability, dead-tool, and cross-plugin collision detection. Zero external dependencies.

---

## Table of Contents

- [What's New in v5.1.0](#whats-new-in-v510)
- [What Is This?](#what-is-this)
- [The Configuration Problem](#the-configuration-problem)
- [Quick Start](#quick-start)
- [Feature Opportunities](#feature-opportunities--context-aware-recommendations)
- [Workflow Examples](#workflow-examples)
- [Commands](#commands)
- [Deterministic Scanners](#deterministic-scanners)
- [Agent Architecture](#agent-architecture)
- [Hooks & Safety](#hooks--safety)
- [Skills](#skills)
- [Suppressions](#suppressions)
- [Examples & Self-Audit](#examples--self-audit)
- [Scanner Library](#scanner-library-scannerslib)
- [Knowledge Base](#knowledge-base-knowledge)
- [Testing](#testing)
- [Gotchas](#gotchas)
- [Data Storage & Safety Guarantees](#data-storage--safety-guarantees)
- [What This Plugin Does Not Cover](#what-this-plugin-does-not-cover)
- [Version History](#version-history)
- [License](#license)

---

## What's New in v5.1.0

**Plain-language UX humanizer** — every command's default output now leads with prose. Findings are grouped by what they mean for the user (Configuration mistake, Conflict, Wasted tokens, Missed opportunity, Dead config) and led with an urgency phrase (Fix this now, Fix soon, Fix when convenient, Optional cleanup, FYI). Technical IDs (`CA-CML-001`, `CA-TOK-005`, …) still appear, but at end-of-line where they belong as references rather than headlines.

### Before / after

```
v5.0.0 default
  - [low] CA-CNF-001: Hook duplicate event registration

v5.1.0 default
  - [low] The same automation is set up more than once

v5.1.0 with --json (machine-readable, byte-stable)
  { "id": "CA-CNF-001", "title": "...", "userImpactCategory": "Conflict",
    "userActionLanguage": "Optional cleanup", "relevanceContext": "affects-everyone" }
```

### Plain-language vocabulary

The toolchain uses these terms when describing findings:

| User-facing label | What it means |
|-------------------|---------------|
| Fix this now | Something is broken or risky and should be addressed immediately |
| Fix soon | High-priority issue worth scheduling this week |
| Fix when convenient | Real issue but not urgent |
| Optional cleanup | Tidy-up that improves polish but isn't required |
| FYI | Informational; no action expected |
| Configuration mistake | A configuration file has an error or omission |
| Conflict | Two configuration sources disagree |
| Wasted tokens | Configuration is loading content that costs tokens without payback |
| Missed opportunity | A Claude Code feature you aren't using that could help your project |
| Dead config | Configuration that has no effect (e.g., a permission that's also denied) |

### Backwards compatibility — the `--raw` flag

Every CLI accepts `--raw` for byte-stable v5.0.0 verbatim output (technical IDs, raw severity, no prose translation). `--json` is unchanged from v5.0.0 — already byte-stable for programmatic consumption. Use `--raw` only if you've built tooling against v5.0.0 stderr scrapes; for new automation, prefer `--json`.

```bash
node scanners/posture.mjs .                # v5.1.0 plain-language default
node scanners/posture.mjs . --raw          # v5.0.0 verbatim (byte-stable)
node scanners/posture.mjs . --json         # unchanged JSON envelope
```

### What's not changed

- All scanner internals (12 scanners + standalone PLH) emit the same finding IDs and structural data — humanization happens at output-formatting time only
- `--json` envelope shape is byte-stable with v5.0.0 (humanizer fields are additive on findings only in default mode; the `--json` path bypasses humanization entirely)
- 635 tests grew to 792 (+157 covering humanizer module, scenario read-tests, forbidden-words lint, JSON / `--raw` backwards-compat, default-output snapshots, and command-template / agent-prompt shape)

---

## 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** — 12 deterministic scanners verify correctness across every configuration file, catching broken imports, deprecated settings, conflicting rules, format errors, permission contradictions, Opus-4.7-era token waste, cache-prefix instability, dead tool grants, and cross-plugin skill collisions
- **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](https://docs.anthropic.com/en/docs/claude-code) installed
- Node.js 18+ (for standalone CLI tools)

### Installation

Add the marketplace and browse plugins with `/plugin`:

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

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

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

### First Scan

```bash
# 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 10 quality areas (incl. Token Efficiency, Plugin Hygiene) |
| `/config-audit tokens` | Opus-4.7-aware token hotspots — ranked by estimated waste; 6 patterns + optional `--accurate-tokens` API calibration |
| `/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 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 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` | 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

12 Node.js scanners that perform structural analysis an LLM cannot reliably do: schema validation, circular reference detection, import resolution, conflict detection across scopes, Opus-4.7-aware token-cost analysis, cache-prefix stability, dead-tool detection, and cross-plugin skill collisions. Plus a standalone plugin-health scanner. 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 |
| `token-hotspots.mjs` | TOK | Cache-breaking volatile content, redundant tool permissions, deep import chains, oversized cascades, bloated skill descriptions, MCP tool-schema budget |
| `cache-prefix-scanner.mjs` | CPS | Volatile content in lines 31–150 of the CLAUDE.md cascade — beyond the cache-prefix window but still re-loaded every turn |
| `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; user-vs-plugin overlaps |

### 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]` |
| **Tokens** | `node scanners/token-hotspots-cli.mjs <path> [--json] [--global] [--output-file path] [--accurate-tokens] [--with-telemetry-recipe]` |
| **Manifest** | `node scanners/manifest.mjs <path> [--json]` — ranked system-prompt source table |
| **What's active** | `node scanners/whats-active.mjs <path> [--json] [--verbose] [--suggest-disables]` |
| **Self-audit** | `node scanners/self-audit.mjs [--json] [--fix] [--check-readme]` |
| **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** | Sonnet | 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** | Sonnet | 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 |
| (sonnet)  |     | (sonnet)|     | (opus)    |     | (sonnet)  |
+-----------+     +---------+     +-----------+     +-----+-----+
                                                          |
                                                    +-----v-----+
                                                    |  Verify   |
                                                    |  (sonnet) |
                                                    +-----------+
```

---

## 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](#the-configuration-problem) above:

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

```bash
# 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 12 scanners + the standalone plugin-health scanner on itself via `self-audit.mjs`. Test fixtures and example files are automatically excluded from scoring — a configuration plugin that ships deliberately broken examples shouldn't fail its own audit. Use `--check-readme` to verify badge counts are in sync with the filesystem.

```bash
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, `WEIGHTS` export (v5 F3) |
| `output.mjs` | Finding objects (`CA-XXX-NNN` format), scanner results, envelope, `details` field |
| `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 (v5 severity-weighted), health scorecard, `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 of plugins/skills/MCP/hooks/CLAUDE.md cascade with token estimates |
| `tokenizer-api.mjs` | Anthropic `count_tokens` wrapper for `--accurate-tokens` (v5 N5); 5s timeout, 429 backoff, key masking |

### 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 |
| `manifest.mjs` | CLI: ranked system-prompt source table (v5 N2) |
| `whats-active.mjs` | CLI: read-only active-config inventory (v3.1.0+) |
| `token-hotspots-cli.mjs` | CLI: token hotspots ranking with optional `--accurate-tokens` |

---

## 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 (Opus 4.7 cache-stability guidance) |
| `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` | `jq` recipe for verifying prompt-cache hit rate from session transcripts |

---

## Testing

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

635 tests across 36 test files (12 lib + 23 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](https://git.fromaitochitta.com/open/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 |
|---------|------|-----------|
| **5.1.0** | 2026-05-01 | Plain-language UX humanizer. Default output of all 18 commands now leads with prose; findings grouped by user-impact category (Configuration mistake, Conflict, Wasted tokens, Missed opportunity, Dead config) and led by urgency phrase (Fix this now → FYI). New `--raw` flag preserves v5.0.0 verbatim output for tooling that scrapes stderr; `--json` is unchanged and byte-stable. New scanner-lib modules: `humanizer.mjs`, `humanizer-data.mjs` with TRANSLATIONS for 13 scanner prefixes. Self-audit terminal output also humanized. 792 tests (+157 humanizer-tester) |
| **5.0.0** | 2026-05-01 | Reality-based token-optimization. 3 new scanners (CPS cache-prefix, DIS dead tools, COL plugin collisions) → 12 deterministic scanners. New `/config-audit manifest` and `--accurate-tokens` API calibration. Severity-weighted scoring (`scoringVersion: 'v5'`). MCP token estimates 15 → 500+. Plugin Hygiene as 10th quality area. Knowledge: cache-stability replaces 200-line rule, cache-telemetry recipe. **Breaking:** F2 token magnitude jump, F3 severity weighting, F5 Pattern D removed, N1 `CA-TOK-*` glob now matches CA-TOK-005. 635 tests |
| **4.0.0** | 2026-04-19 | Opus 4.7 era: new TOK scanner (cache-breaking volatile content, redundant tool permissions, deep import chains, sonnet-era setups), `/config-audit tokens` command, Token Efficiency 8th quality area, scanner-agent + verifier-agent migrated haiku → sonnet. 543 tests |
| **3.1.0** | 2026-04-14 | New `/config-audit whats-active` — read-only inventory of active plugins, skills, MCP, hooks, CLAUDE.md for a repo, with token estimates. 522 tests |
| **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](CHANGELOG.md) for full details.

---

## License

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