AI agent skill · by @platonai

Task Token Usage

Analyzes Claude Code session traces (JSONL) and draft task files to report token usage per task. Use when asked about token usage, session costs, or task efficiency metrics.

Archived 2026-10-23 · Source updated 2026-10-11 · License: Apache-2.0. Check the original repository for the latest version.

SKILL.md instructions

# Task Token Usage

Analyzes Claude Code conversation traces to report token consumption per task.

## When to Use

- "list tasks with token usage"
- "show me token usage for each task"
- "how many tokens did task X use?"
- "what tasks ran in the last N hours?"
- "compare token usage across tasks"

## How It Works

1. Scans `~/.claude/projects/<project>/` for JSONL session traces
2. Extracts `input_tokens`, `output_tokens`, `cache_read_input_tokens` from each assistant message
3. Optionally matches sessions to draft task files in `coworker/tasks/issues/draft/`
4. Prints a summary table grouped by task

## Usage

Run the bundled script:

```bash
python3 coworker/skills/task-token-usage/scripts/list-tasks.py [OPTIONS]
```

### Options

| Flag | Description |
|------|-------------|
| `--recent N` | Only show sessions from last N hours (default: 24) |
| `-d, --detail` | Per-session breakdown instead of grouped summary |
| `-a, --all` | Show all sessions (no time filter) |

### Examples

```bash
# Summary of last 12 hours
python3 coworker/skills/task-token-usage/scripts/list-tasks.py --recent 12

# Detailed per-session view for all time
python3 coworker/skills/task-token-usage/scripts/list-tasks.py --all --detail

# Default: last 24 hours, grouped summary
python3 coworker/skills/task-token-usage/scripts/list-tasks.py
```

## Output Columns (Summary Mode)

| Column | Description |
|--------|-------------|
| Task | Task name (matched from draft files or first step description) |
| Runs | Number of evaluation sessions for this task |
| In Tok | Total input tokens across all runs |
| Out Tok | Total output tokens across all runs |
| Cache | Total cache-read + cache-creation tokens |
| TOTAL | Sum of all tokens |
| Avg/run | Average total tokens per run |

## Output Columns (Detail Mode)

| Column | Description |
|--------|-------------|
| Time | When the session ended |
| Task | Matched task name |
| In | Input tokens |
| Out | Output tokens |
| CacheR | Cache-read tokens |
| TOTAL | Total tokens |
| Model | AI model used |

## Token Pricing (Approximate)

The script does not compute cost, but you can estimate:

| Model | Input (per 1M) | Output (per 1M) | Cached (per 1M) |
|-------|----------------|-----------------|-----------------|
| claude-sonnet-4.6 | $3.00 | $15.00 | $0.30 |
| claude-opus-4 | $15.00 | $75.00 | $1.50 |
| claude-haiku-4.5 | $1.00 | $5.00 | $0.10 |

Cache tokens account for ~96% of total usage in typical evaluation sessions.