Kjell Tore Guttormsen
0874188fe4
Commands are namespaced (/name:command), so a command name shared by two differently-named plugins keeps both reachable — it is ambiguity, not a hard conflict. The check now mirrors COL's plugin-vs-plugin skill finding: severity LOW (was HIGH), 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 (was folder basename) and fires only across 2+ distinct namespaces — when plugins share a declared name, the namespace-collision finding (medium) is the right signal, so this stays silent. Removes the inaccurate "only one wins" humanizer entry. Adds fixtures (duplicate-command-name; a shared command in duplicate-plugin-name's colliding namespace) and 4 tests. Suite 932->936. self-audit A 97 / A 100, scanners 13.
188 lines
10 KiB
Markdown
188 lines
10 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|