ashlr-plugin 1.36.4

package/docs/ashlr-pipe.md

@@ -0,0 +1,161 @@
+---
+name: ashlr-pipe
+description: Run a multi-step JS expression that calls grep/read/bash/ls/glob internally — intermediate results never enter context, only the return value does.
+---
+
+## Overview
+
+`ashlr__pipe` lets you run a JavaScript async expression that orchestrates multiple ashlr tool calls in a single round-trip. Intermediate results (grep output, file contents, bash stdout) are computed server-side and **never sent to the model context** — only the expression's final return value does. Typical savings: **80–95%** vs calling the same tools individually.
+
+### When to use it
+
+- You need to grep for a pattern, then filter/transform the results
+- You need to read several files and extract one fact from each
+- You need to bash-query something and do arithmetic on the result
+- Any pipeline where you'd otherwise burn context on large intermediate strings
+
+---
+
+## Security model & status
+
+**Status: EXPERIMENTAL.** `ashlr__pipe` executes model-authored JavaScript code server-side. It is **off by default** in all releases.
+
+### Flags
+
+| Flag | Effect |
+|---|---|
+| `ASHLR_PIPE_ENABLE=1` | Registers the tool. Required to use `ashlr__pipe` at all. |
+| `ASHLR_PIPE_ALLOW_BASH=1` | Adds `ctx.bash` to the expression context. Requires `ASHLR_PIPE_ENABLE=1`. |
+
+These are two separate, independent opt-ins. Enabling the pipe feature does **not** automatically expose shell access.
+
+### Default ctx — read-only tools only
+
+By default `ctx` exposes only non-mutating, non-shell tools:
+
+| Available by default | Requires `ASHLR_PIPE_ALLOW_BASH=1` |
+|---|---|
+| `ctx.grep`, `ctx.read`, `ctx.ls`, `ctx.glob` | `ctx.bash` |
+
+If an expression calls `ctx.bash` without the flag set it receives a clear error:
+```
+ctx.bash is disabled; set ASHLR_PIPE_ALLOW_BASH=1 to enable shell access in pipes
+```
+
+### Deny-list (best-effort)
+
+Before execution, the expression is checked against a deny-list of blocked tokens: `process`, `Bun`, `require`, `import(`, `globalThis`, `__proto__`, `constructor[`, `eval`, `Function(`, `setTimeout`, `setInterval`, `fetch(`. This is a best-effort guardrail, **not a true sandbox**. The AsyncFunction constructor prevents module-closure access; strict mode (`"use strict"` is prepended automatically) makes `this` undefined so token-splitting attacks (`this["pro"+"cess"]`) fail at runtime.
+
+### Rollout flag
+
+`ashlr__pipe` is **disabled by default**. Enable it per-session:
+
+```sh
+ASHLR_PIPE_ENABLE=1 claude
+```
+
+Or add it to your project's MCP environment config to enable permanently.
+
+---
+
+## Tool schema
+
+```
+ashlr__pipe(
+  expr:             string   — async function body, ≤2000 chars (required)
+  cwd?:             string   — working directory for tool calls
+  timeout_ms?:      number   — default 10000, hard max 30000
+  max_output_bytes? number   — default 4096 (truncates serialized return value)
+)
+```
+
+`expr` receives a single argument `ctx` with these async methods:
+
+| Method | Equivalent tool | Args |
+|---|---|---|
+| `ctx.grep(args)` | `ashlr__grep` | `{ pattern, cwd?, bypassSummary?, ... }` |
+| `ctx.read(args)` | `ashlr__read` | `{ path, bypassSummary? }` |
+| `ctx.bash(args)` | `ashlr__bash` | `{ command, cwd?, timeout_ms? }` |
+| `ctx.ls(args)` | `ashlr__ls` | `{ path? }` |
+| `ctx.glob(args)` | `ashlr__glob` | `{ pattern, cwd? }` |
+
+Each method returns the tool's text output as a plain string.
+
+### Security
+
+Before execution the expression is checked against a deny-list of blocked tokens:
+`process`, `Bun`, `require`, `import(`, `globalThis`, `__proto__`, `constructor[`, `eval`, `Function(`, `setTimeout`, `setInterval`, `fetch(`.
+
+The function is built with `AsyncFunction` (not `eval`) so module-level closures and `require` are inaccessible regardless of the deny-list.
+
+### Return value
+
+- The expression must `return` a value.
+- The return value is `JSON.stringify`-ed. Non-serializable values (circular refs, BigInt) return `"[non-serializable result]"`.
+- Output is truncated to `max_output_bytes` with a `[ashlr__pipe: output truncated]` marker.
+
+---
+
+## Worked examples
+
+### Example 1 — grep for TODOs, return file:line pairs
+
+Instead of calling `ashlr__grep` and getting back potentially thousands of lines, use `ashlr__pipe` to filter down to just the file:line pairs you care about:
+
+```json
+{
+  "expr": "const raw = await ctx.grep({ pattern: 'TODO', cwd: '.', bypassSummary: true }); const lines = raw.split('\\n').filter(l => l.includes(':')); return lines.slice(0, 20).map(l => l.split(':').slice(0,2).join(':'));"
+}
+```
+
+The model receives a compact JSON array of `["file.ts:42", ...]` — not the full grep output.
+
+### Example 2 — read several files and extract one fact each
+
+Read the `name` field from every `package.json` found via `ctx.glob` (no shell required):
+
+```json
+{
+  "expr": "const paths = (await ctx.glob({ pattern: '**/package.json', cwd: '.' })).split('\\n').filter(p => p && !p.includes('node_modules')).slice(0, 10); const names = []; for (const p of paths) { const content = await ctx.read({ path: p, bypassSummary: true }); try { const pkg = JSON.parse(content.split('\\n').slice(1).join('\\n')); if (pkg.name) names.push(pkg.name); } catch {} } return names;"
+}
+```
+
+Intermediate file contents (potentially hundreds of KB) stay on the server. The model receives only the `["name-a", "name-b", ...]` array.
+
+### Example 3 — shell access (requires `ASHLR_PIPE_ALLOW_BASH=1`)
+
+`ctx.bash` is only available when the additional opt-in flag is set:
+
+```sh
+ASHLR_PIPE_ENABLE=1 ASHLR_PIPE_ALLOW_BASH=1 claude
+```
+
+```json
+{
+  "expr": "const listing = await ctx.bash({ command: 'find . -name package.json -not -path */node_modules/* -maxdepth 4' }); const paths = listing.split('\\n').filter(p => p.endsWith('package.json')); const names = []; for (const p of paths.slice(0, 10)) { const content = await ctx.read({ path: p, bypassSummary: true }); try { const pkg = JSON.parse(content.split('\\n').slice(1).join('\\n')); if (pkg.name) names.push(pkg.name); } catch {} } return names;"
+}
+```
+
+Without the flag, `ctx.bash(...)` throws: `ctx.bash is disabled; set ASHLR_PIPE_ALLOW_BASH=1 to enable shell access in pipes`.
+
+---
+
+## Savings accounting
+
+`ashlr__pipe` records **one** aggregate saving at the end:
+- `rawBytes` = sum of all intermediate result lengths (what the model would have seen)
+- `compactBytes` = final output length (what the model actually sees)
+
+Intermediate calls are suppressed from the savings ledger so there is no double-counting.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `disallowed token "process"` | expr contains a blocked identifier | Rewrite without the blocked token |
+| `expr exceeds 2000 characters` | Expression too long | Split into a shorter pipeline or use bash to do more work |
+| `timed out after Nms` | Expression took longer than `timeout_ms` | Raise `timeout_ms` (max 30000) or simplify the pipeline |
+| Tool count jumps by 1 | Flag was set during smoke test | Unset `ASHLR_PIPE_ENABLE` before running `bun run smoke:tools` |
+| `ctx.bash is disabled` | `ASHLR_PIPE_ALLOW_BASH` not set | Set `ASHLR_PIPE_ALLOW_BASH=1` alongside `ASHLR_PIPE_ENABLE=1`, or rewrite expr using `ctx.glob`/`ctx.read` |

