Measure what a read gate could actually save you

git clone https://github.com/multimodeai/token-tax-kit
cd token-tax-kit
chmod +x hooks/size-gate.sh bin/token-tax

No dependencies to install.

Before installing any hook, look at what your sessions already cost.

./bin/token-tax report --project /path/to/your/repo

Track four fields:

• cache read — the conversation re-sent every turn
• input — genuinely new content
• over threshold — reads a gate would intercept
• targeted — reads already using offset/limit, which a gate ignores

Divide cache read by the sum of all four token lines. On four measured repos this was above 99.99% every time.

./bin/token-tax ceiling --project /path/to/your/repo

Two numbers print. Use the second — labelled counted every re-read, with an arrow reading <-- THE GENEROUS ONE. It is the bound that favours the gate. Record the percentage and the dollar figure below it.

./bin/token-tax ceiling --project /path/to/your/repo --threshold 100
./bin/token-tax ceiling --project /path/to/your/repo --threshold 700

If the ceiling stays in the same order of magnitude across all three, your result does not depend on where you drew the line. Record all three.

Create or edit .claude/settings.local.json in your repo. Use absolute paths.

{
  "env": {
    "TOKEN_TAX_MODE": "observe",
    "TOKEN_TAX_MIN_LINES": "350",
    "TOKEN_TAX_LOG": "/absolute/path/to/your/home/.token-tax/gate-log.jsonl"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "/absolute/path/to/token-tax-kit/hooks/size-gate.sh"
          }
        ]
      }
    ]
  }
}

Add .claude/settings.local.json to your .gitignore. It contains machine-specific absolute paths. observe never blocks — it logs what it would have blocked and prints a line in-session when it fires.

cat ~/.token-tax/gate-log.jsonl

Each line is one read the gate would have intercepted, with its line count. Count them against your total reads from step 2.

1. Ceiling in dollars — from step 3. The most you can win.
2. Cost of one wrong refusal — (avg cache read per turn ÷ 1,000,000 × input rate × 0.1) + (avg output per turn ÷ 1,000,000 × output rate). Both averages are report totals divided by assistant msgs.
3. Break-even — divide (1) by (2). That is how many wrong refusals per month wipe out your best case.

If the break-even number is small, enforcing will cost you more than it saves.

Change TOKEN_TAX_MODE to enforce and save. In a Claude Code session in that repo, ask it to read a file you know is over your threshold. Two checks:

• The gate must return a refusal, not Hook JSON output validation failed. That error means the hook is being rejected and reads are proceeding anyway.
• A read of the same file with an offset and limit must still go through.

The refusal is easy to miss on screen — it passes quickly and the assistant recovers on its own. Confirm from the log rather than by eye:

tail -3 ~/.token-tax/gate-log.jsonl

The mode field on the newest line must read enforce.

# gate off, after a normal working session:
./bin/token-tax snapshot before.json --project /path/to/your/repo

# turn the gate on, do comparable work, then:
./bin/token-tax snapshot after.json --project /path/to/your/repo

./bin/token-tax compare before.json after.json

Read the assistant msgs row first. If turn count rose, a token saving on reads is being paid for in round trips. That row is the point of the command.

If your ceiling comes out materially above 0.32%, open an issue on the repo with your ceiling output and your stack. Four repositories is a small sample.