Pay pixels, not tokens. Bulky text enters the model as dense PNG pages, at a fraction of the price.
AI models charge for every token they read. tanuki-context turns the bulky parts of a conversation — logs, command output, long documents — into compact PNG pages the same model reads for a fraction of the price. Node >= 18 or a static Rust binary, zero dependencies either way.
It is just how pricing works: text costs about 1 token per 4 characters; an image costs a fixed amount set by its pixel size, no matter how much text is drawn inside it. Pack 28,000 characters into one 1568x728 page and the model reads it for 1,456 tokens instead of ~7,000. pxpipe found how far that gap stretches; tanuki packages it so the model itself decides when to use it, plus a proxy mode for clients you can't change.
Measured on a 200 KB slice of a real system journal (identifiers rewritten;
repetition and every error line untouched). Reproduce with npm run tiers.
| how the log enters the conversation | tokens | saved |
|---|---|---|
| pasted as raw text | 51,200 | 0 |
| drawn as image pages | 10,752 | -79% |
| noise removed first, then drawn | 5,264 | -90% |
| plus codebook and tiny font | 2,576 | -95% |
Every row is one command on your own file — estimate is instant, renders
nothing, and says so when plain text would be cheaper:
npx tanuki-context estimate your.log 0 --distill --codebook --font tiny
claude mcp add tanuki-context -- npx -y tanuki-context
Any MCP client: { "command": "npx", "args": ["-y", "tanuki-context"] }. Or
price a file with no client at all — --cached flips the verdict when the
text would ride the prompt cache:
npx tanuki-context estimate big.log 0 --model claude-opus-4 --cached
- Your model can't read images. Hard requirement (any current Claude qualifies).
- The exact bytes must survive. Secrets and credentials are auto-refused — never imaged. Dense random strings can misread silently, so the
verbatimsidecar ships uuids/hashes/ids as text; edit-targets should stay text. - The content is small, or your bill is output-dominated.
tanuki_statsreports the output share so you can tell. - You're not on Anthropic pricing. Pass
modeltotanuki_estimatefor provider-correctcost(OpenAI tiles, Gemini tiles), overridable viaTANUKI_RATES.
- Recency-tiered proxy (
--recency N, orTANUKI_RECENCY): recent turns stay text and are reasoned over precisely; only distant bulk is imaged (VIST slow-fast routing). - Credential gate: any block carrying an API key, private-key block, or token is never rendered to pixels — a documentation warning turned into a guarantee.
- Lean surface:
tools/listadvertises 3 tools by default (TANUKI_ALL_TOOLS=1for all 7); brief tool descriptions by default (TANUKI_TOOL_VERBOSE=1for the full contracts).
- Full manual — three run modes, the seven tools, stash/fetch, the table knob, benchmarks, internals.
- Design notes — why each pipeline stage exists.
- Evals — we publish the harness, not a number:
needles(read-back fidelity, results published),paired(cost per successful task),taskqual(task success on pages vs text). - Research roadmap — how tanuki maps onto DeepSeek-OCR, Glyph, and VIST.
Rust: cargo install --git https://github.com/Osyna/tanuki-context --branch rust
— the same engine as one static binary, held byte/pixel-exact with the npm
package by a parity harness.
MIT. The bundled glyph atlas derives from the Spleen font, GNU Unifont, and pxpipe — see NOTICE.