tokr

tokr is a local usage ledger for Claude Code and Codex on Linux, macOS, and Windows.

If you use coding agents all day, the transcript files are not a good source of truth for cost. They get rotated, archived, or deleted, and they are awkward to query once a session is over. tokr turns the usage records already sitting in those transcripts into a small SQLite ledger you can keep querying later.

It stores counts, timestamps, models, session metadata, and cost. It does not copy prompt bodies or assistant responses into the database. Nothing leaves the machine unless you explicitly run tokr prices update.

Why tokr

• Keep a durable record of token spend after the original transcript is gone.
• Backfill history once with tokr sync, then keep the ledger current with harness hooks.
• See the current repo with tokr stats, or everything with tokr stats --global.
• Break usage down by model, project, source, session, or time window.
• Re-price old rows when model pricing changes without re-ingesting the world.

This is for the boring questions that come up after a week of agent work: what did this repo cost, which model is doing the damage, and how many billing windows did a day actually turn into.

Install

Requires Rust 1.85 or newer.

cargo install tokr --locked

To build from a local checkout instead:

cargo install --path . --locked

Or build a release binary manually with cargo build --release.

Quick start

# Import transcripts already on disk
tokr sync

# Dashboard for the current working directory
tokr stats

# Same dashboard across every tracked project
tokr stats --global

# Time-bucketed reports
tokr report --daily --last 14d
tokr report --by model --last 7d

# Five-hour billing windows
tokr blocks --last 14d

tokr stats scopes to the current working directory by default. Use --global when you want the whole ledger.

Hook setup

tokr sync is enough for backfill. If you want the ledger to stay current as sessions end, wire tokr hook into your harness config.

The shipped snippets live in harnesses/claude-code/hooks/hooks.json and harnesses/codex/hooks.json.

Claude Code:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "tokr hook",
            "timeout": 10
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "tokr hook",
            "timeout": 10
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "tokr hook --final",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Codex:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "tokr hook",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

On the hot path, tokr hook reads the harness JSON payload from stdin and ingests only the transcript bytes that have not been seen yet. Claude's --final pass rescans at session end so the ledger catches anything that landed after the incremental hooks.

How it works

• tokr sync walks the standard Claude Code and Codex transcript roots under your home directory, or CODEX_HOME/sessions if you override Codex's default location.
• tokr hook ingests new usage as the harness fires Stop, SubagentStop, or SessionEnd.
• Each row is keyed by the source message id and inserted with INSERT OR IGNORE, so re-ingesting does not double-count.
• Costs are stamped with a pricing_version such as gpt-5.4@2026-04-01, which keeps historical totals stable when price tables move.
• The ledger lives in SQLite with WAL mode enabled in the platform-local app-data directory.

Once rows are in the ledger, transcript churn stops mattering. You can archive or delete the original files and still run reports later.

Pricing

Base prices live in data/pricing.toml in USD per million tokens.

tokr prices list
tokr prices update
tokr prices recost --dry-run
tokr prices recost --model gpt-5 --since 2026-04-01

tokr prices update is the only command that reaches the network. Updated entries are written alongside the ledger in the platform-local app-data directory. Existing rows keep their original pricing_version until you run tokr prices recost.

Data and privacy

Files on disk live under the local app-data directory for your OS:

• Linux: ~/.local/share/tokr/
• macOS: ~/Library/Application Support/tokr/
• Windows: %LocalAppData%\\tokr\\data\\

Within that directory:

• tokr.db: the ledger database.
• pricing_overrides.toml: fetched pricing entries from tokr prices update.
• archive/: optional gzipped Claude Code transcripts from tokr sync --archive-older-than.

Run tokr db path if you want the exact ledger location on the current machine.

The database stores usage metadata: token counts, timestamps, model ids, session ids, project labels, transcript paths, cwd, and computed cost. It does not index prompt text or assistant output.

More queries

tokr report --last 30d --by project
tokr report --session <session-id>
tokr report --json --last 7d --by source
tokr blocks --source claude-code
tokr blocks --json --last 14d
tokr sync --source codex
tokr sync --archive-older-than 60
tokr db path
tokr db vacuum

report and blocks can both emit JSON if you want to script against the ledger.

Build and test

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo build --release --locked
cargo test --release --locked

License

MIT. See LICENSE.