cat:token-report
Generate detailed token usage report with threshold analysis and recommendations
From catnpx claudepluginhub cowwoc/cat --plugin catThis skill uses the workspace's default tool permissions.
Token Report
Purpose
Display a compact token usage report showing per-subagent breakdown with context utilization, health status, and duration. Essential for understanding session resource consumption at a glance.
When to Use
- Quick health check during any session
- Periodic monitoring during long-running orchestration
- After subagent completion to check overall consumption
- Before deciding whether to decompose remaining work
- Post-task retrospectives on efficiency
Step 1: Check for Pre-Computed Results (MANDATORY)
CRITICAL: This skill requires hook-based pre-computation. Check context for:
PRE-COMPUTED TOKEN REPORT:
If PRE-COMPUTED TOKEN REPORT is found:
Output the table EXACTLY as provided. Do NOT modify alignment or recalculate values.
Example pre-computed output:
╭───────────────────┬────────────────────────────────┬──────────┬──────────────────┬────────────╮
│ Type │ Description │ Tokens │ Context │ Duration │
├───────────────────┼────────────────────────────────┼──────────┼──────────────────┼────────────┤
│ Explore │ Explore codebase │ 68.4k │ 34% │ 1m 7s │
│ general-purpose │ Implement fix │ 90.0k │ 45% ⚠️ │ 43s │
│ general-purpose │ Refactor module │ 170.0k │ 85% 🚨 │ 3m 12s │
├───────────────────┼────────────────────────────────┼──────────┼──────────────────┼────────────┤
│ │ TOTAL │ 328.4k │ - │ 5m 2s │
╰───────────────────┴────────────────────────────────┴──────────┴──────────────────┴────────────╯
If PRE-COMPUTED TOKEN REPORT is NOT found:
FAIL immediately with this message:
ERROR: Pre-computed token report not found.
The hook precompute-token-report.sh should have provided the table data.
Do NOT attempt manual computation - the alignment requires deterministic
Python-based calculation.
Possible causes:
1. Session file not found
2. No subagent data in session
3. Hook execution failed
Try running /cat:token-report again or check session status.
Do NOT proceed to manual extraction or table building.
Table Format Reference
The pre-computed table uses these specifications:
Column widths (fixed):
| Column | Width | Content |
|---|---|---|
| Type | 17 | Subagent type (truncated with ...) |
| Description | 30 | Task description (truncated with ...) |
| Tokens | 8 | Formatted count (68.4k, 1.5M) |
| Context | 16 | Percentage with emoji indicator |
| Duration | 10 | Formatted time (1m 7s) |
Context indicators (INSIDE column):
| Context % | Display | Meaning |
|---|---|---|
| < 40% | "34%" | Healthy - plenty of headroom |
| >= 40% and < 80% | "45% ⚠️" | Warning - above soft target |
| >= 80% | "85% 🚨" | Critical - approaching limit |
Box characters:
- Top:
╭─┬─╮ - Divider:
├─┼─┤ - Bottom:
╰─┴─╯ - Sides:
│
Verification Checklist
Before outputting the table, verify:
- Pre-computed results found in context
- Table copied exactly (no modifications)
- All box characters preserved
- Emoji indicators inside Context column
- No additional computation performed
Anti-Patterns
Never attempt manual table construction
# BAD - Manual jq extraction and formatting
jq -s '...' "$SESSION_FILE"
# Then manually building table rows
# GOOD - Use pre-computed results only
# Output exactly what the hook provided
Never modify pre-computed alignment
# BAD - "Fixing" spacing or alignment
│ Type │ # Wrong - modified padding
# GOOD - Copy exactly as provided
│ Type │ # Correct - preserved padding
Related Skills
cat:monitor-subagents- Uses token data for health checkscat:decompose-task- Triggered when context reaches critical levelscat:learn-from-mistakes- Uses token data for context-related analysis