---
name: config-audit:tokens
description: Show ranked token hotspots and Opus 4.7 pattern findings — what's costing the most per turn and how to reduce it
argument-hint: "[path] [--global]"
allowed-tools: Read, Bash
model: 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>`..."**

```bash
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

```bash
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:

```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

```bash
rm -f "$TMPFILE"
```

```markdown
### 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 |