# token-tracker fakes a status line for Codex because Codex has none

> A local token and cost tracker for three coding agents, with two official status line integrations and one hook-based workaround. Its release history is a single afternoon of crash fixes, and its uninstall path is unusually careful.

**stormzhang/token-tracker** — Claude Code & Codex 本地 token 追踪 — 状态栏（Codex 业界首创伪 statusline）、GitHub 风格热力图、多模型成本分析。 | Local token tracker for Claude Code & Codex — status line (industry-first Codex faux statusline), GitHub-style heatmap, multi-model cost analysis

- Repository: https://github.com/stormzhang/token-tracker
- Stars: 526 · Forks: 59
- Language: Python
- License: MIT
- Published: 2026-09-20 · Updated: 2026-09-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/stormzhang-token-tracker

## The tree is at 0.5.8 and the newest tag is 0.4.5

The package version in the manifest and the release history have drifted apart. pyproject declares version 0.5.8, while the newest GitHub release is v0.4.5 from 2026-06-25. The last commit is dated 2026-09-28, so the working tree is five patch versions ahead of anything you can download as a release artifact. The three most recent tags are also worth reading, because their titles are bug descriptions rather than feature names, and all three landed on the same night: v0.4.3 fixed a crash in the curl installer, v0.4.4 fixed a Windows crash caused by config.toml path escaping, and v0.4.5 fixed a dead Python path in the Codex status line. They went out at 02:22, 02:44 and 03:16 on 2026-06-25, so within fifty-four minutes. If you are pinning, pin to a release and know you are pinning to code from June.

## Codex has no status line, so the tool appends two plain lines

Two of the three integrations use a real interface. For Codex there is no official custom status line at all, so the project calls its own approach a faux status line and works around the gap: a Stop hook appends two lines of plain text after each answer completes. That workaround has a consequence the README states directly. From Codex 0.156.0 onwards, Codex filters ANSI control characters out of hook text, so the tool stopped emitting colour sequences to the hook entirely. The screenshot in the documentation is from before that version and is labelled as historical, because the current build shows the same fields and the same progress bars with no colour applied. Two other properties make the workaround tolerable: hook state does not enter the model context, which the project reports as measured rather than assumed, and the hook line does not follow the display theme, so it stays plain text while the other agents are colourised.

## Declining takeover costs you the Claude Code quota numbers

Taking over the status line is optional and the documentation is careful about the price of saying no. If you already run a custom status line, your configuration is preserved by default, the setup wizard lets you choose No at any point, and none of the report commands are affected. The catch is named rather than buried: if you decline, the Claude Code subscription quota section of the status report has no data source, because Claude Code only writes its quota figures to disk through the status line script. There is no second path. That is a fair trade for a tool that needs to own the render surface, but it means the quota numbers and the takeover are the same decision. The other integration is more polite: for Kimi Code, if a custom status line command already exists it is not overwritten by default, and the uninstall command restores the previous state precisely.

## Three agents, three mechanisms, two different sources of quota

The feature list claims unified tracking across Claude Code, Codex and Kimi Code, and the implementation section shows how little the three have in common. Claude Code uses the official custom status line interface, and the documentation stresses that the data comes entirely from the local Claude process with nothing inferred. Kimi Code uses its own official status line interface through a configuration file, rendering a single true-colour line, and its five-hour and seven-day limits come from a cloud usage endpoint cached in the background and refreshed every two minutes. Codex uses the Stop hook. So two agents read local state and one reads a cached cloud response. Token and cost accumulation for Kimi works differently again: totals are computed incrementally from the session wire log with an offset cache, so a once-per-second poll reads only the newly appended part rather than reparsing the file.

## Pricing has two layers and admits when it cannot price a model

Equivalent cost is the number people actually look at, and the project is candid about its confidence in it. Prices come from two layers: litellm's online pricing first, and a built-in table of official prices as the fallback. The built-in list covers the GPT-6 Astra, Sol and Luna variants, Claude Opus 5.5 and Fable 5.1, Grok 4.7, the Claude, OpenAI and Gemini families, and a set of domestic models including Kimi, GLM, Qwen, Doubao, DeepSeek, MiniMax and MiMo. Pricing is computed per request rather than per token, because that is what lets the tool apply long-context tiered pricing and DeepSeek's peak and valley structure, with the weekend treated as valley all day, and because Codex cache reads and cache writes are billed as different things. When a model is unknown the tool falls back to a known family price, and when even that fails it says the price is missing rather than printing zero.

