GitHub - d-date/retok: Token-efficiency analyzer for AI coding agents (Claude Code, OpenAI Codex CLI): cost estimates, cache analysis, and savings advice. Zero dependencies. · GitHub

/" data-turbo-transient="true" />

Skip to content

Search or jump to...

Search code, repositories, users, issues, pull requests...

-->

Search

Clear

Search syntax tips

Provide feedback

--><br>We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted

Cancel

Submit feedback

Saved searches

Use saved searches to filter your results more quickly

-->

Name

Query

To see all available qualifiers, see our documentation.

Cancel

Create saved search

Sign in

/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up

Appearance settings

Resetting focus

You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.

Dismiss alert

{{ message }}

d-date

retok

Public

Notifications<br>You must be signed in to change notification settings

Fork

Star<br>27

main

BranchesTags

Go to file

CodeOpen more actions menu

Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit

History<br>17 Commits<br>17 Commits

.github/workflows

.github/workflows

docs

docs

locales

locales

.gitignore

.gitignore

LICENSE

LICENSE

README.ja.md

README.ja.md

README.md

README.md

retok

retok

test_retok.py

test_retok.py

View all files

Repository files navigation

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.

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

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

■ Recommendations

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

Installation

Requires Python 3.7+. No dependencies.

git clone https://github.com/d-date/retok.git<br>cd retok<br>./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<br>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<br>chmod +x ~/.local/bin/retok

Usage

./retok # report for the last 30 days<br>./retok --days 7 # change the window<br>./retok --project myapp # filter by project name (substring)<br>./retok --provider codex # only one provider (claude | codex)<br>./retok --lang en # report language (default: $LANG)<br>./retok --json # JSON output for other tools<br>./retok --top 20 # rows in ranking tables<br>./retok --dirs ~/somewhere/projects # override Claude Code roots<br>./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.

What it measures

Metric<br>Meaning

Estimated cost<br>USD estimate based on published per-model pricing (table below)

Cache hit rate<br>cache_read / (input + cache_read + cache_write) — higher is cheaper

Cost per prompt<br>Cost consumed per human instruction

Subagent share<br>Consumption by subagents (Task/Explore; /subagents/agent-*.jsonl)

maxCtx<br>Peak context size within a session — the bigger, the more each request costs

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 —...