123 lines
3.9 KiB
Markdown
123 lines
3.9 KiB
Markdown
---
|
|
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 |
|