package/docs/assets/logo.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">
+  <defs>
+    <linearGradient id="pl-grad" x1="0" y1="0" x2="64" y2="64" gradientUnits="userSpaceOnUse">
+      <stop offset="0%" stop-color="#c2410c"/>
+      <stop offset="100%" stop-color="#8B2E1A"/>
+    </linearGradient>
+  </defs>
+  <rect width="64" height="64" rx="14" fill="#1a0f0c"/>
+  <rect x="1" y="1" width="62" height="62" rx="13" fill="none" stroke="url(#pl-grad)" stroke-opacity="0.25" stroke-width="1.5"/>
+  <!-- Ledger lines -->
+  <line x1="14" y1="22" x2="50" y2="22" stroke="url(#pl-grad)" stroke-opacity="0.4" stroke-width="1"/>
+  <line x1="14" y1="32" x2="50" y2="32" stroke="url(#pl-grad)" stroke-opacity="0.5" stroke-width="1"/>
+  <line x1="14" y1="42" x2="50" y2="42" stroke="url(#pl-grad)" stroke-opacity="0.6" stroke-width="1"/>
+  <!-- Brand square -->
+  <rect x="14" y="14" width="10" height="10" fill="url(#pl-grad)"/>
+  <!-- Row marks -->
+  <circle cx="46" cy="32" r="2.5" fill="url(#pl-grad)"/>
+  <circle cx="46" cy="42" r="2.5" fill="url(#pl-grad)" opacity="0.7"/>
+</svg>

