Token Tracker (tt): local token and cost tracking for Claude Code, Codex and Kimi Code

What Token Tracker solves, and for whom

Agent CLIs write their token accounting into local session files, and each one uses a different format. Claude Code keeps transcripts, Codex keeps its own session records, and Kimi Code keeps wire logs. None of them gives you a single view across all three, and none of them prices a mixed-model session for you.

Token Tracker reads those local records and produces one number set. The README describes it as a local tracking and analysis tool for Claude Code, Codex and Kimi Code, with a custom status line plus a CLI dashboard for token usage, equivalent cost and quota state. The intended user is a single developer running these agents on their own machine. The README states that data stays local and is neither collected nor uploaded, which is the main reason to prefer it over a hosted dashboard.

The scope is deliberately per-machine. There is no server component and no team aggregation in the repository layout: the top level holds install.sh, pyproject.toml, src/, tests/ and assets/. If you need to know what ten engineers spent last month, this is not the tool.

How the status line and the reports get their numbers

The mechanism differs per agent, and the difference matters when you debug it.

For Claude Code, the README says the status line uses the official custom StatusLine interface and that data comes entirely from local Claude with no inference. The four-line layout parses the transcript: session token totals, equivalent cost as reported by Claude Code itself, quota percentages for the 5-hour and 7-day sliding windows, context window usage, output tokens per second, model and reasoning level, and session duration. Quota figures only exist in subscription mode; the README notes that API mode has no subscription quota, so line 2 shows only the context segment.

For Codex, there is no official status line. Token Tracker injects a faux status line through a hook: after each answer completes, two truecolor lines are appended to the answer. The first line carries project, branch, cumulative session tokens and model; the second carries 5h and 7d quota bars plus context usage. The README states these lines do not enter the model context and that quota is read per current session or per model_provider, so multiple accounts and providers do not mix.

For Kimi Code, the README says the status line uses the official status_line interface in tui.toml, a single truecolor line with project, branch, total, cost, 5h and 7d percentages and model. Totals and cost accumulate incrementally from wire.jsonl using an offset cache, which is why the per-second refresh only reads new bytes.

Reports read the same sources. tt status, tt weekly, tt monthly and tt sessions render panels and charts. Pricing comes from litellm online prices with a built-in fallback list, and the README says long-context tiered prices and DeepSeek peak/off-peak prices are applied per request.

Install and first run

The README gives a single curl command. The installer picks between uv, pipx and a private venv, and the README says this avoids PEP 668 restrictions and does not touch the system Python.

curl -sSL https://raw.githubusercontent.com/stormzhang/token-tracker/main/install.sh | bash

After that, configure the agent integrations. The README shows tt setup as the step that configures status lines and installs the Codex and Kimi Code tt-sidebar Skill and prompt hook.

tt setup
tt

Running tt with no arguments produces the past year heatmap plus a three-part summary at the top, which the README identifies as the same output as tt daily. If you want the live panel instead, tt status shows today's merged overview, 5h and 7d quota and today's sessions.

tt status
tt weekly
tt sessions

One caveat is stated plainly in the README: status line takeover is optional, and if you already have a custom statusLine the wizard keeps your configuration by default. The trade-off is that Claude Code quota data only reaches disk through the status line script, so if you decline takeover, the subscription quota section of tt status has no data source.

The Codex faux status line is a workaround, and it behaves like one

The README calls the Codex status line industry-first, and in the narrow sense that no official hook exists, that is accurate. It is still a hook that appends text to model answers, and that has consequences.

Codex treats non-managed hooks as untrusted. The README instructs you to run /hooks after installation and trust the Token Tracker entry. If the Skill does not appear immediately, restart Codex. That is two manual steps that a supported interface would not need, and a Codex release that changes hook handling can break the integration until Token Tracker ships a fix. The release history reflects this pattern: v0.4.5 fixed a dead Python path in the Codex status line, v0.4.4 fixed a Windows config.toml path escaping crash, and v0.4.3 fixed a curl install crash alongside a README rewrite.

There is also a data-freshness boundary. The README notes that Codex establishes its window mapping only after the next answer completes, so the click-to-jump behavior in the sidebar lags until then. The sidebar itself refreshes every 5 seconds and is read-only, which limits the blast radius if something goes wrong.

