tanuki-context 0.4.0 → 0.4.1

package/README.md

@@ -73,6 +73,63 @@ No AI client at all, just curious what it would save you:
 npx tanuki-context estimate some-big-file.log 0
 ```
 
+## Installing it: two ways, same tools
+
+**npm (the default).** `npx -y tanuki-context` downloads a 0.98 MB tarball
+with zero dependencies and starts the MCP server on stdio. That is the
+whole install. Your client spawns one short-lived process per session
+(35 ms to first response under node, 27 under bun); the model calls the
+seven `tanuki_*` tools; pages come back inline as PNG blocks. On disk it
+touches exactly two places, both yours to delete: `~/.tanuki/stash` for
+stashed text and `~/.pxpipe/events.jsonl` for the savings log.
+
+**cargo (the static binary).** No node at all:
+
+```
+cargo install --git https://github.com/Osyna/tanuki-context --branch rust
+```
+
+One 5.7 MB binary, same seven tools, same numbers — a 103-check parity
+harness holds the two engines to byte-identical JSON and pixel-identical
+PNGs on every release. It spawns in 0.4 ms and idles at 3.8 MB RSS, which
+matters when every session forks its own server. Point any client config
+at `"command": "tanuki-context"` instead of the npx line and nothing else
+changes.
+
+## Should you use it at all?
+
+Reach for tanuki when:
+
+- **bulky text is about to enter context** — logs, build output, command
+  results, long docs, anything past roughly 2,000 tokens;
+- **an agent keeps re-reading big files** — the proxy dedupes exact
+  repeats, and stash turns re-reads into cheap fetches;
+- **a long session is running out of context** — pages carry ~4x more
+  characters per token, and the proxy can image old bulky turns in place;
+- **you cannot change the client** — the proxy mode needs only a base-URL
+  export.
+
+Leave it alone when:
+
+- **your model cannot read images.** Hard requirement. Everything here
+  assumes a vision-capable reader (any current Claude model qualifies).
+- **the exact bytes must survive a round trip** — secrets, hashes, code
+  the model is about to edit. Rendering is exact, but model read-back of
+  dense random strings is not guaranteed (pxpipe measured 13/15 on
+  12-char hex). Keep those in text.
+- **the content is small.** A 500-token snippet is not worth a modality
+  switch even when the math technically favors it; `estimate` and the
+  proxy gate both say so.
+- **your bill is output-dominated.** tanuki cuts input tokens only. If
+  most of your spend is the model's own output, fix that first.
+- **you are not on Anthropic pricing.** Verdicts use Anthropic's
+  28-px patch grid. OpenAI and Google price images differently (tiles,
+  fixed per-image rates), so every verdict needs re-deriving before you
+  trust it there.
+- **the bulk is already prompt-cached.** Cache reads cost a tenth of
+  fresh input; imaging content that was riding the cache can be a net
+  loss. The proxy never touches `cache_control` blocks for this reason.
+
 ## The three ways to run it
 
 **Explicit (MCP tools) — the default and the recommendation.** Your AI gets
@@ -461,6 +518,20 @@ pi install npm:tanuki-context
 claude mcp add tanuki-context -- npx -y tanuki-context
 ```
 
+The package also ships a **skill** — a short instruction file that teaches
+the model the whole workflow (estimate first, read `recommend`, stash big
+references, the page decode grammar, the do-nots) without you prompting
+any of it. Install it once and the tools get used correctly on their own:
+
+```
+npm i -g tanuki-context   # or any install that gives you the package on disk
+cp -r "$(npm root -g)/tanuki-context/skills/tanuki-context" ~/.claude/skills/
+```
+
+From a checkout it is just `cp -r skills/tanuki-context ~/.claude/skills/`.
+The same file works for any skill-aware harness (OMP picks it up from the
+same directory).
+
 **Rust instead of Node?** Same pipeline, same numbers, one 5.7 MB static
 binary:
 

package/dist/agent.js

