stormzhang/token-tracker

Token Tracker (tt)

What it does – Token Tracker is a local, command‑line utility that watches how many AI‑model tokens you spend when using three popular code‑assistant agents: Claude Code, Codex, and Kimi Code. It reads the agents’ local transcript files, aggregates token counts, estimates the monetary cost, and shows the information in several convenient places:

• a custom StatusLine that appears inside the agent’s own terminal UI,
• a live “sidebar” pane that can be pinned in a split‑window (iTerm2, Ghostty, tmux),
• a set of daily/weekly/monthly reports you can invoke with tt daily, tt weekly, etc.

All data stays on your machine – there is no network upload.

---

Key features (from the README)

Feature	How it works
Unified tracking for three agents	Reads Claude Code JSONL logs, Codex JSONL + SQLite, and Kimi Code wire JSONL. Tokens are summed per session and per model.
StatusLine integration	• Claude Code – uses the official StatusLine API (four‑line layout). • Codex – injects two plain‑text lines via a Stop hook (no colour on newer versions). • Kimi Code – uses the official status_line interface (single colour line).
Live sidebar (tt sidebar)	A narrow pane that refreshes every 5 seconds, listing active sessions (last 5 h), a three‑city clock, recent prompts, a status‑light, and a “next‑step” suggestion extracted from the last AI reply. Clicking a line jumps to the corresponding iTerm2/tmux pane.
Automatic split‑screen for the current session	When you type $tt-sidebar inside a Codex or Kimi Code session, the tool opens a 1/3‑width pane on the right that shows the full prompt history for that session.
Quota monitoring	Shows sliding‑window usage for the typical 5‑hour and 7‑day limits, with progress bars and reset countdowns.
Cost analysis	Uses pricing data from LiteLLM and a built‑in fallback table covering major models (Claude Opus, Sonnet, Gemini, Grok, Chinese models like Kimi, GLM, Qwen, etc.). Calculates per‑session, daily, weekly, and monthly cost.
Themed output	Six colour themes (Catppuccin family, Nord, Dracula). Themes apply to CLI reports and to the agents’ status lines.
Zero‑config detection	On first run it auto‑detects which agents are installed and reads their local data directories.
Privacy‑first	No data is sent anywhere; everything is stored locally under ~/.config/token-tracker.

---

Typical workflow

1. Install – run the one‑liner curl … | bash. The script picks the best installer (uv, pipx, or a private venv).
2. Setup – tt setup walks you through a short interactive wizard (language, theme, whether to take over each agent’s status line).
3. Use –
   • tt or tt daily shows a GitHub‑style heat‑map of token usage for the past year.
   • tt status gives today’s totals and quota percentages.
   • tt weekly / tt monthly produce bar‑chart reports.
   • tt sidebar opens the live pane; tt sidebar --once prints a single snapshot.
   • Inside a Codex/Kimi session, type $tt-sidebar to get an automatic split‑screen view.
4. Adjust – Change theme with tt theme set <name>, or re‑run tt setup to modify the status‑line configuration.
5. Uninstall – tt unsetup removes the hooks/skills and restores any previous custom status lines.

---

Who might find it useful?

• Developers who frequently use AI coding assistants and need to keep an eye on token consumption to avoid surprise bills.
• Teams that share a quota (e.g., a 5‑hour sliding window) and want a quick visual cue of how close they are to the limit.
• Anyone who likes a tidy terminal UI – the sidebar and status‑line give at‑a‑glance metrics without opening a separate dashboard.

---

Limitations / considerations

• It only works with the three supported agents; other LLM front‑ends are ignored.
• All cost calculations rely on static price tables; if a provider changes pricing, the built‑in data must be updated.
• The “next‑step” suggestion is rule‑based, not generated by a model.
• On Windows, the sidebar adapts to the console’s GBK encoding, but some colour fidelity may be reduced.

---

Quick reference (commands)

tt setup          # initial configuration, installs status‑line hooks & sidebar skill
tt               # same as `tt daily` – yearly heat‑map
tt daily          # heat‑map of token usage
tt status         # today’s totals + quota bars
tt weekly         # weekly report (cost, tokens, trends)
tt monthly        # monthly report
tt sessions       # list recent sessions, sortable
tt sidebar        # live pane with active sessions
tt sidebar --once# single snapshot
tt theme …       # show / list / preview / set themes
tt unsetup        # remove all injected hooks/skills

---

Bottom line – Token Tracker is a genuine, open‑source Python tool that gives developers concrete visibility into how many tokens their AI coding agents are consuming, how much those tokens cost, and whether they are approaching quota limits, all from the comfort of the terminal.