token-breakdown

Token Breakdown

Query Splunk for detailed token usage analytics of the current Claude Code session.

Prerequisites

The Splunk MCP server must be configured in Claude Code. This is managed by nix-darwin:

• splunk MCP server defined in programs.claude.mcpServers
• Credentials injected via Doppler (SPLUNK_MCP_ENDPOINT, SPLUNK_MCP_TOKEN)
• Self-signed TLS handled by NODE_TLS_REJECT_UNAUTHORIZED=0 in the MCP server env

Verify: mcp__splunk__splunk_get_info should return the Splunk version.

Invocation

/token-breakdown [session-id]

• No arguments: analyzes the current active session
• With session-id: analyzes a specific session UUID

Workflow

Phase 1: Session Identification

Determine the current session ID and validate it has a useful name.

Step 1a — Find session ID:

If no session-id argument was provided, find the current session:

# Compute encoded project path (slashes become hyphens)
encoded_path=$(echo "$PWD" | sed 's|^/|-|; s|/|-|g')

# Find the most recently modified JSONL session file
session_file=$(ls -t "$HOME/.claude/projects/${encoded_path}/"*.jsonl 2>/dev/null | head -1)

# Validate a session file was found
if [ -z "$session_file" ]; then
  echo "No active session found for current project directory: $PWD"
  exit 1
fi

# Extract session ID from filename
session_id=$(basename "$session_file" .jsonl)

Step 1b — Read session metadata:

Read line 1 of the session file to extract the slug and version:

head -1 "$session_file"

Extract slug, version, and sessionId from the JSON.

Step 1c — Check session name quality:

If the slug matches the auto-generated pattern (three hyphenated words like glistening-gliding-cook):

• Tell the user: "This session has an auto-generated name: {slug}."
• Suggest: "For better Splunk searchability, run /rename to give it a descriptive name."
• Do NOT block — continue with the analysis regardless
• Note the suggestion in the output header

Phase 2: Execute Splunk Queries

Run all four queries in parallel using the Splunk MCP server tools.

MCP tool call pattern:

Each query uses mcp__splunk__splunk_run_query with the SPL query text and time range:

mcp__splunk__splunk_run_query({
  "search_query": "<SPL query>",
  "earliest_time": "-7d",
  "latest_time": "now"
})

The MCP server handles authentication, TLS, and connection management. Results are returned as structured JSON — no manual parsing of newline-delimited export format needed.

Query 2a: Session Overview by Model

search index=claude sourcetype="claude:code:session" sessionId="{session_id}" type="assistant"
| spath path=message.usage.input_tokens output=input_tokens
| spath path=message.usage.output_tokens output=output_tokens
| spath path=message.usage.cache_read_input_tokens output=cache_read
| spath path=message.usage.cache_creation_input_tokens output=cache_creation
| spath path=message.model output=model
| stats
    sum(input_tokens) as input,
    sum(output_tokens) as output,
    sum(cache_read) as cache_read,
    sum(cache_creation) as cache_write,
    count as api_calls
    by model
| eval total=input+output+cache_read+cache_write
| eval cache_pct=if((cache_read+input)>0, round(cache_read/(cache_read+input)*100, 1), 0.0)
| sort -total
| addcoltotals labelfield=model label="TOTAL"

Query 2b: Token Usage by Tool

search index=claude sourcetype="claude:code:session" sessionId="{session_id}" type="assistant"
| spath path=message.content{} output=content_items
| spath path=message.usage.output_tokens output=output_tokens
| eval tool_count=mvcount(mvfilter(match(content_items, "\"type\":\s*\"tool_use\"")))
| eval output_per_call=if(tool_count>0, output_tokens/tool_count, 0)
| mvexpand content_items
| spath input=content_items path=type output=content_type
| spath input=content_items path=name output=tool_name
| where content_type="tool_use"
| stats count as calls, sum(output_per_call) as output_tokens by tool_name
| sort -calls

Query 2c: Subagent Token Usage

search index=claude sourcetype="claude:code:subagent" sessionId="{session_id}" type="assistant"
| spath path=message.usage.input_tokens output=input_tokens
| spath path=message.usage.output_tokens output=output_tokens
| spath path=message.model output=model
| spath path=slug output=agent_slug
| stats
    sum(input_tokens) as input,
    sum(output_tokens) as output,
    count as api_calls
    by model, agent_slug
| eval total=input+output
| sort -total

Query 2d: Token Burn Rate (Timeline)

search index=claude sourcetype="claude:code:session" sessionId="{session_id}" type="assistant"
| spath path=message.usage.input_tokens output=input_tokens
| spath path=message.usage.output_tokens output=output_tokens
| spath path=message.model output=model
| eval total=input_tokens+output_tokens
| bin _time span=5m
| stats sum(total) as tokens by _time, model
| sort _time

Phase 3: Parse and Display Results

The MCP tool returns results as structured JSON directly — no newline-delimited parsing needed. Extract the result rows from each query response and display as formatted markdown tables:

Output Format

## Session Token Breakdown

**Session:** {slug} (`{session_id}`)
**Period:** {first_timestamp} → {last_timestamp}
**Claude Code:** v{version}

### Model Usage

| Model | Input | Output | Cache Read | Cache Write | Total | Cache % | API Calls |
|-------|------:|-------:|-----------:|------------:|------:|--------:|----------:|
| {model} | {n} | {n} | {n} | {n} | {n} | {pct}% | {n} |
| **TOTAL** | ... | ... | ... | ... | ... | ... | ... |

### Tool Usage (by call frequency)

| Tool | Calls | Output Tokens |
|------|------:|--------------:|
| {tool} | {n} | {n} |

### Subagent Usage

| Agent | Model | Input | Output | Total | API Calls |
|-------|-------|------:|-------:|------:|----------:|
| {slug} | {model} | {n} | {n} | {n} | {n} |

### Token Burn Rate (5-min buckets)

| Time | Model | Tokens |
|------|-------|-------:|
| {time} | {model} | {n} |

Format all token counts with thousand separators for readability (e.g., 37,064).

Phase 4: Efficiency Analysis

After displaying raw data, provide a brief analysis:

• Cache efficiency: If cache_pct < 50%, flag as "Low cache hit rate — context may be churning"
• Heavy tools: If any single tool accounts for >40% of output tokens, flag it
• Subagent cost: If subagent tokens exceed 30% of main session tokens, flag it
• Burn rate spikes: Note any 5-min buckets with >2x the average

Keep analysis to 3-5 bullet points max. Data speaks for itself.

Error Handling

Error	Resolution
MCP tool not available	"Splunk MCP server not configured. Check nix-darwin mcpServers."
Auth failure	"Splunk MCP auth failed. Check SPLUNK_MCP_TOKEN in Doppler."
Connection refused	"Cannot reach Splunk. Check VPN/network."
No results	"No telemetry for session {id}. Data may not have been ingested yet."
Subagent query empty	Skip subagent section — not all sessions use subagents

Notes

• All aggregation happens server-side in Splunk — Claude only receives summary rows
• Session data lands in Splunk via: Claude Code → OTEL Collector → Cribl Stream → Splunk HEC
• There may be a ~60s ingestion delay between Claude Code activity and Splunk availability
• Token counts come from the Anthropic API response usage object — they are exact, not estimates
• The Splunk MCP Server App has a 1-minute query timeout and 1000-event max per query
• Our queries use stats aggregation so results are small summary rows — well within limits

Related Skills

This is a standalone analytics skill. It is useful alongside any development workflow skill that involves active Claude Code sessions.