## The installer picks your Python strategy and explains version shadowing

Installation is one piped command:

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

The script chooses the best available method for the machine, naming three options: uv, pipx, or a private virtual environment. The stated reason is to work around PEP 668 and to avoid touching the system Python. Upgrading is the same command, since the script is idempotent and moves to the latest version. One caveat is called out: after upgrading to a version that adds a new agent integration you must run setup again, because the sidebar skill for Codex is installed by setup into the user-level skill directory rather than by the installer. A documented failure mode is worth keeping. If the version command still reports the old number after an upgrade, an older installation in a different Python environment is shadowing the new one, which is common on Windows and after an early plain pip install. The fix is to uninstall the old distribution and re-run the script:

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

## The next-step hint is rule-based, and the skill will not overwrite yours

The sidebar panel makes one inference about your work and is careful to say how. Each session carries a status light: a running state with an animated marker, a needs-attention state for a tool call with no result, which the documentation suggests is usually a pending authorisation, a waiting-for-input state, and idle. The next-step suggestion is extracted by pure rules from the closing passage of the assistant's last reply, looking for a question or a to-do item, and no model is involved. When the agent is mid-question the panel shows the question and its options directly. Clicking a session header switches to the terminal pane it lives in, which depends on the agent's status line component having provided the mapping, and Codex only establishes that mapping after its next answer finishes. Refresh is every five seconds, read-only, and nothing is written. If you already have your own skill at the same path, neither setup nor uninstall touches it, and for Kimi Code the hook is appended into the configuration file by replacing only the tool's own managed block.

## Conclusion

Use token-tracker if you run more than one coding agent and want one place to see quota burn, equivalent cost and prompt history, since the aggregation across agents is the part no single vendor dashboard can do. Before you install, read the Codex section, because that integration is a hook rather than a real status line and it emits no colour. If you already have a custom status line, know that declining takeover costs you the Claude Code quota numbers, and keep the uninstall command handy because setup writes into agent config files.

## FAQ

### what is token tracker

A local tool for tracking token consumption and equivalent cost across Claude Code, Codex and Kimi Code. It provides a status line, a command line dashboard, quota monitoring, a session sidebar and multi-model cost analysis, with data stored locally and nothing uploaded.

### How do I track my token usage?

Run the installer, which chooses between uv, pipx and a private virtual environment, then run setup to configure the status line. The daily report shows a year of heatmap, status shows today plus five-hour and seven-day quota, and sessions lists the twenty most recent.

### Which AI agents does token-tracker support?

Claude Code, Codex and Kimi Code. Claude Code and Kimi Code use their official status line interfaces, while Codex has no such interface so the tool appends two plain text lines from a Stop hook instead.

### Why does the token-tracker Codex status line have no colour?

Codex 0.156.0 filters ANSI control characters out of hook text, so the tool stopped emitting colour sequences to the hook. The current build shows the same fields and progress bars uncoloured, and the screenshot in the README is from an earlier version.

### What happens to my existing status line configuration in token-tracker?

It is kept by default, and the setup wizard lets you decline at any point. The documented cost of declining is that the Claude Code subscription quota figures have no data source, since they only reach disk through the status line script.

### Why does tt --version show an old version after I upgrade?

An older installation in a different Python environment is shadowing the new one, which the documentation says is common on Windows and after an earlier plain pip install. Uninstall the old distribution with pip uninstall token-tracker and re-run the install script.

## Sources

- [Issues](https://github.com/stormzhang/token-tracker/issues)
- [License: MIT](https://github.com/stormzhang/token-tracker/blob/main/LICENSE)
- [README](https://github.com/stormzhang/token-tracker/blob/main/README.md)
- [Releases](https://github.com/stormzhang/token-tracker/releases)
- [stormzhang/token-tracker on GitHub](https://github.com/stormzhang/token-tracker)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/stormzhang-token-tracker