@@ -78,7 +78,7 @@ function oJ(){let J=cJ.env.TANUKI_STASH;if(J!==void 0&&J!=="")return J;return`${
 //!      tanuki-context estimate <file> [level] [--distill]
 //!      tanuki-context render <file> [level] [outdir]
 //!      tanuki-context proxy [--port N] [--upstream URL] [knobs]   (implicit mode)
-var rJ="0.4.0",RJ=6;function BZ(J,Q){let Z=Math.min(J.length,Q.length),$=0;while($<Z&&J.charCodeAt($)===Q.charCodeAt($))$++;if($>=Z)return J.length-Q.length;return J.codePointAt($)-Q.codePointAt($)}function L(J,Q,Z=""){if(J===null||J===void 0)return"null";if(J instanceof YJ){let z=J.value;return Number.isFinite(z)&&Number.isInteger(z)?z.toFixed(1):String(z)}let $=typeof J;if($==="string")return JSON.stringify(J);if($==="number"||$==="boolean")return String(J);if(Array.isArray(J)){if(J.length===0)return"[]";if(!Q){let O="[";for(let B=0;B<J.length;B++){if(B>0)O+=",";O+=L(J[B],!1)}return O+"]"}let z=Z+"  ",K=`[
+var rJ="0.4.1",RJ=6;function BZ(J,Q){let Z=Math.min(J.length,Q.length),$=0;while($<Z&&J.charCodeAt($)===Q.charCodeAt($))$++;if($>=Z)return J.length-Q.length;return J.codePointAt($)-Q.codePointAt($)}function L(J,Q,Z=""){if(J===null||J===void 0)return"null";if(J instanceof YJ){let z=J.value;return Number.isFinite(z)&&Number.isInteger(z)?z.toFixed(1):String(z)}let $=typeof J;if($==="string")return JSON.stringify(J);if($==="number"||$==="boolean")return String(J);if(Array.isArray(J)){if(J.length===0)return"[]";if(!Q){let O="[";for(let B=0;B<J.length;B++){if(B>0)O+=",";O+=L(J[B],!1)}return O+"]"}let z=Z+"  ",K=`[
 `;for(let O=0;O<J.length;O++){if(O>0)K+=`,
 `;K+=z+L(J[O],!0,z)}return K+`
 `+Z+"]"}let V=J,G=Object.keys(V).sort(BZ);if(G.length===0)return"{}";if(!Q){let z="{";for(let K=0;K<G.length;K++){if(K>0)z+=",";z+=JSON.stringify(G[K])+":"+L(V[G[K]],!1)}return z+"}"}let Y=Z+"  ",H=`{

package/dist/cli.js

@@ -84,7 +84,7 @@ function zQ(){let J=VQ.env.TANUKI_STASH;if(J!==void 0&&J!=="")return J;return`${
 //!      tanuki-context estimate <file> [level] [--distill]
 //!      tanuki-context render <file> [level] [outdir]
 //!      tanuki-context proxy [--port N] [--upstream URL] [knobs]   (implicit mode)
-var TZ="0.4.0",wJ=6,bJ=8000;function LZ(J,Q){let Z=Math.min(J.length,Q.length),$=0;while($<Z&&J.charCodeAt($)===Q.charCodeAt($))$++;if($>=Z)return J.length-Q.length;return J.codePointAt($)-Q.codePointAt($)}function P(J,Q,Z=""){if(J===null||J===void 0)return"null";if(J instanceof ZJ){let H=J.value;return Number.isFinite(H)&&Number.isInteger(H)?H.toFixed(1):String(H)}let $=typeof J;if($==="string")return JSON.stringify(J);if($==="number"||$==="boolean")return String(J);if(Array.isArray(J)){if(J.length===0)return"[]";if(!Q){let B="[";for(let U=0;U<J.length;U++){if(U>0)B+=",";B+=P(J[U],!1)}return B+"]"}let H=Z+"  ",K=`[
+var TZ="0.4.1",wJ=6,bJ=8000;function LZ(J,Q){let Z=Math.min(J.length,Q.length),$=0;while($<Z&&J.charCodeAt($)===Q.charCodeAt($))$++;if($>=Z)return J.length-Q.length;return J.codePointAt($)-Q.codePointAt($)}function P(J,Q,Z=""){if(J===null||J===void 0)return"null";if(J instanceof ZJ){let H=J.value;return Number.isFinite(H)&&Number.isInteger(H)?H.toFixed(1):String(H)}let $=typeof J;if($==="string")return JSON.stringify(J);if($==="number"||$==="boolean")return String(J);if(Array.isArray(J)){if(J.length===0)return"[]";if(!Q){let B="[";for(let U=0;U<J.length;U++){if(U>0)B+=",";B+=P(J[U],!1)}return B+"]"}let H=Z+"  ",K=`[
 `;for(let B=0;B<J.length;B++){if(B>0)K+=`,
 `;K+=H+P(J[B],!0,H)}return K+`
 `+Z+"]"}let V=J,z=Object.keys(V).sort(LZ);if(z.length===0)return"{}";if(!Q){let H="{";for(let K=0;K<z.length;K++){if(K>0)H+=",";H+=JSON.stringify(z[K])+":"+P(V[z[K]],!1)}return H+"}"}let G=Z+"  ",Y=`{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tanuki-context",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Token-cutting context pipeline as an MCP server: distill logs, compress text, render dense PNG pages (pxpipe imaging engine). Zero dependencies.",
   "license": "MIT",
   "type": "module",
@@ -17,6 +17,7 @@
   "files": [
     "dist",
     "assets",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/tanuki-context/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: tanuki-context
+version: 0.4.1
+description: |
+  Cut input-token cost by rendering bulky text (logs, command output, long
+  docs) as dense PNG pages the model reads at a fraction of the price, or by
+  parking it outside context and fetching slices. Use when pasting or reading
+  anything over ~2,000 tokens of logs, build output, or documents; when a
+  session is close to its context limit; or before re-reading a large file.
+  Requires the tanuki-context MCP server (tanuki_* tools) and a
+  vision-capable model.
+---
+
+# tanuki-context: pay pixels, not tokens
+
+Text costs ~1 token per 4 characters. A dense PNG page costs a fixed 1,456
+tokens and carries up to 28,080 characters. The tanuki_* tools exploit that
+gap deterministically: nothing is summarized by a model, errors stay
+verbatim, and every drop is counted.
+
+## Workflow
+
+1. **Estimate first, always.** `tanuki_estimate { text }` is instant and
+   never renders pixels. Read two things from the answer:
+   - `recommend` - the cheapest reversible knob set (pack/codebook), priced.
+   - `recommend.withDistill` - the log route (repeats collapsed with exact
+     counts). Cheaper, and honest for logs; do not use it on source code.
+2. **Act on the verdict.**
+   - `"PIPELINE cheaper"` and you need the content in front of you ->
+     `tanuki_render` with the recommended knobs. Use the returned pages
+     instead of pasting the text.
+   - You only need parts of it, now or later -> `tanuki_stash { text }`
+     (returns a ~300-token map + id), then `tanuki_fetch { id, query }` or
+     `{ id, lines: "a-b" }`. Big slices arrive as pages automatically.
+   - `"TEXT cheaper"` -> just use the text. Small inputs are not worth an
+     image even when the math technically favors one.
+3. **For noisy logs**, add `distill: true` (and `query: "regex"` for a
+   slice). Error/warn/fail lines survive verbatim; repeats become one
+   exemplar plus an exact xN count.
+4. **Shell commands with chatty output**: run them as
+   `tanuki-context run -- <cmd>` instead of reading the firehose. Exit code
+   passes through; the full capture is stashed and fetchable.
+
+## Reading the pages
+
+`↵` = original newline · `→` = tab · `⇥N` = N leading spaces · a trailing
+`·legend·` line maps codebook sigils back to full tokens · `[U+XXXX]` = a
+codepoint the atlas has no glyph for · `[×N similar]` = N near-identical
+lines collapsed here.
+
+## Do not
+
+- Do not image content whose exact bytes you must retype later (secrets,
+  hashes, code you are about to edit). Rendering is exact; model read-back
+  of dense hex is not guaranteed.
+- Do not use `font: "tiny"` or ladder levels 2-4 on anything you may need
+  to quote. Tiny is a 99.7%-read-back trade; levels 2-4 reword prose.
+- Do not use `withDistill` numbers on source code or docs you want intact -
+  distill collapses similar-looking lines.
+- Do not probe knob combinations by hand; `recommend` already priced them.