tokentap: a local HTTP proxy that counts LLM CLI tokens in a terminal dashboard
Intercept LLM API traffic and visualize token usage in a real-time terminal dashboard. Track costs, debug prompts, and monitor context window usage across your AI development sessions.
At a glance
- What is it?
- tokentap sits between your LLM CLI tool and the provider API, counting tokens and archiving prompts. It is a small, single-purpose tool with one provider blocked upstream and no published benchmark data.
- Who is it for?
- Adopt tokentap if you run Claude Code or Codex from a terminal on macOS or Linux and want per-request token counts without touching certificates or provider dashboards. Skip it if you need Gemini CLI coverage today, if you work on Windows, or if you need cost figures in currency rather than token counts, since the README describes tokens only.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 87 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap tokentap fills between a CLI agent and the provider dashboard
Provider consoles report usage after the fact, usually aggregated by day or by API key. That is fine for billing reconciliation and useless in the middle of a session when you want to know whether the next large file paste will push you past the context window. tokentap targets that gap. It is a local HTTP proxy plus a terminal dashboard, aimed at developers who drive Claude Code, Codex, or an OpenAI-compatible tool from a shell and want a running count as they work. The README frames the audience directly: people who want to see how many tokens each request consumes, watch cumulative usage against a limit, and keep a copy of every prompt for later inspection. The project was formerly named Sherlock, which is worth knowing if you find older references. It is written in Python, requires Python 3.10 or newer, ships under the MIT license, and lists macOS and Linux as platforms. Windows is not mentioned anywhere in the material.
How the proxy, the base URL override, and the path prefix fit together
The mechanism is a base URL swap, not packet inspection. You start the proxy with tokentap start, and it listens on localhost:8080 by default. In a second terminal you launch your tool through a tokentap wrapper, which sets an environment variable pointing the client at the local proxy instead of the provider. For Claude Code the README shows ANTHROPIC_BASE_URL=http://localhost:8080. The client then sends its request to your machine, tokentap reads the request and response bodies, extracts token counts, and forwards the traffic over HTTPS to the real upstream, for example api.anthropic.com. The dashboard is a separate concern layered on the same process: it renders a context usage bar, a table of requests with timestamp, provider, model and token count, and the opening text of the last prompt. The README also states that every intercepted request is written to disk as a markdown file for humans and a JSON file containing the raw request body.
OpenAI-compatible providers need more than a host swap because several of them share the /v1/chat/completions path shape. tokentap handles this with path-prefix routing. Running tokentap run --provider minimax python my_app.py sets OPENAI_BASE_URL=http://localhost:8080/minimax/v1, so requests arrive at /minimax/v1/chat/completions, the proxy strips the /minimax prefix, and forwards to https://api.minimax.io/v1/chat/completions. That prefix is the routing key. It also means the prefix is part of the contract: a client that rewrites or drops the path segment will not be routed correctly.
Getting it running: commands and the two options that matter
Installation is a single pip command, pip install tokentap, or a source install with git clone followed by pip install -e . The workflow is deliberately split across two terminals. Terminal one runs tokentap start; the README says you are prompted to choose where captured prompts are saved before the dashboard appears. Terminal two runs one of the wrappers: tokentap claude, tokentap gemini, tokentap codex, or the generic tokentap run --provider <name> <cmd> form. The supported values for --provider are anthropic, openai, gemini and minimax.
Two options are documented for tokentap start. The -p, --port flag changes the proxy port from its default of 8080, and -l, --limit sets the token ceiling used by the fuel gauge, defaulting to 200000. The limit is a display parameter, not an enforcement mechanism: nothing in the material suggests tokentap blocks a request when the bar turns red. The claude subcommand accepts -p, --port as well. The gauge colors are defined as green below 50 percent of the limit, yellow between 50 and 80 percent, and red above 80 percent. On exit, the README shows a session summary line of the form "Session complete. Total: 84,231 tokens across 12 requests."
Gemini CLI is listed as supported but blocked by an upstream bug
The provider table and the known issues section disagree in a way that matters. The table lists Google Gemini CLI with the status "Blocked by upstream issue," while the README badge row above it advertises Gemini CLI support. The explanation is that Gemini CLI ignores custom base URLs when using OAuth authentication, tracked in google-gemini/gemini-cli issue 15430. The README states that tokentap's Gemini support will work automatically once that issue is fixed upstream. Until then, tokentap gemini exists as a command but the proxy will not see the traffic if you authenticate with OAuth. Anyone evaluating this tool for a Gemini-based workflow should treat that path as unavailable and check whether the upstream issue is still open before planning around it.
A second limitation is structural rather than a bug. Because the mechanism is an environment variable override, any client that hardcodes its endpoint, pins a certificate, or routes through its own gateway will not be intercepted. The README's "zero configuration, no certificates" claim is accurate for the supported CLIs precisely because those CLIs respect a base URL variable. It is not a general-purpose TLS interception tool, and the material gives no indication that it attempts to be one.
What the dashboard does not tell you: currency, persistence, and accuracy checks
The repository description mentions tracking costs, but the README's feature list and dashboard mockup deal in tokens throughout: a context usage bar, a per-request token column, a limit expressed in tokens, and a session total in tokens. No pricing table, currency conversion, or per-model rate configuration appears in the supplied material, so any cost figure would have to be computed by you from the token counts. Treat the cost-tracking framing as aspirational relative to what the documentation actually specifies.
The archive is described as saving every prompt as markdown and JSON, but the README does not document retention, rotation, or redaction. Prompts written to disk can contain source code, credentials pasted into a chat, or customer data, and the material says nothing about scrubbing them. The choice of archive directory is the only control mentioned. There is also no published data on counting accuracy. Token counts can come from the provider's usage field in the response or from a local tokenizer, and those two methods disagree, particularly across model versions. The README does not say which tokentap uses, so the honest position is that the numbers should be spot-checked against provider-reported usage before you trust them for anything beyond a rough gauge.
How tokentap differs from itmproxy and from provider billing consoles
The topic list tags this project with itmproxy, which is the natural comparison. mitmproxy is a general HTTPS interception proxy: you install its certificate authority, configure your system or client to trust it, and then inspect and modify arbitrary traffic with a Python addon API. tokentap inverts those trade-offs. It does no certificate installation, which is why setup is a pip install and an environment variable, but it only sees traffic from clients that let you set a base URL, and it only understands LLM request and response shapes. If you need to inspect a non-LLM service, rewrite a response body, or replay a captured request, tokentap is the wrong tool and mitmproxy is the right one. If you only want a live token counter next to your Claude Code session, mitmproxy would be a heavier path to the same result.
The other alternative is doing nothing and reading the provider's usage page. That approach needs no local process, no port, and no prompt copies on disk, and it works with Gemini CLI today. Its weakness is timing: usage appears after the session, not during it, and it cannot show you the individual request that consumed 15,000 tokens. tokentap's value is the live per-request view, and that value only exists while the proxy process is running.
Maintenance surface and what the MIT license does and does not settle
The project is small and the dependency surface is the main ongoing cost. Two releases are listed, v0.1.0 in February 2026 and v0.1.1 in April 2026, with the last push to the default branch in June 2026. That is a young, low-version-number project, and the CLI wrappers depend on the base URL environment variables of third-party tools that change on their own schedule. The Gemini situation is the clearest example: tokentap's support for one provider is gated on a fix in someone else's repository. Expect to re-check the wrappers after major Claude Code or Codex releases.
On licensing, the repository is MIT, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are retained. That is the extent of what the material supports saying. Two things it does not address: the prompts tokentap copies to disk are your data and may be subject to your own obligations to customers or employers, and the license text itself should be read in the repository rather than inferred from the badge. Nothing here is legal advice.
Who should install it and what to check in the first ten minutes
The fit is narrow and clear. You run Claude Code or Codex from a macOS or Linux terminal, you want per-request token counts during a session rather than a daily total, and you are comfortable running a local proxy that writes prompt copies to a directory you choose. The install is one pip command and the mental model is one environment variable.
The misfits are equally clear. Gemini CLI users are blocked by the upstream OAuth issue. Windows users have no stated support. Anyone who needs dollar figures rather than token counts will be doing their own arithmetic. Anyone whose CLI tool does not honor a custom base URL cannot be proxied this way at all.
For the first run, three checks are worth doing before you build a habit around the dashboard. Confirm the port is free, since 8080 collides with a lot of local development servers and you would need -p to move it. Confirm your CLI actually routes through the proxy by watching whether a request row appears after one prompt. Then compare the token count in that row against the usage your provider reports for the same request, because the README does not document where the numbers come from and that is the single assumption the whole tool rests on.
Editorial conclusion
Adopt tokentap if you run Claude Code or Codex from a terminal on macOS or Linux and want per-request token counts without touching certificates or provider dashboards. Skip it if you need Gemini CLI coverage today, if you work on Windows, or if you need cost figures in currency rather than token counts, since the README describes tokens only. Before relying on it, verify that the port you plan to use is free, that your CLI tool honors a custom base URL, and that the token counts the dashboard shows match the usage reported by your provider.
Community notes