LIVE METER · AUTHOR'S MACHINE

STANDBY

0TOKENS KEPT OUT

This counter is real and it is currently zero. It starts moving the first time the hook clamps a read.

CLAMPS0

DUP HITS0

BYTES AVOIDED0

EST. TOKENS0

SNAPSHOT—

Get STK on GitHub ▸

github.com/ryanportfolio/STK · MIT · one Rust binary, no runtime deps · install ↓

UPPER BOUND, NOT A NET. Full methodology ↓

A Claude Code hook that stops oversized file reads from flooding your context.

One Rust binary, wired in as a PreToolUse hook on the native Read tool. Big file → the agent gets a ~2 KB line-numbered outline instead of the full dump, plus exact instructions to fetch any range with Read(offset, limit). Small files, scoped reads, binaries, anything STK can't analyze: all pass through untouched.

CH1 · THE MEASUREMENT

We looked before we built

Mined 250+ Claude Code sessions (27.8 MB of tool output across 24,597 tool results) to find where the tokens actually go:

38.6%

of ALL tool-result bytes sat in oversized (>8 KB) results: 10.7 MB carried by just 590 results. 2.4% of results held 38.6% of the bytes.

85%

of that oversized mass came from ONE source: the native Read tool. 9.1 MB, vs 1.0 MB from Bash. RTK's shell hook can never see it. This number is the whole reason STK exists.

READ9.1 MB

BASH1.0 MB

OTHER0.6 MB

Oversized (>8 KB) tool-result bytes by source, 250 sessions.

CH2 · THE MECHANISM

The narrowest tool that closes the gap

Decision in under 10 ms, in order. The first rule that matches wins. Everything STK doesn't understand passes through. It never blocks a read it can't analyze.

Read already has offset/limit→ALLOWnever fight a targeted read
File missing / unreadable→ALLOWlet Read produce its own error
Binary, image, PDF, notebook→ALLOWnothing to outline
≤ 16 KB→ALLOWsmall files were never the problem
Same file, same hash, this session→DENYone-line “unchanged” note, not a 50 KB re-dump
Big file, first sight→DENYoutline instead (the payload below)

What the model sees instead of 84 KB of source:

stk clamp: src/pipeline.ts — 84.3 KB, 2140 lines (threshold 16 KB).
Outline below; fetch only what you need with Read(file_path, offset, limit).

   1  import { … } (12 import lines)
  40  export interface Config
  92  export class Pipeline
 118    constructor(opts: PipelineOpts)
 143    async run(input: Stream): Promise<Result>
 402    private flush()
 ...
2101  export function main()

Re-read a symbol's body: Read with offset=<line>, limit=<span>.

The shape of an 84 KB file for ~2 KB. Nothing is lost: the agent re-reads any range on demand.

CH3 · THE SIBLING

Two meters, two streams

STK is the sibling of RTK (Rust Token Killer). Together they cover the two fattest input streams an agent pays for.

RTK versus STK
	RTK	STK
Scope	Shell command output	`Read` tool output
Unit	Per command	Per session
Mechanism	Filter & compress	Outline & clamp
Loss	Lossless (strips decor)	Lossy but recoverable (re-read on demand)

RTK · AUTHOR'S LIFETIME METER

COMMANDS97,474

TOKENS SAVED19.9M

REDUCTION77.9%

RTK's own accounting, from rtk gain on the author's machine, reported here as-is. Not measured by us.

CALIBRATION · METHODOLOGY

How the meter is wired

Source of truth: an append-only JSONL at %LOCALAPPDATA%\stk\stats.jsonl. One record per clamp or dedup hit, with file_bytes and sent_bytes.
Aggregation: stk gain --json emits totals plus a per-day series. bytes_avoided = file_bytes − outline_bytes per clamp. est_tokens = bytes ÷ 4. The divisor is an estimate and we say so.
Publication: a scheduled job on the author's machine runs stk gain --json and commits the snapshot into this repo. This page renders that file. No server, no credentials. “Live” means daily granularity, the granularity the data has.
The caveat, again: after a clamp, follow-up range reads cost tokens the hook can't see. The counter is an upper bound. Under-claiming is the brand.
Everything is auditable: the decision matrix, outline formats, store layout, and fail-open contract live in SPEC.md, in the same repo as this page.

TRANSMIT · INSTALL

Single binary, no runtime deps

cargo install --path .   # build the binary
stk init                 # prints the PreToolUse snippet

stk init prints the exact hook block to paste into ~/.claude/settings.json. STK never edits your settings for you. You paste it, so you stay in control of what runs in your agent. Verify with echo {} | stk hook claude: prints nothing, exits 0.

Tunables (all optional): clamp_threshold · outline_max_lines · dedup · exclude globs. Details in the README.