Tokentap CLI
A local proxy with a terminal dashboard: shows how many tokens each Claude Code and Codex request sends and saves the prompts to files
- 811 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The proxy accepts all of the agent's requests to the model, including headers with the API key, and forwards them to the provider
- The full text of every request, with code and files from the context, is saved to disk as Markdown and JSON
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/tokentapDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The proxy accepts all of the agent's requests to the model, including headers with the API key, and forwards them to the provider
- The full text of every request, with code and files from the context, is saved to disk as Markdown and JSON
This is third-party code. Review the repository files before installing.
What it does
Tokentap installs as a PyPI package and shows the token usage of command-line AI agents in a live terminal dashboard. `tokentap start` brings up a local proxy on port 8080 and asks where to save the captured prompts (Enter keeps the default folder). In a second terminal, `tokentap claude`, `tokentap codex` or `tokentap gemini` launches the agent with a substituted API address: `ANTHROPIC_BASE_URL` for Claude Code, `OPENAI_BASE_URL` for Codex. For any other program there is `tokentap run --provider <name> <command>`, with the providers anthropic, openai, gemini and minimax. The proxy forwards each request to the provider's real address and parses the request body: it takes the model and messages, counts tokens with the `cl100k_base` encoding of the tiktoken library and adds a row to the table with time, provider, model and token count. A fuel gauge compares the running total with a limit (200000 by default, changed with `--limit`): green up to half, yellow from 50 to 80 percent, red above. The last prompt is shown under the table. Every request lands in the chosen folder as two files: Markdown with metadata and the raw JSON of the request body. On exit Tokentap prints a session total: the sum of tokens and the number of requests.
Who it is for. For developers who work with Claude Code, Codex or another command-line agent and want to see where the tokens go and what exactly the agent sends to the model.
Good fit when
- A Claude Code session hits the context window fast and you need to see which request added the most tokens
- You need to inspect which system instructions and messages the agent actually sent to the model
- You want an archive of the session's prompts in Markdown and JSON to review afterwards
- You are writing a program against an OpenAI-compatible API, for example with MiniMax, and want to see the size of each request
Not a fit when
- You need reports for past days and months: Tokentap sees only requests that passed through the proxy while it ran, and ccusage builds reports from local logs
- The program does not read an API address variable: the proxy gets traffic only from processes given a substituted `ANTHROPIC_BASE_URL`, `OPENAI_BASE_URL` or similar
- You need Windows: the project badges list only macOS and Linux
- You need a provider outside the list: the proxy knows the Anthropic, OpenAI, Google Gemini and MiniMax addresses and answers other requests with a 400 error
Example request
Install tokentap and tell me how to launch Claude Code so I can see token usage for every requestLimitations
Version 0.1.1, and the package metadata marks it Beta. MIT license.
The project counts tokens from the request body with the `cl100k_base` encoding, so the figure is an estimate and not the provider's billing data. Model replies are not counted: the code parses only the request.
Gemini CLI ignores a custom API address when signed in through OAuth, so Gemini support will start working after a fix on Google's side, as the known-issues section says.
The proxy forwards requests unchanged, and the OpenAI and Anthropic APIs are unavailable from Russia. It listens on 127.0.0.1, with the port set by `--port`.
How to disable. Stop `tokentap start` and launch the agent with its usual command, without the `tokentap` prefix. `pip uninstall tokentap` removes the package. Saved prompts stay in the folder you chose and have to be deleted by hand.
FAQ
How do I see how many tokens each Claude Code request uses?
Run `tokentap start` in one terminal and `tokentap claude` in another. The table in the first terminal adds a row per request: time, provider, model and token count. The gauge on top compares the running total with the 200000 limit, which `--limit` changes.
How do I see exactly what the agent sends to the model?
Every captured request is saved to the folder chosen at startup as two files: Markdown with metadata for reading and JSON with the request body as is. The last prompt is also shown under the dashboard table.
How do I connect a program that is not Claude Code or Codex?
`tokentap run --provider minimax python my_app.py` sets `OPENAI_BASE_URL=http://localhost:8080/minimax/v1`. Requests arrive at `/minimax/v1/chat/completions`, and the proxy strips the prefix and forwards them to the MiniMax address.
What if port 8080 is taken?
Pass another number with `--port` to both `tokentap start` and `tokentap claude`. The two values must match, or the agent keeps knocking on the old port.
What does the summary at the end of a session show?
On exit Tokentap prints one line: how many tokens the session accumulated and how many requests passed through the proxy. Per-request details stay in the saved files.
Discussion
No questions or reviews yet.
Related
CLI toolsToken Savior indexes code by symbol, keeps memory between sessions and rewrites noisy Bash commands so the agent spends fewer tokens
Local ledger of AI agent work: tokens, estimated cost, steps, changed files and checks per task for Claude Code, Codex and OpenCode
Magpie
magpie
Magpie — an app and local gateway that connect any model to Claude Code, Codex, Gemini CLI and OpenCode and switch them from the menu bar
A local dashboard for Claude Code sessions: timelines, token costs, tools, agents, skills and live sessions
An ai-forever proxy that serves GigaChat through OpenAI, Anthropic and Gemini APIs so Claude Code, Codex and Gemini CLI can run on it
A Rust terminal task board: every task runs in its own git worktree and tmux window while Claude Code, Codex, Gemini CLI and other agents work in parallel
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| Tokentap (this entry) | no | 811 | |
| ccusage | no | 19,125 | builds token and cost reports from the agents' local logs, with no proxy |
| claude-tap | no | 3,302 | also a local proxy, but with a traffic viewer for system prompts, tool calls and usage |
README in short
The repository has an English description with installation, a quick start and a command table, a diagram of how the proxy works, a list of providers with support status and a known-issues section. The code is split into modules for the proxy, request parsing, the dashboard and configuration, with a tests folder alongside.