Agent Tokenwatch

The problem#

Coding agents burn tokens fast, and the cost signal that would let someone notice and course-correct is usually buried in a dashboard nobody opens mid-session — or not surfaced at all. A CLI wrapper that watches an agent’s own logs and hooks needs to answer “what did this cost me” without reading the prompts, code, or transcripts that produced the answer.

What it does#

Agent Tokenwatch is a dependency-free Node.js CLI that captures local, metadata-only token and cost telemetry from Claude Code, OpenAI Codex CLI, and GitHub Copilot CLI. It installs lifecycle hooks where available, feeds supported command-backed status lines, accepts Codex OTLP/HTTP JSON and protobuf logs, and installs a set of tw-* skills. It records counts and operational structure — not prompts, code, transcripts, file paths, tool inputs, tool outputs, or arbitrary telemetry bodies.

Install and use#

Node.js 20 or later is the only prerequisite. The package is agent-tokenwatch on npm, and the command it installs is tokenwatch:

npm install -g agent-tokenwatch
tokenwatch install --agents all --scope user
tokenwatch doctor

Start a new agent session and the status line appears with the first reply. install wires hooks, the status line and the skills into every agent it finds; doctor checks that each one is really delivering data.

• Codex CLI: start it as tokenwatch-codex so its token counts reach Tokenwatch.
• One project only: tokenwatch install --agents all --scope project --project .
• Remove it all: tokenwatch uninstall --scope user takes out everything it added and restores whatever it replaced.

Skills that ship with it#

Skill	What it gives you
tw-retrospective-this-session	What the session in progress has cost so far, its cache health, and whether it runs expensive against your own recent average
tw-retrospective-overall	A weekly or monthly look back: which sessions, models and turns drove spend, and how the period compares with the one before
tw-token-cost-coach	An interactive walk-through of a real expensive moment (a long session, a cold break, a huge tool output, subagents) using your own telemetry
tw-cost-drivers-basics	Token economics from first principles: prompts, turns, why input, output and cache are priced differently, what a cache TTL does
tw-cost-audit-define-experiment	Design and track evidence-based experiments that cut token cost, judging the running ones before proposing new ones
tw-explain-statusline	What each status-line field means, what it deliberately doesn’t mean, and how to reconfigure it
tw-import-history	Imports history from before Tokenwatch was installed, checked against live capture, without reading a prompt, reply or code

Every skill works from metadata only: none of them reads prompts, code, transcripts or tool contents.

How it works#

  agent hooks / logs (Claude Code, Codex CLI, Copilot CLI)
        │
        ▼
  tokenwatch CLI ──▶ metadata-only extraction (counts, no content)
        │
        ├──▶ status line renderer (per-agent, command-backed)
        └──▶ tw-* skills (installed alongside the CLI)

The hard part#

Three different agents expose usage data in three different shapes — some via lifecycle hooks, Codex via OTLP/HTTP JSON and protobuf logs — and the tool has to normalize all of them into one status-line contract without ever touching the content those agents are working on, only the metadata describing what happened.

Where it stands#

Live and in active use. Distributed as a dependency-free Node.js CLI (engines.node >=20) with two bin entry points, tokenwatch and tokenwatch-codex.