cost - SKILL.md Agent Skill

name: cost license: MIT description: >- Deep cost exploration and transparency. Shows real token usage, session costs, campaign spend, burn rates, and model breakdown. Reads Claude Code's native session data for exact numbers. Complements /dashboard with focused cost views. user-invocable: true auto-trigger: false trigger_keywords: - cost - costs - cost breakdown - campaign cost - token usage - burn rate - model breakdown last-updated: 2026-03-30

/cost -- Session & Campaign Cost Explorer

When to Use

/cost -- current session cost and burn rate
/cost today -- today's total spend
/cost week -- this week's spend
/cost campaign {slug} -- total spend for a specific campaign
/cost all -- lifetime cost summary
When /do routes "how much", "what's the cost", "spending", "tokens", "burn rate"

Inputs

Optional arguments parsed from user message:

today -- filter to today's sessions
week -- filter to last 7 days
campaign {slug} -- filter to a specific campaign
all -- show all-time data
No argument -- show current session

Protocol

Step 1: READ REAL DATA

Run the session-tokens.js script to get real token data:

node scripts/session-tokens.js              # current/latest session
node scripts/session-tokens.js --today      # today's sessions
node scripts/session-tokens.js --all        # all sessions (use for week/all/campaign)

Step 2: RENDER BASED ON SCOPE

Current session (/cost with no args):

=== Session Cost Report ===
Session: {sessionId (first 8 chars)}
Started: {relative time} ({absolute time})
Duration: {minutes} min

Tokens:
  Input:          {N} tokens
  Output:         {N} tokens
  Cache creation: {N} tokens
  Cache read:     {N} tokens
  Total:          {N} tokens

Cost: ${total}
Burn rate: ${rate}/min
Messages: {N} ({N} main + {N} across {N} subagents)

Model breakdown:
  claude-opus-4-6:         {N} messages (${cost}, {pct}% of spend)
  claude-haiku-4-5:        {N} messages (${cost}, {pct}% of spend)

Cache efficiency: {pct}% of input tokens served from cache
  (Higher = more cost-efficient. Cache reads cost 10x less than fresh input.)

Pricing source: scripts/pricing.json (version {version})

Today / Week / All (/cost today, /cost week, /cost all):

=== Cost Report: {Today / This Week / All Time} ===

Summary:
  Sessions: {N}
  Total cost: ${total}
  Subagents spawned: {N}
  Total messages: {N}

Top 5 sessions by cost:
  ${cost}  {duration}min  {agents} agents  {msgs} msgs  {date}
  ${cost}  {duration}min  {agents} agents  {msgs} msgs  {date}
  ...

By campaign (from session-costs.jsonl):
  {slug}: ${cost} across {N} sessions
  _unattached: ${cost} across {N} sessions

Average session: ${avg_cost} | ${avg_rate}/min | {avg_duration} min

For historical charts and billing-window views: npx ccusage

Campaign (/cost campaign {slug}):

=== Campaign Cost: {slug} ===

Total: ${cost} across {N} sessions ({N} agents, {N} min)
Average session: ${avg}

Sessions:
  {date}: ${cost} ({duration} min, {agents} agents, {msgs} msgs)
  {date}: ${cost} ({duration} min, {agents} agents, {msgs} msgs)
  ...

Step 3: ADD CONTEXT

After the cost data, add one of these contextual lines based on the numbers:

If burn rate > $2/min: "Burn rate is high. Consider whether subagent-heavy work could be restructured into smaller focused sessions."
If cache hit rate < 50%: "Low cache hit rate. Long conversations with many tool results tend to have lower cache efficiency."
If no real data available: "Cost data is estimated. Real token data becomes available when sessions complete and Claude Code writes session JSONL files."
Otherwise: no extra context needed.

Step 4: FRINGE CASES

If scripts/session-tokens.js does not exist: Fall back to session-costs.jsonl data. Show estimated costs with "(est)" marker.

If no session data exists:

No session data found. Cost tracking requires Claude Code session files
at ~/.claude/projects/. These are created automatically by Claude Code.

If pricing.json is missing or unreadable: Use hardcoded pricing in session-tokens.js. Note: "Using built-in pricing (pricing.json not found)."

If user asks about Pro/Max subscription costs:

Note: Pro/Max subscribers pay a flat monthly fee, not per-token.
The token counts shown here represent your usage volume, not billing.
For rate limit awareness, token throughput matters more than dollar cost.

Fringe Cases

Telemetry directory missing: .planning/telemetry/ does not exist — output: "No telemetry data found. Run any skill first to generate session data, then re-run /cost."
Malformed telemetry JSON: a session-*.json file fails to parse — output: "Telemetry file is corrupted. Delete .planning/telemetry/session-*.json and re-run the skill that generated it." Skip the bad file and continue with the rest.
MCP cost API returns no data: Claude Code is not tracking this session — output: "Session cost unavailable from MCP. Check that Claude Code is running with cost tracking enabled. Showing telemetry file data only." Fall back to session-costs.jsonl.
All session files are from a different project: project paths in the files do not match the current working directory — warn: "Session files found belong to a different project. You may be in the wrong directory." List the project paths found in the session files.

Contextual Gates

Disclosure: "Reading telemetry and session data. No files modified." Reversibility: green — read-only; no files modified Trust gates:

Any: full cost report, session data, campaign attribution.

Quality Gates

Always show real data when available, estimated when not
Always label data source: (real) vs (est)
Never claim specific dollar savings from Citadel -- show raw hook facts instead
Suggest ccusage for features we don't replicate (charts, billing windows)
Round costs to 2 decimal places, tokens to nearest K/M
Total output must fit on one screen for current-session view

Exit Protocol

/cost does not produce a HANDOFF block. It is a read-only cost exploration tool. After displaying the report, wait for the next user command.