| name | usage-view |
| description | Know exactly what you spent (Claude Code) or how much of your Codex limit you have used (Codex). Interactive HTML dashboard with token usage and, on Claude Code, cost breakdown and 5-hour window timeline across all sessions |
| when_to_use | Use when user wants to see token usage, cost breakdown, or usage/rate-limit timeline. Triggers on "usage view", "usage dashboard", "show usage", "usage report". |
| host | dual |
Dual-host: Claude Code and Codex both write the facts this dashboard needs, but not the same facts. Claude Code gives cost and a hardcoded 5-hour window; Codex gives rate_limits.primary/secondary — a used-percent and a reset instant with a dynamic, host-reported window (observed as 10080 minutes / 7 days, never assumed to be 5 hours) — and no per-token pricing at all. Detect the host you are running under and act accordingly:
- Claude Code: run the full pipeline below unmodified (cost, 5-hour window, AI insights, 23-locale HTML).
- Codex: run
node ${PLUGIN_ROOT}/scripts/run-usage-view.js --gen-agent-prompt --host codex [parsed flags]. It uses the same default AI-analysis pipeline and the same explicit ai / no ai options as Claude Code. This renders the same dashboard (skills/usage-view/template.html via build-report.js) — token breakdown, calendar, session detail — not a separate report. Cost figures read N/A, not $0 or a Claude-derived estimate, and the calendar follows Codex's reported rate-limit lane instead of assuming a fixed 5 hours.
- A dual-host skill must not hardcode one host's plugin root. Claude Code exports
CLAUDE_PLUGIN_ROOT; Codex does not reliably export CODEX_PLUGIN_ROOT. Resolve PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT}}", falling back to this skill's own directory if both are unset.
Parse user arguments, then launch a single background Agent that runs the entire pipeline (analyze → AI insights unless no ai was selected → build → open browser). The user can continue working while the dashboard is being generated.
Help
ONLY show help if the user's argument literally contains the word "help" (e.g. /usage-view help). If no argument or any other argument is given, SKIP this section entirely and proceed to launching the agent.
If the user provides "help" as argument, show usage summary and stop:
/usage-view — Interactive HTML usage dashboard
Options:
(nothing) All projects, last ~1 month
current Current 5-hour window only (fast, no AI analysis by default)
last N days Analyze last N days only
locale XX Force language (e.g. locale ja). Default: system language → en fallback
no ai Skip AI analysis for faster rendering (no LLM cost)
ai Force AI analysis (use with "current" to override its default)
private Strip user prompt text from report (safe to share)
help Show this help
Supported locales:
en ko ja zh es fr de pt it ru ar hi bn id ms th vi tr pl nl he sv no
Examples:
/usage-view
/usage-view current (fast, no AI)
/usage-view current ai (current + AI analysis)
/usage-view last 7 days
/usage-view locale ja
/usage-view current locale fr
/usage-view private (safe to share — no prompt text)
Do not run any analysis. Just display the help text and stop.
Args (user-facing)
Users may provide these in natural language. Parse and map to script flags.
⚠️ Default is NO FLAGS. Only add flags when the user explicitly provides arguments. Do NOT infer or assume arguments.
| User input | Script flag | Example |
|---|
| (nothing) | (no flags) | all projects, last ~1 month |
| a number of days | --days N | "last 7 days" → --days 7 |
| "all time" | --days all | no time limit, load all available data (see note below) |
| "current" | --days 1 --current | current 5H window only (implies --no-ai for speed) |
| "locale XX" | --locale XX | "locale ja" → --locale ja |
| plan name | --plan XX | "max200" → --plan max200 |
| "project X" | --project X | specific project only (X = hashed CWD, e.g. -Users-foo-myproject. Derive via echo "$PWD" | sed 's/[^a-zA-Z0-9]/-/g') |
| "all" | --all | aggregate all projects |
| "no ai" | --no-ai | skip AI analysis (fast) |
| "ai" | --ai | force AI analysis (override current's default) |
| "private" | --private | strip user prompt text from report |
Note on --days all: Claude Code deletes transcripts older than ~1 month. Data beyond that range comes from previously cached timeline CSVs and session summaries at ~/.claude/super-token-saver-data/. Original transcripts cannot be recovered — only already-analyzed sessions are available. Tell the user: "Transcripts older than ~1 month are deleted by Claude Code. This loads previously cached analysis data — sessions that were never analyzed won't appear."
Note on current: Defaults to no AI analysis because the main purpose is a quick snapshot. If the user explicitly says "current ai" or "current with analysis", add --ai to re-enable it.
Plan parameter
On Claude Code, if the user does NOT provide a plan, ask before launching:
What's your current Claude plan?
| # | Plan | Price |
|---|
| 1 | Pro | $20/mo |
| 2 | Max 5x | $100/mo |
| 3 | Max 20x | $200/mo |
| 4 | Team Standard | $20/seat/mo |
| 5 | Team Premium | $100/seat/mo |
| 6 | Enterprise | custom |
| 7 | Amazon Bedrock | usage-based |
| 8 | Microsoft Foundry | usage-based |
| 9 | Google Vertex AI | usage-based |
Enter number or name (e.g. "3" or "max200"):
Map user input to --plan values: 1=pro, 2=max100, 3=max200, 4=team, 5=team_premium, 6=enterprise, 7=bedrock, 8=foundry, 9=vertex
If the user doesn't know or skips, run without --plan.
On Codex, the plan is normally read straight off rate_limits.plan_type in the transcript — do not ask unless that field was absent. If asked, offer the order Codex itself uses (codex-rs/protocol/src/account.rs):
| # | Plan |
|---|
| 1 | Free |
| 2 | Go |
| 3 | Plus |
| 4 | Pro |
| 5 | Pro Lite |
| 6 | Team |
| 7 | Business (usage-based, self-serve) |
| 8 | Business |
| 9 | Enterprise (usage-based) |
| 10 | Enterprise |
| 11 | Edu |
Enter number or name (e.g. "2" or "go"):
Map to --plan values by the same order (1=free … 11=edu). A plan_type this list doesn't recognize is still shown as-is, never collapsed to the literal word "unknown".
Launch: Background Agent
Launch a single background Agent (run_in_background: true). Tell the user: "Usage dashboard is being generated in the background. You can continue working — the browser will open automatically when ready."
On Claude Code, the agent prompt should be exactly this (replace [parsed flags] with the actual flags parsed from user args):
"Resolve PLUGIN_ROOT as \"${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT}}\", falling back to this skill's own directory if both are empty — never assume CLAUDE_PLUGIN_ROOT is set. Run node "$PLUGIN_ROOT"/scripts/run-usage-view.js --gen-agent-prompt [parsed flags] 2>/dev/null, parse the JSON output to get agentPromptFile, then Read that file and follow the instructions exactly. Output ONLY the final summary at the very end: scope, file path, sessions analyzed, date range, total cost."
On Codex, use the same AI-analysis pipeline and user options as Claude Code. The agent prompt should be exactly this:
"Resolve PLUGIN_ROOT from CODEX_PLUGIN_ROOT, falling back to this skill's own directory if empty. Run node "$PLUGIN_ROOT"/scripts/run-usage-view.js --gen-agent-prompt --host codex [parsed flags] 2>/dev/null, parse the JSON output to get agentPromptFile, then Read that file and follow the instructions exactly. Output ONLY the final summary at the very end: scope, file path, sessions analyzed, date range, total cost."
Main Session: Final Output
After launching the background agent, immediately tell the user (do NOT wait for the agent to finish):
Usage dashboard is being generated in the background. Browser will open automatically when ready.
You can continue working.
When the background agent completes, report the host-appropriate cost and window labels:
Usage dashboard opened in browser.
- Scope: {all projects OR current folder name}
- File: {path}
- Sessions analyzed: {N}
- Date range: {from} ~ {to}
- Total cost: ${total OR "N/A — Codex subscription usage is not per-token billing"}
The HTML file is self-contained -- you can share it or re-open it anytime.
💡 Tip: `/usage-view no ai` — skip AI analysis for a faster dashboard (no LLM cost).
💡 Tip: `/usage-view current` — quick snapshot (Claude: 5H window; Codex: latest host-reported windows).
Important Notes
- Large files: The analyze-usage.js script uses streaming (
readline) internally. Do not read JSONL files with fs.readFileSync.
- Caching: The script caches per-session JSON at
~/.claude/super-token-saver-data/{projectName}/{sessionId}/summary.json and timeline CSV at ~/.claude/super-token-saver-data/{projectName}/{sessionId}/timeline.csv. Use --force to force re-analysis.
- Build script:
scripts/build-report.js reads timeline CSVs and constructs the REPORT_DATA object. The template at skills/usage-view/template.html contains the viewer (HTML/CSS/JS) with sample data that gets replaced.
- Timezone: All displayed dates/times use the user's local timezone via
new Date().
- Cost formula: Per-model pricing from
scripts/model-pricing.json. Falls back to default model if unknown.
- Self-contained HTML: The output file works standalone -- inline CSS/JS, CDN for Chart.js, no external dependencies.
- stderr: The analyze script writes progress to stderr. Always use
2>/dev/null when redirecting stdout to a file, never 2>&1. Exception: Tool Call 1 in the background agent captures stderr to a logfile so ERROR:UNKNOWN_MODEL (exit code 2) can be inspected on failure.
- Runner script:
scripts/run-usage-view.js consolidates all deterministic steps. The agent should NEVER run analyze-usage.js or build-report.js directly.
- Unknown model handling: When
scripts/analyze-usage.js encounters a model missing from scripts/model-pricing.json, it fails fast with exit code 2 and emits ERROR:UNKNOWN_MODEL on stderr. The background agent handles this inline — WebFetch the Anthropic pricing page, Edit the JSON with exact values (no guessing), and re-run Tool Call 1. If the page lacks required fields, the agent guides the user to update the plugin instead of patching with derived values. Full procedure lives in agent-prompt-template.txt Tool Call 1. This entire step is Claude Code-only — Codex has no pricing table to be missing from, so --host codex never hits ERROR:UNKNOWN_MODEL; its cost column is unconditionally N/A.
- Codex path:
--host codex reuses scripts/lib/codex-transcript.js for discovery/normalization and renders through the same build-report.js → skills/usage-view/template.html and AI-analysis pipeline Claude Code uses. Codex sessions use the same cache tree and CSV shape. Host-specific prompt substitutions cover tokens, actual model IDs, subscription allowance, cache-creation billing notes, and observed rate-limit lanes. no ai is optional and is never forced merely because the host is Codex.
