Early access — cascade metrics are real (derived from canonical token telemetry); the operator field is a curated seed. Learn more about the data
◈ Guide

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

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 a TRANSMITTER-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:

  1. Step 1 — Install

    npm install -g sigrank. This gives you the full toolkit: ccusage for Claude Code logs, tokscale for scaling, and token-dashboard for visualization.

  2. Step 2 — Enroll

    sigrank enroll. Generates an ed25519 keypair. Your submissions are cryptographically signed so the leaderboard can verify they came from you.

  3. Step 3 — Read your cascade

    sigrank me. 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.

  4. Step 4 — Submit

    sigrank submit. Publishes the four signed integers to the leaderboard. Use --dry-run to 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?
Install the sigrank CLI and run `sigrank me`. It reads your local session logs on-device and counts the four pillars across multiple time windows. Run `sigrank submit` to publish signed snapshots.
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.

Next: How to Read Your Cascade →