How to Track Your Token Cascade
Every AI coding session has a cascade — the flow of tokens through four pillars. Here’s how to read it and track it automatically.
What a token cascade is — the four pillars
When you work with an AI coding agent, tokens flow through your session in four directions. That flow — the token cascade — is the complete record of how you and the model exchanged signal. Raw token volume tells you how much you spent. The cascade tells you how you spent it: whether you reused context efficiently or burned it from scratch every turn.
The cascade is described by four integers. No content, no prompts, no code — just counts. That’s what makes it privacy-preserving and platform-neutral: the same four numbers work whether you’re on Claude Code, Cursor, Copilot, or Gemini CLI.
The four pillars
1. Input
Fresh tokens you send to the model — new instructions, re-pasted files, prompts not served from cache. Every fresh input token costs full price. Tracking input tells you how much new context you’re injecting versus reusing.
2. Output
Tokens the model generates back — code, explanations, diffs, refactors. This is your gross signal. Tracking output tells you how much the model is producing per turn and per session.
3. Cache-read
Tokens reused from prior context via prompt caching. When the model already has your context loaded, it reads from cache instead of re-processing it. High cache-read is the signature of an efficient operator.
4. Cache-write
New tokens written to cache for future reuse. You pay now so the next turn is cheaper. A healthy cascade shows cache-write early, then rising cache-read as the session compounds.
How to read your cascade
The four pillars aren’t just counts — they’re a diagnostic. Here’s what each one tells you about your workflow:
High cache-read, low input
You’re reusing context well. The model has your codebase loaded and you’re sending small deltas. This is the ideal — high leverage, low cost. Your yield will be high.
High input, low cache-read
You’re re-sending context from scratch every turn. Prompt caching isn’t engaging. This is the most common waste pattern — and the easiest to fix by structuring your context window better.
High output, high cache-read
The model is productive and has good context. You’re getting a lot of signal out per unit of fresh input. This is an ARCH+-class cascade.
Low output, high input
You’re sending a lot but getting little back. The model is churning, re-rolling, or producing low-signal output. Your prompts may need restructuring — or your context is too noisy.
What each pillar tells you about your workflow
Input reveals how much fresh context you inject. If it’s high relative to cache-read, you’re not leveraging prompt caching — your context window strategy needs work.
Output reveals how much signal the model produces. Low output with high input means the model is struggling with your context — it’s either too noisy, too large, or poorly structured.
Cache-read reveals how well you reuse context. This is the single most important pillar for yield. High cache-read means you’ve built a stable context window that the model can reference cheaply.
Cache-write reveals how much you’re investing in future cache hits. High cache-write early in a session that converts to high cache-read later is a healthy, compounding cascade.
How to install sigrank and track automatically
You don’t need to track tokens by hand. The sigrank CLI reads your local logs on-device and counts the four pillars automatically. Here’s the step-by-step:
Step 1 — Install
npm install -g sigrank. This optional global installation provides the SigRank CLI. You can also run npx sigrank without installing it globally.Step 2 — Enroll
npx sigrank enroll. First sign in to SignalAF and generate a connect code in Settings. This links the device to your existing operator account and generates a local signing keypair.Step 3 — Read your cascade
npx sigrank. Reads local session logs and counts the four pillars across 7d, 30d, 90d, and all-time windows. You see the full cascade on-device before anything is submitted.Step 4 — Submit
npx sigrank submit. Publishes Claude telemetry by default, after enrollment. To use another supported source, select --platform. Use--dry-runto inspect the payload first. No prompt content ever leaves your machine.
FAQ
- What is a token cascade?
- The flow of tokens through an AI coding session, described by four pillars: input, output, cache-read, and cache-write. The cascade shape — not raw volume — determines your efficiency.
- What are the four token pillars?
- Input (fresh tokens sent), output (tokens generated back), cache-read (cached tokens reused), and cache-write (new tokens written to cache). They describe the complete token flow of any AI session.
- How do I track my cascade automatically?
- Run `npx sigrank` to inspect supported local telemetry. Create a connect code in Settings, run `npx sigrank enroll`, preview with `npx sigrank submit --dry-run`, then publish with `npx sigrank submit` (Claude by default).
- Does sigrank read my prompt content?
- No. The scanner reads token counts only. Only the four integers leave your machine, signed with ed25519. This is a core privacy guarantee.
- Which platforms are supported?
- SigRank works across Claude Code, ChatGPT, Gemini, Copilot, Cursor, and 15+ platforms. The bundled ccusage tool reads Claude Code logs natively.
Related: The Local Agent (MCP) · Yield (Υ) · Read Your Cascade