# Token Chart

> Generate a 7-day token usage chart (all chats) and post it to the web UI timeline.

- Skill: `rcarmo/token-chart` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add rcarmo/token-chart`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rcarmo/token-chart/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: rcarmo (https://skillmd.com/u/rcarmo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rcarmo/token-chart

---


# Token chart

Generate token-usage charts from the database or from session files.

## Modes

- `default` — daily stacked token-usage bars across the last N days
- `provider-model` — stacked usage grouped by provider + model for attribution by model family
- `provider-model-cost` — estimated cost grouped by provider + model using the pricing reference bundled with the script

## Examples

Default chart:

```bash
bun /workspace/.pi/skills/token-chart/token-chart.ts
```

Provider + model chart:

```bash
bun /workspace/.pi/skills/token-chart/token-chart.ts --mode provider-model
```

Estimated provider + model cost chart:

```bash
bun /workspace/.pi/skills/token-chart/token-chart.ts --mode provider-model-cost
```

Post to the web chat via IPC:

```bash
bun /workspace/.pi/skills/token-chart/token-chart.ts --ipc
```

Post via IPC and allow a Pushover nudge:

```bash
bun /workspace/.pi/skills/token-chart/token-chart.ts --ipc --nudge
```

## Data sources

- default source: `token_usage` rows in `${PICLAW_STORE}/messages.db`
- `--source sessions`: read usage from session files under `${PICLAW_DATA}/sessions` instead of SQLite
- `--sessions-dir <dir>`: override the session-file location explicitly

Use `--source sessions` when DB-backed token usage is unavailable or when you want to inspect raw session-file history directly.

## Output behaviour

- `--ipc` writes an IPC message JSON file and, if needed, an SVG media file so piclaw posts the chart to the web timeline.
- without `--ipc`, the script writes markdown to stdout with an embedded SVG data URL plus summary text.
- `--output-svg <path>` writes the SVG to a file in either mode.

## Notes

- Numbers are formatted with compact `K` / `M` labels.
- Use this on demand unless you intentionally wire it into a scheduled task.