package/docs/assets/og.svg

@@ -0,0 +1,41 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630">
+  <defs>
+    <filter id="noise" x="0" y="0" width="100%" height="100%">
+      <feTurbulence baseFrequency="0.9" numOctaves="3" stitchTiles="stitch" />
+      <feColorMatrix values="0 0 0 0 0.05  0 0 0 0 0.05  0 0 0 0 0.05  0 0 0 0.06 0" />
+    </filter>
+    <style>
+      @import url("https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,300;9..144,400&amp;family=JetBrains+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@500&amp;display=swap");
+    </style>
+  </defs>
+
+  <!-- Parchment background -->
+  <rect width="1200" height="630" fill="#F3EADB" />
+
+  <!-- Paper grain overlay -->
+  <rect width="1200" height="630" filter="url(#noise)" opacity="0.6" />
+
+  <!-- Brand mark -->
+  <rect x="80" y="80" width="14" height="14" fill="#8B2E1A" />
+  <text x="108" y="96" font-family="Fraunces, serif" font-size="32" fill="#121212" font-weight="400">ashlr</text>
+
+  <!-- Top-right meta -->
+  <text x="1120" y="96" font-family="JetBrains Mono, monospace" font-size="14" fill="#121212" opacity="0.55" text-anchor="end" letter-spacing="1.5">v0.1.0 · MIT</text>
+
+  <!-- Eyebrow -->
+  <line x1="80" y1="200" x2="140" y2="200" stroke="#8B2E1A" stroke-width="2" />
+  <text x="160" y="205" font-family="JetBrains Mono, monospace" font-size="14" fill="#8B2E1A" letter-spacing="3" font-weight="500">THE TOKEN LEDGER</text>
+
+  <!-- Headline -->
+  <text x="80" y="310" font-family="Fraunces, serif" font-size="104" fill="#121212" font-weight="300" letter-spacing="-3">Every tool call,</text>
+  <text x="80" y="420" font-family="Fraunces, serif" font-style="italic" font-size="104" fill="#8B2E1A" font-weight="300" letter-spacing="-3">line-itemized.</text>
+
+  <!-- Sub -->
+  <text x="80" y="490" font-family="IBM Plex Sans, sans-serif" font-size="24" fill="#121212" opacity="0.8" font-weight="400">Open-source Codex + Claude Code plugin — token-efficient Read, Grep, Edit.</text>
+  <text x="80" y="524" font-family="IBM Plex Sans, sans-serif" font-size="24" fill="#121212" opacity="0.55">Mean −57% savings across reference repos.</text>
+
+  <!-- Bottom strip: install commands -->
+  <line x1="80" y1="570" x2="1120" y2="570" stroke="#121212" stroke-opacity="0.15" stroke-width="1" />
+  <text x="80" y="600" font-family="JetBrains Mono, monospace" font-size="16" fill="#121212">/plugin marketplace add ashlrai/ashlr-plugin</text>
+  <text x="1120" y="600" font-family="JetBrains Mono, monospace" font-size="14" fill="#8B2E1A" text-anchor="end" letter-spacing="1.5">plugin.ashlr.ai</text>
+</svg>

