Retok

retok(return-of-token)

English | 日本語

A CLI tool that analyzes your AI coding agent usage logs — Claude Code and OpenAI Codex CLI — to measure token efficiency, estimate cost, and print actionable recommendations.

Runs on Python 3 with the standard library only — no dependencies.

Installation

Requires Python 3.7+. No dependencies.

To run it from anywhere, symlink it into your PATH (the symlink is resolved, so translations in locales/ keep working):

Alternatively, grab just the script — everything works, but the report falls back to English because locales/ is not present:

Usage

By default it scans Claude Code transcripts in ~/.claude/projects (plus $CLAUDE_CONFIG_DIR/projects when that environment variable is set) and Codex CLI rollouts in ~/.codex/sessions. If you keep transcripts elsewhere (multiple profiles, custom config dirs), pass every root with --dirs / --codex-dirs. Usage records are deduplicated globally, so overlapping roots are never double-counted.

What it measures

Recommendation rules

- Cache TTL expiry — a large cache write (majority of the context) right after a gap longer than the write's TTL (1h/5m, detected from the usage buckets) means an expired prefix was re-cached from scratch. Suggests /compact / /clear
- Oversized contexts — sessions exceeding 120k tokens, with at least 3 prompts in the session. Suggests /clear between tasks
- Under-delegation — high Read/Grep/Glob share on the main thread with little subagent use
- Retry loops — the same Bash command executed 5+ times within a session
- Frequent interruptions — [Request interrupted by user] above 12% of prompts, only evaluated once the period has 30+ prompts. Suggests clearer prompts and Plan Mode
- Premium models on tiny sessions — one-shot Q&A on Opus/Fable-class models, 10 or…