TokenJam CLI
A CLI and local dashboard that find token overspend in Claude Code and Codex sessions and suggest concrete fixes
- 125 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Reads agent session logs and transcripts on disk and adds a status line and hooks to Claude Code settings.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/tokenjamDetects 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.
- Reads agent session logs and transcripts on disk and adds a status line and hooks to Claude Code settings.
This is third-party code. Review the repository files before installing.
What it does
TokenJam reads agent telemetry and shows where tokens go. The `tj onboard` command wires live capture, backfills recent Claude Code and Codex history and installs a zero-token status line. `tj serve` opens the local Lens dashboard at 127.0.0.1:7391, and `tj optimize` prints a waste report to the terminal. Analyzers look for resent context, sessions where a cheaper model of the same family would do, bloated instruction files such as CLAUDE.md and AGENTS.md, and MCP servers whose schemas load but are never called. Each check ends with a concrete fix, and `tj rules list` prints the resulting rules. Data stays on your machine.
Who it is for. People paying for Claude Code or Codex tokens who want to see per session where money is wasted, with no data sent to a cloud.
Good fit when
- The Claude Code bill grew and it is unclear which sessions and models inflated it.
- Subagents run on an expensive model where a cheap one would do.
- A CLAUDE.md file has grown and weighs down every session.
- A team wants a one-off report without installing: `npx tokenjam` is enough.
Not a fit when
- You need a cloud observability dashboard for a whole team: TokenJam runs locally.
- The agent writes no telemetry or readable session logs to disk.
- The report must guarantee answer quality after a model switch: cheaper model suggestions do not prove equal quality.
Example request
Show how many tokens my sessions wasted over the month and which CLAUDE.md edits would save the most.Limitations
The advertised savings of up to 40 percent depend on a user's habits and are not guaranteed. Installation needs Node.js for `npx tokenjam` or Python 3.10 and newer for `pipx install tokenjam`. The Claude Code plugin only wraps `tj` commands and installs nothing itself, so `tj` must be on PATH. The `tj mcp` MCP server is opt-in and off by default. SDK agents add the `@watch()` decorator or export OTLP to a local address. The latest commit is from November 2026.
How to disable. Run `tj uninstall --yes` or, in Claude Code, `/tokenjam:uninstall`, then remove the package with `pipx uninstall tokenjam`. The status line and the session resume hook are removed by the same command.
FAQ
How do I see a report without installing?
Run `npx tokenjam`: it prints a read-only report over logs already on disk and keeps nothing.
Where does the dashboard open?
Run `tj serve` and open http://127.0.0.1:7391/. The Lens dashboard shows spend by model and session plus proposed fixes.
Which agents does it work with?
Claude Code and Codex through session logs, your own Python and TypeScript agents through the SDK, and any OTLP source.
How do I install the Claude Code plugin?
Run `/plugin marketplace add Metabuilder-Labs/tokenjam`, then `/plugin install tokenjam@tokenjam` and `/tokenjam:onboard`.
Can I import data from Langfuse?
Yes, with `tj backfill langfuse --source-url <url> --api-key <key>`, and Helicone is supported the same way.
Discussion
No questions or reviews yet.
Related
CLI toolsCounts token use and cost of Claude Code and Codex sessions from local logs and shows remaining limits in the status line
TokenTracker counts tokens and spend across Claude Code, Codex, Cursor, Gemini CLI and other agents from local logs and shows them on a local dashboard
A local CLI that shows where tokens go in Claude Code, Codex and opencode and holds back expensive messages
Tokdash shows token usage and session cost for Claude Code, Codex, Gemini CLI and a dozen more agents locally
A CLI built on ccusage that syncs your daily agent token usage to a public profile and leaderboard on tokenmaxxing.sh
Token and cost reports for Claude Code, Codex, Gemini CLI and other agents from local logs, by day, month and session
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| TokenJam (this card) | no | 125 | |
| ccusage | no | 19,425 | counts spend from Claude Code logs; TokenJam additionally finds causes of overspend and proposes fixes |
| Token Optimizer | no | 2,964 | compresses context and output; TokenJam measures sessions and shows where spend can be cut |
README in short
Setup starts with a wizard asking how you use agents and enables matching analyzers. MIT licensed, with no cloud and no signup.