package/docs/benchmarks-v2.json

@@ -0,0 +1,355 @@
+{
+  "version": 2,
+  "measuredAt": "2026-04-26T03:27:38.258Z",
+  "repo": {
+    "url": "https://github.com/ashlrai/ashlr-plugin.git",
+    "commit": "b98da9c6d38a27ee35a1b9d95d9b8b99ddbc58d4",
+    "files": 750,
+    "loc": 149462
+  },
+  "samples": {
+    "ashlr__read": [
+      {
+        "path": "/Users/masonwyatt/Desktop/ashlr-plugin/vscode/src/extension.ts",
+        "bucket": "2-5KB",
+        "rawBytes": 3472,
+        "rawTokens": 867,
+        "ashlrBytes": 1629,
+        "ashlrTokens": 406,
+        "ratio": 0.4682814302191465
+      },
+      {
+        "path": "/Users/masonwyatt/Desktop/ashlr-plugin/bench/fixtures/tasklist-sprint-open.json",
+        "bucket": "2-5KB",
+        "rawBytes": 3265,
+        "rawTokens": 817,
+        "ashlrBytes": 1623,
+        "ashlrTokens": 406,
+        "ratio": 0.4969400244798042
+      },
+      {
+        "path": "/Users/masonwyatt/Desktop/ashlr-plugin/site/components/bits/DecryptedText.tsx",
+        "bucket": "2-5KB",
+        "rawBytes": 4079,
+        "rawTokens": 1020,
+        "ashlrBytes": 1625,
+        "ashlrTokens": 406,
+        "ratio": 0.3980392156862745
+      },
+      {
+        "path": "/Users/masonwyatt/Desktop/ashlr-plugin/video/src/compositions/DashboardFrame.tsx",
+        "bucket": "2-5KB",
+        "rawBytes": 4213,
+        "rawTokens": 1051,
+        "ashlrBytes": 1629,
+        "ashlrTokens": 406,
+        "ratio": 0.38629876308277833
+      },
+      {
+        "path": "/Users/masonwyatt/Desktop/ashlr-plugin/site/app/dpa/page.tsx",
+        "bucket": "5-15KB",
+        "rawBytes": 13288,
+        "rawTokens": 3321,
+        "ashlrBytes": 1625,
+        "ashlrTokens": 406,
+        "ratio": 0.12225233363444746
+      },
+      {
+        "path": "/Users/masonwyatt/Desktop/ashlr-plugin/servers/_genome-crypto-v2.ts",
+        "bucket": "5-15KB",
+        "rawBytes": 9269,
+        "rawTokens": 2313,
+        "ashlrBytes": 1627,
+        "ashlrTokens": 406,
+        "ratio": 0.17552961521833116
+      },
+      {
+        "path": "/Users/masonwyatt/Desktop/ashlr-plugin/__tests__/_summarize.test.ts",
+        "bucket": "5-15KB",
+        "rawBytes": 7868,
+        "rawTokens": 1967,
+        "ashlrBytes": 1623,
+        "ashlrTokens": 406,
+        "ratio": 0.20640569395017794
+      },
+      {
+        "path": "/Users/masonwyatt/Desktop/ashlr-plugin/__tests__/hook-timings-async.test.ts",
+        "bucket": "5-15KB",
+        "rawBytes": 5678,
+        "rawTokens": 1416,
+        "ashlrBytes": 1629,
+        "ashlrTokens": 406,
+        "ratio": 0.2867231638418079
+      },
+      {
+        "path": "/Users/masonwyatt/Desktop/ashlr-plugin/servers/_test-parsers.ts",
+        "bucket": "15-50KB",
+        "rawBytes": 19213,
+        "rawTokens": 4780,
+        "ashlrBytes": 1625,
+        "ashlrTokens": 406,
+        "ratio": 0.08493723849372385
+      },
+      {
+        "path": "/Users/masonwyatt/Desktop/ashlr-plugin/scripts/genome-auto-consolidate.ts",
+        "bucket": "15-50KB",
+        "rawBytes": 18644,
+        "rawTokens": 4652,
+        "ashlrBytes": 1631,
+        "ashlrTokens": 406,
+        "ratio": 0.08727429062768702
+      },
+      {
+        "path": "/Users/masonwyatt/Desktop/ashlr-plugin/scripts/savings-dashboard.ts",
+        "bucket": "15-50KB",
+        "rawBytes": 41965,
+        "rawTokens": 10410,
+        "ashlrBytes": 1627,
+        "ashlrTokens": 406,
+        "ratio": 0.03900096061479347
+      },
+      {
+        "path": "/Users/masonwyatt/Desktop/ashlr-plugin/__tests__/embedding-cache.test.ts",
+        "bucket": "15-50KB",
+        "rawBytes": 20709,
+        "rawTokens": 5171,
+        "ashlrBytes": 1623,
+        "ashlrTokens": 406,
+        "ratio": 0.07851479404370527
+      },
+      {
+        "path": "/Users/masonwyatt/Desktop/ashlr-plugin/CHANGELOG.md",
+        "bucket": "50+KB",
+        "rawBytes": 160910,
+        "rawTokens": 39889,
+        "ashlrBytes": 1640,
+        "ashlrTokens": 406,
+        "ratio": 0.010178244628845045
+      },
+      {
+        "path": "/Users/masonwyatt/Desktop/ashlr-plugin/.ashlrcode/genome/knowledge/discoveries-auto.md",
+        "bucket": "50+KB",
+        "rawBytes": 232920,
+        "rawTokens": 57674,
+        "ashlrBytes": 1633,
+        "ashlrTokens": 406,
+        "ratio": 0.0070395672226653255
+      },
+      {
+        "path": "/Users/masonwyatt/Desktop/ashlr-plugin/server/src/db.ts",
+        "bucket": "50+KB",
+        "rawBytes": 87630,
+        "rawTokens": 21889,
+        "ashlrBytes": 1627,
+        "ashlrTokens": 406,
+        "ratio": 0.01854812919731372
+      },
+      {
+        "path": "/Users/masonwyatt/Desktop/ashlr-plugin/site/tsconfig.tsbuildinfo",
+        "bucket": "50+KB",
+        "rawBytes": 381765,
+        "rawTokens": 95442,
+        "ashlrBytes": 1623,
+        "ashlrTokens": 406,
+        "ratio": 0.004253892416336624
+      }
+    ],
+    "ashlr__grep": [
+      {
+        "pattern": "function ",
+        "rawBytes": 850335,
+        "rawTokens": 212573,
+        "ashlrBytes": 3023,
+        "ashlrTokens": 756,
+        "ratio": 0.003556425322124635,
+        "method": "rg-truncated"
+      },
+      {
+        "pattern": "import ",
+        "rawBytes": 846065,
+        "rawTokens": 211503,
+        "ashlrBytes": 3023,
+        "ashlrTokens": 756,
+        "ratio": 0.0035744173841505793,
+        "method": "rg-truncated"
+      },
+      {
+        "pattern": "TODO",
+        "rawBytes": 12761,
+        "rawTokens": 3184,
+        "ashlrBytes": 3025,
+        "ashlrTokens": 756,
+        "ratio": 0.23743718592964824,
+        "method": "rg-truncated"
+      },
+      {
+        "pattern": "class ",
+        "rawBytes": 30112,
+        "rawTokens": 7524,
+        "ashlrBytes": 3025,
+        "ashlrTokens": 756,
+        "ratio": 0.10047846889952153,
+        "method": "rg-truncated"
+      },
+      {
+        "pattern": "interface ",
+        "rawBytes": 219322,
+        "rawTokens": 54830,
+        "ashlrBytes": 3023,
+        "ashlrTokens": 756,
+        "ratio": 0.013788072223235455,
+        "method": "rg-truncated"
+      }
+    ],
+    "ashlr__edit": [
+      {
+        "size": "small",
+        "searchChars": 15,
+        "replaceChars": 15,
+        "naiveBytes": 47,
+        "naiveTokens": 12,
+        "ashlrBytes": 121,
+        "ashlrTokens": 30,
+        "ratio": 2.5
+      },
+      {
+        "size": "medium",
+        "searchChars": 184,
+        "replaceChars": 206,
+        "naiveBytes": 407,
+        "naiveTokens": 102,
+        "ashlrBytes": 201,
+        "ashlrTokens": 49,
+        "ratio": 0.4803921568627451
+      },
+      {
+        "size": "large",
+        "searchChars": 2243,
+        "replaceChars": 2383,
+        "naiveBytes": 4643,
+        "naiveTokens": 1161,
+        "ashlrBytes": 167,
+        "ashlrTokens": 41,
+        "ratio": 0.03531438415159346
+      }
+    ]
+  },
+  "aggregate": {
+    "ashlr__read": {
+      "mean": 0.17938858483486492,
+      "p50": 0.12225233363444746,
+      "p90": 0.4682814302191465
+    },
+    "ashlr__grep": {
+      "mean": 0.0717669139517361,
+      "p50": 0.013788072223235455,
+      "p90": 0.23743718592964824
+    },
+    "ashlr__edit": {
+      "mean": 1.0052355136714461,
+      "p50": 0.4803921568627451,
+      "p90": 2.5
+    },
+    "overall": {
+      "mean": 0.26019826950545244
+    }
+  },
+  "methodology": "Measurement methodology (version 2):\n\n**ashlr__read**: For each sampled source file, we measure raw file bytes and\ntoken count (chars/4 heuristic). We then apply the same snipCompact\ntransformation used at runtime — wrapping the content in a tool_result message\nand calling snipCompact() — and measure the resulting byte/token count. The\nratio is ashlrTokens / rawTokens. Files below 2 KB are excluded because\nsnipCompact only fires on tool results > 2 000 chars; savings are zero by\ndesign for small files.\n\nFiles are selected deterministically: the repo HEAD commit SHA is folded into a\n32-bit seed (mulberry32 PRNG), then up to 4 files are sampled from each of four\nsize buckets (2–5 KB, 5–15 KB, 15–50 KB, 50+ KB). Re-running on the same\ncommit always picks the same files.\n\n**ashlr__grep**: Five common patterns (function, import, TODO, class, interface)\nare run via rg --json against the repo root. Raw output bytes are measured\ndirectly. The ashlr__grep fallback path (no genome) truncates output to 4 000\nchars (head 2 000 + tail 1 000). The ratio is truncated/raw.\n\nNote: when a .ashlrcode/genome/ index is present, real-world grep savings are\nsubstantially higher. This benchmark measures only the conservative\nno-genome baseline.\n\n**ashlr__edit**: Three synthetic edits (small ~15 chars, medium ~300 chars,\nlarge ~3 000 chars) compare the naive \"ship before+after as text\" approach\nagainst ashlr__edit's diff-summary format (one header line + removed/added\nfirst-lines). The ratio is summary tokens / naive tokens.\n\n**Aggregation**: per-tool mean/p50/p90 are computed over each tool's ratio\nvalues (lower ratio = more savings). The `overall.mean` is pooled across\nevery individual sample regardless of tool — so tools with more samples (read\nhas 15, grep has 5, edit has 3) weight the overall figure proportionally.\nThat makes the headline number reflect the workload mix, not a uniform\nper-tool average. The unweighted mean of per-tool means is intentionally NOT\npublished because it gives equal weight to a 3-sample tool and a 15-sample\ntool, which over-weights the synthetic edit overhead.\n\nToken counts use the chars/4 heuristic, the same estimator the plugin uses at\nruntime for savings accounting.",
+  "crossLanguageMeasuredAt": "2026-05-23T00:07:25.178Z",
+  "byRepo": {
+    "node-sdk": {
+      "repoKey": "node-sdk",
+      "language": "ts",
+      "upstreamRepo": "github.com/vercel/ai",
+      "refrev": "049801243cc791e0ba28910b8a638f0e05446bcd",
+      "meanRatio": 0.3866451136118328,
+      "savingsPct": 61.33548863881673,
+      "perTool": {
+        "read": {
+          "mean": 0.25972488616679845,
+          "p50": 0.2283464566929134,
+          "p90": 0.5638888888888889
+        },
+        "grep": {
+          "mean": 0.32009941944414705,
+          "p50": 0.2968197879858657,
+          "p90": 0.6948529411764706
+        },
+        "edit": {
+          "mean": 1.0052355136714461,
+          "p50": 0.4803921568627451,
+          "p90": 2.5
+        }
+      }
+    },
+    "python-lib": {
+      "repoKey": "python-lib",
+      "language": "py",
+      "upstreamRepo": "github.com/pandas-dev/pandas",
+      "refrev": "be0642f7cb8900282a43b53cd50cf00a05161ed6",
+      "meanRatio": 0.3688098954558492,
+      "savingsPct": 63.11901045441508,
+      "perTool": {
+        "read": {
+          "mean": 0.2429002666026248,
+          "p50": 0.230028328611898,
+          "p90": 0.56
+        },
+        "grep": {
+          "mean": 0.31431955954487434,
+          "p50": 0.20454545454545456,
+          "p90": 1
+        },
+        "edit": {
+          "mean": 1.0052355136714461,
+          "p50": 0.4803921568627451,
+          "p90": 2.5
+        }
+      }
+    },
+    "rust-project": {
+      "repoKey": "rust-project",
+      "language": "rs",
+      "upstreamRepo": "github.com/tokio-rs/tokio",
+      "refrev": "6c03e03898d71eca976ee1ad8481cf112ae722ba",
+      "meanRatio": 0.532296183969948,
+      "savingsPct": 46.7703816030052,
+      "perTool": {
+        "read": {
+          "mean": 0.24330862010197613,
+          "p50": 0.2088477366255144,
+          "p90": 0.4608399545970488
+        },
+        "grep": {
+          "mean": 0.826507713884993,
+          "p50": 1,
+          "p90": 1
+        },
+        "edit": {
+          "mean": 1.0052355136714461,
+          "p50": 0.4803921568627451,
+          "p90": 2.5
+        }
+      }
+    }
+  },
+  "byLanguage": {
+    "ts": {
+      "language": "ts",
+      "meanRatio": 0.3866451136118328,
+      "savingsPct": 61.33548863881673
+    },
+    "py": {
+      "language": "py",
+      "meanRatio": 0.3688098954558492,
+      "savingsPct": 63.11901045441508
+    },
+    "rs": {
+      "language": "rs",
+      "meanRatio": 0.532296183969948,
+      "savingsPct": 46.7703816030052
+    }
+  },
+  "crossLanguageMean": 0.42925039767920997,
+  "crossLanguageSavingsPct": 57.07496023207901
+}