If you are not on Codex, most of this section does not apply. Claude Code and Kimi Code use official interfaces, and the README says an existing custom status_line.command is not overwritten unless you choose to.

Where the sidebar and the split-pane Skill stop working

The tt sidebar command is a live panel meant for a narrow terminal pane or tmux split. It lists sessions active in the past 5 hours, sorted by recent activity, up to 10, with a status light, project and branch, agent, model and idle time. It also shows a three-city clock row, the last few prompts per session, and a next-step suggestion extracted from the AI's last reply by rules rather than a model call. tt sidebar --once prints one frame and exits, and --claude or --codex filter to a single agent.

The per-session split view is a separate Skill, invoked as $tt-sidebar in Codex or /skill:tt-sidebar in Kimi Code, which opens a pane occupying one third of the width to the right of the current session. Platform support is where this narrows: the README lists iTerm2, Ghostty 1.3.0 or newer on macOS, and tmux. Terminal emulators outside that list are not covered.

Two more constraints are documented. First, iTerm2 native full screen refuses AppleScript column-width changes, so you must leave full screen before running the Skill. Second, Kimi Code has no session ID environment variable, so the launcher locates the current session by matching cwd (with a legacy workDir fallback) and the newest updatedAt. That heuristic can pick the wrong session if two Kimi sessions share a directory. The hook pushes new prompts through a local FIFO and returns immediately when no sidebar is open, which the README says avoids polling the transcript.

Alternatives and how the approach differs

The closest alternative is the agent vendors' own usage surfaces. Claude Code already reports the session cost in its status line, and the README's own field table credits that number to Claude Code itself. If Claude Code is your only agent, its built-in display plus your provider's billing page covers most of what Token Tracker shows, and you avoid installing a hook into your editor workflow.

The difference appears with mixed usage. Token Tracker normalizes three agent formats into one report, prices requests against litellm plus a built-in fallback table, and applies tiered long-context and DeepSeek peak/off-peak pricing per request. A vendor dashboard will not price a Codex session against Claude rates, and it will not show a 5h quota bar for a third-party provider that has no quota at all, which the README says Token Tracker handles by omitting the Limit prefix.

Hosted LLM observability platforms are the other category. They typically require an SDK wrapper or a proxy in the request path, which gives them cross-machine aggregation but also means prompts leave your machine. Token Tracker reads files the agents already wrote and has no network path for usage data, at the cost of being single-machine and dependent on each vendor's on-disk format staying stable.

Maintenance, licence and upgrade cost

The repository is not archived. The last push was on 2026-09-09, and the most recent release listed is v0.4.5 from 2026-06-25, while pyproject.toml declares version 0.5.7. That gap between the declared package version and the newest release entry is worth noting if you pin versions.

Upgrades are cheap by design. The README says rerunning the install command is idempotent and moves you to the latest version, and that releases adding new agent integrations require running tt setup again, giving $tt-sidebar as the example since it must be installed into the Codex user-level Skill directory. Uninstall is tt unsetup, which the README says also removes the Token Tracker-managed Skills and hooks; if ~/.agents/skills/tt-sidebar is already your own Skill, installation and removal leave it alone.

The known upgrade failure is environmental. If tt --version still shows the old version after upgrading, the README attributes it to an older install in a different Python environment shadowing the new one, common on Windows or after an early pip install. The documented fix is to uninstall and reinstall:

pip uninstall token-tracker
curl -sSL https://raw.githubusercontent.com/stormzhang/token-tracker/main/install.sh | bash

The project is MIT licensed, with the licence file at the repository root. That permits commercial use and modification, but it also means no warranty and no support obligation. Nothing here is legal advice; if you redistribute it or ship it inside a product, read the LICENSE file yourself. Dependency choices carry their own maintenance weight: questionary is pinned below 3.0 because the wizard patches private internals, and textual is loaded only when the live sidebar runs.

Editorial conclusion

Adopt Token Tracker if you already run Claude Code, Codex or Kimi Code on one machine and want per-session cost and quota numbers without sending anything to a server. Skip it if you need fleet-wide aggregation or a supported Codex status line, since the Codex integration is a hook-based workaround that Codex may ask you to trust. Before installing, check that Python 3.11 or newer is present and that you are willing to run tt setup, which writes status line configuration into Claude Code, Codex and Kimi Code.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. stormzhang/token-tracker on GitHub