ktg-plugin-marketplace/plugins/config-audit/commands/tokens.md

name	description	argument-hint	allowed-tools	model
config-audit:tokens	Show ranked token hotspots and Opus 4.7 pattern findings — what's costing the most per turn and how to reduce it	[path] [--global]	Read, Bash	sonnet

Config-Audit: Token Hotspots

Show the configuration sources that contribute the most tokens per turn, ranked by estimated tokens, with Opus 4.7-specific recommendations for reducing prompt-cache misses, schema bloat, and deep import chains.

Complementary to /config-audit whats-active:

• whats-active = inventory view (what loads).
• tokens = action view (what to trim and why).

UX Rules (MANDATORY — from .claude/rules/ux-rules.md)

1. Never show raw JSON or stderr output. Always use --output-file + 2>/dev/null.
2. Narrate before acting. Tell the user what you're about to do.
3. Read, don't dump. Read the JSON file and render formatted tables.
4. End with context-sensitive next steps.

Implementation

Step 1: Parse $ARGUMENTS

Split $ARGUMENTS into a path and flags. Path is the first non-flag argument. Default to . (current working directory). Recognized flags:

• --global — also include the user-level ~/.claude/ cascade
• --json — emit raw JSON instead of rendered tables (power-user mode)

Step 2: Run the CLI silently

Tell the user: "Analysing token hotspots for <path>..."

TMPFILE="/tmp/config-audit-tokens-$$.json"
node ${CLAUDE_PLUGIN_ROOT}/scanners/token-hotspots-cli.mjs <path> --output-file "$TMPFILE" [--global] 2>/dev/null; echo $?

Exit code handling:

• 0 → continue
• 3 → tell user: "Couldn't analyse tokens. Check that the path exists and is a directory." Stop.

Step 3: If --json was requested, cat the file and stop

cat "$TMPFILE"

Do NOT render tables in JSON mode.

Step 4: Read JSON and render

Use the Read tool on $TMPFILE. Extract:

• total_estimated_tokens — top-line number
• hotspots[] — top 10 ranked sources
• findings[] — Opus 4.7 pattern findings (CA-TOK-001..004)
• counts — severity breakdown

Render as markdown:

**Token hotspots for `<path>`** — ~{total_estimated_tokens} estimated tokens loaded per turn

### Top hotspots (ranked by estimated tokens)

| Rank | Source | Tokens | Recommendations |
|------|--------|--------|-----------------|
| {rank} | `{source}` | ~{estimated_tokens} | {recommendations joined as `· ` bullets} |

### Opus 4.7 pattern findings

{For each finding, render:}

- **{id}** ({severity}) — {title}
  - {description}
  - **Fix:** {recommendation}

### Severity summary

| Severity | Count |
|----------|-------|
| critical | {counts.critical} |
| high | {counts.high} |
| medium | {counts.medium} |
| low | {counts.low} |
| info | {counts.info} |

_Estimates assume ~4 chars/token (Claude ballpark). Real token count varies ±20%._

Step 5: Cleanup and next steps

rm -f "$TMPFILE"

### What's next

- **`/config-audit whats-active`** — full inventory of what loads (plugins, skills, MCP, hooks)
- **`/config-audit posture`** — overall health scorecard (Token Efficiency is the 8th area)
- **`/config-audit fix`** — auto-fix deterministic issues (where applicable)
- See `knowledge/opus-4.7-patterns.md` for the full pattern catalogue (CA-TOK-001 … 004)

Scope and limits

• Read-only. Inspects config files; never writes.
• Single repo. Scans one path per invocation.
• Structural only. Hotspots are deterministic byte→token estimates from disk; runtime cache hit-rate is out of scope.
• Heuristic estimates. ~4 chars/token for markdown, ~3.5 for JSON. Real counts vary ±20%.

Error handling

Condition	Action
Exit code 3	Tell user path is invalid, suggest checking path exists
JSON parse fails	Tell user to re-run, mention as a bug to report
Empty hotspots	Suggest adding a CLAUDE.md or running /config-audit feature-gap first