Exact Claude token counter for the terminal. Reuses your local Claude Code
login from the macOS Keychain — no ANTHROPIC_API_KEY required — and calls
Anthropic's official count_tokens endpoint, so the number matches what Claude
actually bills.
Build
cargo build --release
# binary at target/release/tok (optionally: cp target/release/tok ~/.local/bin/)Requires that Claude Code is installed and you've logged in at least once
(claude). The OAuth token is read from the Keychain entry
Claude Code-credentials.
Interactive mode (default)
Run with no input to open a Claude-Code-style field with a live count:
- Type or paste your prompt — the token count and estimated input cost update as you edit (debounced).
- Ctrl+V — smart paste: attaches an image if the clipboard holds one, otherwise inserts text. (Plain ⌘V text paste also works.)
- Pasted images appear inline as
[Image 1],[Image 2], … just like Claude Code. The placeholder is display-only — the image itself is counted as an image block, the[Image N]text is not. - Ctrl+X — drop the last attached image · Ctrl+L — clear everything
- Esc / Ctrl+C — quit
Pipe / scripting mode
Any text, file, or image argument switches to a single count-and-print:
tok "Hello, world!" # -> 16 tokens · ≈ $0.000240 input echo "from a pipe" | tok # reads stdin tok -q "just the number" # -> 11 (integer only, for scripts) tok --file prompt.txt # count a file's contents tok "describe this" -i shot.png # text + image (repeat -i for more) tok -m claude-haiku-4-5 "hi" # price reflects the chosen model
The cost shown is the input cost (what it takes to send this prompt once)
at the model's per-token input price — count_tokens doesn't generate output,
so there's no output cost to include. Prices are approximate, matched by model
family (opus/sonnet/haiku).
Options
| flag | meaning |
|---|---|
-f, --file <PATH> |
read prompt text from a file |
-i, --image <PATH> |
attach an image (png/jpg/gif/webp), repeatable |
-m, --model <ID> |
model to count against (counts are identical across Claude models) |
-q, --quiet |
print only the integer |
--interactive |
force the field even when input is piped |
How it works
tok reads the claudeAiOauth.accessToken (scope user:inference) from the
Keychain and POSTs your text/images to
https://api.anthropic.com/v1/messages/count_tokens with the
anthropic-beta: oauth-2025-04-20 header. It only sends content for counting;
no completion is generated and nothing is billed for tokens.
If you see a 401, your login expired — run claude once to refresh it.