package/docs/benchmarks.json

@@ -0,0 +1,102 @@
+{
+  "generatedAt": "2026-04-15",
+  "method": "snipCompact via @ashlr/core-efficiency on each file; chars/4 token estimate",
+  "note": "Files below 2KB see 0% savings by design \u2014 snipCompact only fires on tool-results > 2000 chars. This is honest: there's nothing to trim on a small file.",
+  "reproducible": "legacy snapshot; use docs/benchmarks-v2.json and bun run scripts/run-benchmark.ts for current methodology",
+  "rows": [
+    {
+      "path": "src/compression/priority.ts",
+      "loc": 22,
+      "kb": 0.5,
+      "rawTokens": 117,
+      "ashlrTokens": 117,
+      "savedPct": 0
+    },
+    {
+      "path": "src/genome/jsonl.ts",
+      "loc": 42,
+      "kb": 1.2,
+      "rawTokens": 305,
+      "ashlrTokens": 305,
+      "savedPct": 0
+    },
+    {
+      "path": "src/tokens/index.ts",
+      "loc": 51,
+      "kb": 1.5,
+      "rawTokens": 372,
+      "ashlrTokens": 372,
+      "savedPct": 0
+    },
+    {
+      "path": "src/budget/index.ts",
+      "loc": 56,
+      "kb": 1.9,
+      "rawTokens": 491,
+      "ashlrTokens": 491,
+      "savedPct": 0
+    },
+    {
+      "path": "src/types/index.ts",
+      "loc": 68,
+      "kb": 1.9,
+      "rawTokens": 484,
+      "ashlrTokens": 484,
+      "savedPct": 0
+    },
+    {
+      "path": "src/compression/context.ts",
+      "loc": 186,
+      "kb": 5.9,
+      "rawTokens": 1517,
+      "ashlrTokens": 406,
+      "savedPct": 73.2
+    },
+    {
+      "path": "src/genome/manifest.ts",
+      "loc": 238,
+      "kb": 7.0,
+      "rawTokens": 1802,
+      "ashlrTokens": 406,
+      "savedPct": 77.5
+    },
+    {
+      "path": "src/genome/retriever.ts",
+      "loc": 259,
+      "kb": 7.8,
+      "rawTokens": 2001,
+      "ashlrTokens": 406,
+      "savedPct": 79.7
+    },
+    {
+      "path": "src/genome/fitness.ts",
+      "loc": 241,
+      "kb": 7.8,
+      "rawTokens": 2009,
+      "ashlrTokens": 406,
+      "savedPct": 79.8
+    },
+    {
+      "path": "src/genome/scribe.ts",
+      "loc": 276,
+      "kb": 8.3,
+      "rawTokens": 2131,
+      "ashlrTokens": 406,
+      "savedPct": 80.9
+    },
+    {
+      "path": "src/genome/generations.ts",
+      "loc": 331,
+      "kb": 11.2,
+      "rawTokens": 2878,
+      "ashlrTokens": 406,
+      "savedPct": 85.9
+    }
+  ],
+  "summary": {
+    "smallFiles (<2KB)": 5,
+    "mediumFiles (2-10KB)": 5,
+    "largeFiles (\u226510KB)": 1,
+    "avgSavingsLargeFiles": 79.5
+  }
+}