Retok: Token-efficiency analyzer for Claude Code and Codex CLI (zero deps)

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.

══════════════════════════════════════════════════════════════════════════
  retok — Token Efficiency Report (last 30 days / 472 files)
══════════════════════════════════════════════════════════════════════════

■ Overview
  Estimated cost            $2,119.66
  Claude Code / Codex       $2,091.00 / $28.66
  Cache hit rate            89.4%
  Cost per prompt           $1.593
  ...

■ Recommendations

  ! Re-caching after cache TTL expiry: ~135.0M tokens ($873.49)
    Returning to a session left idle beyond the cache TTL (usually 1
    hour) re-caches the entire context at twice the input rate. ...

Requires Python 3.7+. No dependencies.

git clone https://github.com/d-date/retok.git
cd retok
./retok

To run it from anywhere, symlink it into your PATH

(the symlink is resolved, so translations in locales/

keep working):

ln -s "$(pwd)/retok" ~/.local/bin/retok   # or /usr/local/bin/retok
retok

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

is not present:

curl -fsSLo ~/.local/bin/retok https://raw.githubusercontent.com/d-date/retok/main/retok
chmod +x ~/.local/bin/retok
./retok                    # report for the last 30 days
./retok --days 7           # change the window
./retok --project myapp    # filter by project name (substring)
./retok --provider codex   # only one provider (claude | codex)
./retok --lang en          # report language (default: $LANG)
./retok --json             # JSON output for other tools
./retok --top 20           # rows in ranking tables
./retok --dirs ~/somewhere/projects       # override Claude Code roots
./retok --codex-dirs ~/somewhere/sessions # override Codex roots

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.

Metric	Meaning
Estimated cost	USD estimate based on published per-model pricing (table below)
Cache hit rate	cache_read / (input + cache_read + cache_write) — higher is cheaper
Cost per prompt	Cost consumed per human instruction
Subagent share	Consumption by subagents (Task/Explore; <session>/subagents/agent-*.jsonl )
maxCtx	Peak context size within a session — the bigger, the more each request costs

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 tasksUnder-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 ModePremium models on tiny sessions— one-shot Q&A on Opus/Fable-class models, 10 or more such sessions in the period** Premium-tier concentration**— a single model priced above the median (currently Fable/Mythos) accounts for 90%+ of total cost, once total cost reaches $50. Suggests delegating light work to a cheaper model

Claude prices (USD / MTok, as of 2026-06):

Model	input	output
Fable 5 / Mythos 5	$10	$50
Opus 4.x	$5	$25
Sonnet 4.x / 5	$3	$15
Haiku 4.5	$1	$5

• Cache read = 0.1× input rate - Cache write = 1.25× input rate (5-minute TTL) /2×(1-hour TTL) — detected from thecache_creation

buckets in usage - One API response is written to the transcript as multiple entries; usage is deduplicated by message.id

OpenAI (Codex) prices (USD / MTok, as of 2026-07):

Model	input	output
gpt-5.5	$5	$30
gpt-5.4	$2.50	$15
gpt-5.3 / 5.2 (codex)	$1.75	$14
gpt-5.1 / 5.1-codex-max / 5	$1.25	$10
gpt-5-mini / nano	$0.25 / $0.05	$2 / $0.40

• Cached input = 0.1× input rate (no cache-write premium);cached_input_tokens

is a subset ofinput_tokens

and is unbundled before pricing - Usage comes from token_count

events in~/.codex/sessions

rollout files, deduplicated by the cumulative token counter

Note: figures are estimates based on published API pricing. If you are on a subscription plan (e.g. Max), read them as "how much compute you used in API terms", not what you actually paid.

The report language follows --lang

, then RETOK_LANG

, then LC_ALL

/ LC_MESSAGES

/ LANG

, falling back to English.

Available: en

(built-in), ja

, zh-CN

, zh-TW

, ko

, es

, fr

, de

, pt-BR

.

• Copy locales/ja.json

tolocales/<tag>.json

(BCP 47-ish tag, e.g.it

,pt-PT

) - Translate the values — keep the {placeholders}

intact - Test with ./retok --lang <tag>

and open a pull request

Missing keys fall back to English automatically, so partial translations are fine.

source & further reading

github.com — original article Show HN: Kiso – Publish one OKF knowledge base for humans and AI agents Show HN: Xyzzy – AI teamwork in one Python process, with a tamper-evident log Move Claude CLI Projects - MacOS