Skip to content
Back to search

winnow

A calibrated context sieve for Claude Code: every tool result is judged by a System One model before it enters context.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ghalebdweikat--winnow/badge.svg)](/listings/ghalebdweikat--winnow)

HTML

<a href="/listings/ghalebdweikat--winnow"><img src="/api/listings/ghalebdweikat--winnow/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requirements: Python 3.10+, [uv](https://docs.astral.sh/uv/), Claude Code 2.1.260 or newer with function hooks enabled (early access; one line in settings, below).

First turn on function hooks in `~/.claude/settings.json` (winnow does nothing without this, and `winnow doctor` checks it):

{ "env": { "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1" } }

Then install:

git clone https://github.com/GhalebDweikat/winnow.git
claude plugin marketplace add ./winnow
claude plugin install winnow@winnow

Then add a key (next section), open a new Claude Code session, and read any file longer than about 1,500 characters. If a `[winnow]` line appears in the result, it's working. If not, see [Troubleshooting](#troubleshooting).

Before you have any key, you can still see what it does:

uv run --project winnow/sidecar winnow demo --fake

That runs a synthetic 130-line file through the real pipeline with a keyword judge and prints what Claude would have seen. Once a key is set, drop `--fake` and the same command makes the first real judge call.

The repo is its own plugin marketplace, so it also installs straight from GitHub without cloning:

claude plugin marketplace add GhalebDweikat/winnow
claude plugin install winnow@winnow

GitHub shorthand clones over SSH by default; set `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1` if you don't have an SSH key on this machine.

Installing applies everywhere that shares your `~/.claude` config: the CLI, the desktop app, and IDE extensions. New sessions pick the plugin up; running sessions don't. The first session after install syncs the sidecar's environment and starts the resident server, which takes a few seconds once; after that, sessions share the running server and start instantly.

Installed plugins are copied to `~/.claude/plugins/cache/`, not linked, so after pulling changes run `claude plugin update winnow@winnow`. For a hot-reload loop while developing, load the checkout for one session instead:

claude --plugin-dir ./winnow

To scope the plugin to one project rather than your whole account, add `--scope project` to the `marketplace add` command.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 22 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "winnow",
  3. "description": "winnow: a calibrated context sieve for Claude Code.",
  4. "owner": {
  5. "name": "Ghaleb Dweikat",
  6. "email": "ghalebdweikat@gmail.com",
  7. "url": "https://github.com/GhalebDweikat"
  8. },
  9. "plugins": [
  10. {
  11. "name": "winnow",
  12. "source": "./",
  13. "description": "Every large Read, Bash, or Grep result is judged by a System One model before it enters context. Irrelevant blocks are replaced with a summary and a recall key.",
  14. "version": "0.5.2",
  15. "author": {
  16. "name": "Ghaleb Dweikat"
  17. },
  18. "category": "productivity",
  19. "tags": ["context", "typesafe", "jev", "system-one", "hooks"]
  20. }
  21. ]
  22. }
README.md · README · 386 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # winnow
  2. [![tests](https://github.com/GhalebDweikat/winnow/actions/workflows/tests.yml/badge.svg)](https://github.com/GhalebDweikat/winnow/actions/workflows/tests.yml)
  3. A calibrated context sieve for Claude Code.
  4. Every large `Read`, `Bash`, or `Grep` result is judged before it enters Claude's context. Blocks the judge is confident you don't need are replaced with a three-line stub: what was hidden, a one-paragraph summary from a cheap model, and a key that restores the full text on demand. Nothing is lost; it just stops costing tokens until you ask for it.
  5. **Terms used below.** The *judge* is the model that answers one yes/no question per block ("is this block needed for the current task?") with a probability. By default that is **Jev**, TypeSafe AI's *System One* model: a model that returns calibrated probabilities for typed questions instead of generating text, so a hundred questions come back in one call in a few hundred milliseconds. Jev is in early access. The *adapter* is TypeSafe's `system-one-adapter` package, which answers the same questions by prompting Claude Haiku 4.5; it is not calibrated, but it lets the whole pipeline run today.
  6. ## What it does
  7. ```
  8. Read big.py ──► Claude Code ──► tool.call hook ──► winnow
  9. │
  10. split into ~25-line blocks ◄─────────────────────────┘
  11. one call to the judge: "is block N needed for the current task?" ×N, in parallel
  12. keep confident-yes and uncertain blocks verbatim
  13. hide confident-no blocks: cache full text ─► summarize ─► stub
  14. │
  15. Claude sees ◄── { result } ◄───────────────────────────────┘
  16. ```
  17. A stub looks like this:
  18. ```
  19. [winnow] Lines 41-188 (148 lines) hidden: judged unlikely to matter for the current task (relevance <= 0.22).
  20. [winnow] Summary: Argparse setup for the --export and --format flags, plus the license header.
  21. [winnow] Full text cached as key a1b2c3d4e5f6. Call winnow_recall(key="a1b2c3d4e5f6", start=41, end=188) if you need it.
  22. ```
  23. Without a summarizer the middle line is a deterministic digest instead, so Claude still knows what kind of thing it lost: for a search result, which files the hidden matches came from and how many each; for anything else, the line count, whether it was mostly comments, imports or repetition, and the first line.
  24. Two safety rules are built in. If the judge thinks the output shows an error, nothing is hidden. If a block's probability is merely uncertain (between `WINNOW_DROP` and `WINNOW_KEEP`), it is kept. Both thresholds are tunable; the rules themselves are not optional. The default `WINNOW_DROP` of 0.1 is the bin that came back clean on hand-labeled replay (see [Measured](#measured)); raise it only with your own evidence.
  25. The hook is a function-hook module (see [How it hooks in](#how-it-hooks-in)) that talks to a small resident server (`winnow serve`) on loopback, started at session start, so a judged call costs about 16 ms plus the judge call rather than a Python startup. winnow never judges its own files or its own commands, so recalls and labeling sheets always come back whole.
  26. A second hook runs at prompt time. It ranks the memory files Claude Code keeps for the project (`~/.claude/projects/<project>/memory/*.md`, everything except the `MEMORY.md` index, which Claude already loads) plus any directories in `WINNOW_CONTEXT_DIRS` against your prompt, and injects the relevant ones so Claude reads what it needs without a round of `Read` calls.
  27. What winnow changes is only what Claude sees. Files on disk, the commands that ran, and Claude Code's own transcript are untouched.
  28. ## Quick start
  29. Requirements: Python 3.10+, [uv](https://docs.astral.sh/uv/), Claude Code 2.1.260 or newer with function hooks enabled (early access; one line in settings, below).
  30. First turn on function hooks in `~/.claude/settings.json` (winnow does nothing without this, and `winnow doctor` checks it):
  31. ```json
  32. { "env": { "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1" } }
  33. ```
  34. Then install:
  35. ```bash
  36. git clone https://github.com/GhalebDweikat/winnow.git
  37. claude plugin marketplace add ./winnow
  38. claude plugin install winnow@winnow
  39. ```
  40. Then add a key (next section), open a new Claude Code session, and read any file longer than about 1,500 characters. If a `[winnow]` line appears in the result, it's working. If not, see [Troubleshooting](#troubleshooting).
  41. Before you have any key, you can still see what it does:
  42. ```bash
  43. uv run --project winnow/sidecar winnow demo --fake
  44. ```
  45. That runs a synthetic 130-line file through the real pipeline with a keyword judge and prints what Claude would have seen. Once a key is set, drop `--fake` and the same command makes the first real judge call.
  46. The repo is its own plugin marketplace, so it also installs straight from GitHub without cloning:
  47. ```bash
  48. claude plugin marketplace add GhalebDweikat/winnow
  49. claude plugin install winnow@winnow
  50. ```
  51. GitHub shorthand clones over SSH by default; set `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1` if you don't have an SSH key on this machine.
  52. Installing applies everywhere that shares your `~/.claude` config: the CLI, the desktop app, and IDE extensions. New sessions pick the plugin up; running sessions don't. The first session after install syncs the sidecar's environment and starts the resident server, which takes a few seconds once; after that, sessions share the running server and start instantly.
  53. Installed plugins are copied to `~/.claude/plugins/cache/`, not linked, so after pulling changes run `claude plugin update winnow@winnow`. For a hot-reload loop while developing, load the checkout for one session instead:
  54. ```bash
  55. claude --plugin-dir ./winnow
  56. ```
  57. To scope the plugin to one project rather than your whole account, add `--scope project` to the `marketplace add` command.
  58. ## Add your keys
  59. winnow needs one key for the judge and, optionally, one for summaries. Nothing runs until at least the judge key is in place; until then every hook passes results through untouched and, once per session, tells you so.
  60. **1. Get a Jev key.** Jev is in early access. Join the waitlist at [typesafe.ai](https://typesafe.ai), and once you're admitted create a key at [console.typesafe.ai/settings/keys](https://console.typesafe.ai/settings/keys). No key yet? Skip to step 3.
  61. **2. Put the keys where hooks can see them.** A hook runs with the environment of whatever launched Claude Code. A key exported in one terminal is invisible to the desktop app and to IDE sessions. Either of these works everywhere:
  62. - A file at `~/.winnow/env` (on Windows, `%USERPROFILE%\.winnow\env`), one `KEY=VALUE` per line. winnow reads it on every hook call. Keep it private; it is outside the repo.
  63. ```
  64. TYPESAFE_API_KEY=ts-...
  65. ANTHROPIC_API_KEY=sk-ant-...
  66. ```
  67. - Or the `env` block of `~/.claude/settings.json`, which Claude Code applies to every session and every subprocess it starts:
  68. ```json
  69. { "env": { "TYPESAFE_API_KEY": "ts-...", "ANTHROPIC_API_KEY": "sk-ant-..." } }
  70. ```
  71. A variable already in the environment wins over the file, so a plain shell export still works for CLI use.
  72. **3. No Jev key yet? Use the adapter.** Add `WINNOW_JUDGE=adapter` to the same file. The adapter sends the identical request to Claude Haiku 4.5 through your Anthropic credentials (`ANTHROPIC_API_KEY`, or a profile from the `ant` CLI's `ant auth login`). Its probabilities are not calibrated, but the whole pipeline works, and switching to Jev later is one line. This path bills your Anthropic account; see [cost](#what-leaves-your-machine-and-what-it-costs).
  73. **4. Verify.**
  74. ```bash
  75. uv run --project winnow/sidecar winnow doctor
  76. ```
  77. It prints which keys were found, where they came from, and whether each backend initializes. Then `winnow demo` (without `--fake`) makes one real judge call and shows the result.
  78. Summaries use the Anthropic credentials. Set `WINNOW_SUMMARY=0` to turn them off; stubs then say "Summary unavailable" and everything else still works.
  79. ### Running `winnow` commands
  80. From the clone, every command is `uv run --project winnow/sidecar winnow <command>`. To have `winnow` on your PATH anywhere:
  81. ```bash
  82. uv tool install ./winnow/sidecar
  83. winnow doctor
  84. ```
  85. Commands: `doctor`, `demo [--fake]`, `stats`, `recall <key> [--start N --end M]`, `replay {extract,judge,score,run,sample,label,import-labels,agreement}`, `serve [--ensure|--status|--stop]`, `bench [--http]`, `clean`, `mcp`, `hook <event>`.
  86. ## What leaves your machine, and what it costs
  87. winnow's job is reading everything Claude reads, so be clear about where it goes.
  88. | Data | Sent to | When |
  89. |---|---|---|
  90. | The tool output being judged, in blocks, plus a short task description from the transcript (last user request, last assistant sentence) and the tool's arguments | TypeSafe (judge `typesafe`) or Anthropic (judge `adapter`) | every judged result over `WINNOW_MIN_CHARS` |
  91. | The hidden blocks only | Anthropic | when summaries are on and something was hidden |
  92. | Your prompt and the first 600 characters of each candidate memory file | the judge | every prompt, when candidate files exist |
  93. Nothing is sent when the judge is `off`, and nothing is sent for outputs under the size threshold. The full text of every hidden output is kept locally in `~/.winnow/cache/` for recall; there is no eviction yet, so clear it when you like.
  94. Approximate cost per judged result, for a 10,000-token output:
  95. | Judge | Judge call | Summaries (up to 4, Haiku 4.5) | Total |
  96. |---|---|---|---|
  97. | Jev at $0.042 per million input tokens | $0.0004 | about $0.005 | under a cent |
  98. | Adapter on Haiku 4.5 at $1 per million input tokens | about $0.01 | about $0.005 | a few cents |
  99. `winnow stats` reports the judge's actual token usage and cost after the fact.
  100. ## Configuration
  101. All settings are environment variables (or lines in `~/.winnow/env`). Defaults are deliberately conservative.
  102. | Variable | Default | Meaning |
  103. |---|---|---|
  104. | `WINNOW_MODE` | `active` | `active` rewrites tool results; `shadow` judges and logs only |
  105. | `WINNOW_JUDGE` | `typesafe` | `typesafe`, `adapter`, or `off` |
  106. | `WINNOW_MODEL` | `jev-latest` | Jev model id |
  107. | `WINNOW_JUDGE_TIMEOUT` | `15` | Seconds per judge call, including one retry |
  108. | `WINNOW_ADAPTER_PROVIDER` | `anthropic` | Provider behind the adapter (`anthropic` or `openai`) |
  109. | `WINNOW_ADAPTER_MODEL` | `claude-haiku-4-5` | Model behind the adapter |
  110. | `WINNOW_TOOLS` | `Read,Bash,Grep` | Tools whose output is judged. This can only narrow the set; the module wraps the tools listed in `TOOLS` in `hooks/winnow.ts`, so to add a tool edit that list too |
  111. | `WINNOW_QUESTIONS` | `structured` | Question set the judge is asked with: `structured`, `default`, or `strict` |
  112. | `WINNOW_EXCLUDE_PATHS` | `WINNOW_HOME` | Reads under these directories are never judged (path-separator delimited) |
  113. | `WINNOW_EXCLUDE_COMMANDS` | `\bwinnow\b` | Bash commands matching this regex are never judged |
  114. | `WINNOW_PORT` | `47311` | Sidecar port; `PORT` in `hooks/winnow.ts` must match |
  115. | `WINNOW_MIN_CHARS` | `1500` | Outputs shorter than this are never touched |
  116. | `WINNOW_DROP` | `0.1` | Hide a block only when P(needed) is below this |
  117. | `WINNOW_KEEP` | `0.5` | Error-gate threshold; also the line between "confident keep" and "uncertain keep" |
  118. | `WINNOW_MIN_PRUNE_RATIO` | `0.2` | Skip the rewrite unless at least this fraction of the text would be hidden |
  119. | `WINNOW_BLOCK_LINES` | `25` | Target lines per block |
  120. | `WINNOW_MAX_BLOCKS` | `200` | Cap on questions per call; block size grows to fit |
  121. | `WINNOW_MAX_STATE_CHARS` | `120000` | Blocks beyond this budget are kept unjudged |
  122. | `WINNOW_SUMMARY` | `1` | Summarize hidden groups |
  123. | `WINNOW_SUMMARY_MODEL` | `claude-haiku-4-5` | Summarizer model |
  124. | `WINNOW_SUMMARY_MAX_GROUPS` | `4` | Summarize at most this many hidden groups per result; the rest get "Summary unavailable" |
  125. | `WINNOW_SUMMARY_MAX_CHARS` | `20000` | Characters of a hidden group sent to the summarizer |
  126. | `WINNOW_CONTEXT_DIRS` | | Extra directories of `.md` files for the prompt-time selector. Path-separator delimited: `:` on macOS and Linux, `;` on Windows |
  127. | `WINNOW_CONTEXT_GATE` | `0.5` | Minimum P(relevant) to inject a file |
  128. | `WINNOW_CONTEXT_TOP_K` | `3` | Max files injected per prompt |
  129. | `WINNOW_CONTEXT_MAX_CHARS` | `8000` | Total characters injected per prompt |
  130. | `WINNOW_CONTEXT_MAX_CANDIDATES` | `60` | Max files considered per prompt |
  131. | `WINNOW_HOME` | `~/.winnow` | Cache, decision log, env file |
  132. ## Shadow mode: run it for a week without trusting it
  133. ```
  134. WINNOW_MODE=shadow
  135. ```
  136. In shadow mode every hook does its full job, judging, caching and logging, but never changes what Claude sees and never calls the summarizer. Use it for the first week with any judge. `winnow stats` then reports how many results it *would* have rewritten and how many characters it would have saved, and each decision line in `~/.winnow/decisions.jsonl` carries the per-block probabilities and a cache key, so `winnow recall <key>` shows you exactly what would have been hidden. Switch to `WINNOW_MODE=active` when the decisions look right.
  137. ## Replay: score a judge on your own history, no key needed
  138. Your Claude Code transcripts already hold hundreds of large tool results, each followed by what Claude did next. `winnow replay` turns that into a labeled benchmark and scores a judge against it, offline.
  139. ```bash
  140. winnow replay run --judge lexical # every transcript under ~/.claude/projects
  141. winnow replay run --judge lexical --limit 200 path/to/session.jsonl
  142. ```
  143. The label is weak but free: a block counts as *needed* if, later in the same turn, Claude reused one of its lines in an edit, write or command, or mentioned a distinctive identifier that appears in few other blocks. Blocks that Claude read, understood, and never quoted get labeled *not needed*, so treat the reported regret as an upper bound.
  144. The report gives, for each `WINNOW_DROP` threshold, how much would be hidden and what share of needed blocks that would cost (regret), plus a calibration table and expected calibration error. The `lexical` judge is a keyless word-overlap baseline; any real judge has to beat it. When you have a key:
  145. ```bash
  146. winnow replay judge --judge adapter # re-judge the same cases
  147. winnow replay judge --judge typesafe
  148. winnow replay score --judged ~/.winnow/replay/judged-typesafe.jsonl
  149. ```
  150. Cases, judged files and scores live in `~/.winnow/replay/`. Nothing leaves the machine unless you pick a judge that calls an API.
  151. ### Hand labels
  152. Weak labels are good enough to rank judges and not good enough to trust a regret number. To get real labels, draw a blind sample and label it:
  153. ```bash
  154. winnow replay sample --judged ~/.winnow/replay/judged-typesafe.jsonl # 100 blocks, stratified by judge probability
  155. winnow replay label --sample ~/.winnow/replay/sample.jsonl --labeler you # interactive: y needed, x not needed, u unsure
  156. winnow replay agreement --sample ~/.winnow/replay/sample.jsonl # weak vs you, labeler vs labeler
  157. winnow replay score --judged ~/.winnow/replay/judged-typesafe.jsonl --labels ~/.winnow/replay/labels.jsonl --labeler you
  158. ```
  159. The sample also comes as a Markdown sheet (`sample.md`) if you would rather read it in an editor and import answers from a text file with `winnow replay import-labels`. A second labeler on a subset (`--limit 20 --seed 2`) gives an agreement number.
  160. ### Question sets
  161. The words the judge is asked with matter. `WINNOW_QUESTIONS` selects a set, and `winnow replay judge --questions <name>` scores one against the same cases as any other:
  162. | set | what it is | result on hand labels |
  163. |---|---|---|
  164. | `structured` (default) | criteria as `what` / `not_for` / `examples` objects | clean below 0.1, hides ~5% of text there |
  165. | `default` | one-line criteria | clean below 0.1, hides ~2% |
  166. | `strict` | "directly about the task" | overconfident: 23% of its bottom bin was needed |
  167. ### Measured
  168. First results on 300 real cases, 97 blind hand labels, three question sets and the sidecar's latency are in [docs/DESIGN.md](docs/DESIGN.md#first-numbers-jev-vs-the-lexical-baseline), with the raw score files under `docs/results/` and a draft write-up in [docs/WRITEUP.md](docs/WRITEUP.md). Reports print calibration (ECE) and ordering (ROC AUC) side by side, because a judge that answers the base rate for every block scores a fine ECE and can hide nothing; an experiment with [jevlike](https://github.com/vinnylarouge/jevlike), an open Jev-shaped model, is what made that necessary (see [docs/DESIGN.md](docs/DESIGN.md#an-open-judge-jevlike-on-the-same-harness)).
  169. ## How it hooks in
  170. winnow is a Claude Code **function-hook** plugin: a TypeScript module, [`hooks/winnow.ts`](hooks/winnow.ts), that the engine loads in-process. Its `tool.call` handler wraps every Read, Bash and Grep call, hands the result to the sidecar (which reads the task from the session's transcript), and returns the sidecar's rewrite as the tool's result; its `prompt.submit` handler appends the selected context files to the prompt. Function hooks are early access, behind a flag; winnow is tested on Claude Code 2.1.277 and later. On 2.1.277 a subagent's tool calls don't reach the module, so they pass through untouched; on 2.1.286 they are judged like any other. Without the flag the module never loads and winnow does nothing; `winnow doctor` says so.
  171. When a result is rewritten you see a toast: `winnow: hid 3 of 8 blocks of Read (5.1k to 1.8k chars; winnow_recall ab12)`. Small results never leave the process; the judging, thresholds and cache are all in the Python sidecar, so nothing measured below changes with the hook mechanism.
  172. The module's tests run under Claude Code's own kit, with no key and no sidecar (the kit has no network, so they cover task reconstruction and the pass-through path):
  173. ```bash
  174. CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude plugin test .
  175. ```
  176. For editor types, run `/plugin-types ./.claude/types` inside a Claude Code session with the flag on; the `tsconfig.json` at the repo root already includes that folder, `hooks/` and `tests/`. The surface may change between releases; the plugin pins nothing and is tested against the current one in CI.
  177. ## The resident sidecar
  178. The module posts every large result to `winnow serve` on `127.0.0.1:47311`. The SessionStart hook runs `winnow serve --ensure`, which starts a detached server if none is answering and replaces one left over from an older plugin version. The server keeps the SDK loaded and the judge's connection warm, re-reads `~/.winnow/env` whenever it changes, and exits after 45 idle minutes. When a session needs it again, the module starts it (`winnow serve --revive`) and resends.
  179. ```bash
  180. winnow serve --status # is it up, how many requests, is the judge built
  181. winnow serve --stop # off until the next session start; sessions already open won't restart it
  182. winnow serve --ensure # what SessionStart runs; prints nothing
  183. winnow bench --http # 381 ms for a Python start per call vs 16 ms through the resident sidecar, on the machine this was built on
  184. ```
  185. If the server is down and cannot be started, results pass through unjudged, winnow says so once, and `winnow doctor` says why. After a failed start the module waits a minute before trying again, so a dead sidecar costs nothing per call. Set `WINNOW_PORT` and `PORT` in `hooks/winnow.ts` together if the port is taken.
  186. ## Housekeeping
  187. ```bash
  188. winnow bench # hook overhead with the judge off
  189. winnow clean # drop cache entries older than 30 days, then trim to 200 MB
  190. ```
  191. ## Measuring it
  192. ```bash
  193. winnow stats
  194. ```
  195. Reports outputs judged and rewritten, characters and estimated tokens saved, judge latency and cost, and the **regret rate**: the share of hidden outputs that Claude later asked to recall.
  196. The better regret number comes from you. `winnow review` walks the stubs from your recent sessions, newest first, and shows the whole picture a person needs: what was asked (for a subagent, its delegation prompt), which subagent ran it, what Claude kept and what it lost, what Claude did in its next few actions, and an automatic check for whether any of those actions reused a line from the hidden text. Then one question per stub: was hiding that fine? Ten of these while the session is still fresh in your head are worth more than a hundred labels on old transcripts, and `winnow stats` reports the result as human regret.
  197. ```bash
  198. winnow review --limit 10 # y fine, x should have been kept, u unsure
  199. ``` Regret against `WINNOW_DROP` is the calibration curve for your own workload. Every decision, with per-block probabilities, is one line in `~/.winnow/decisions.jsonl`; demo runs are logged but excluded from stats.
  200. Recall from the shell:
  201. ```bash
  202. winnow recall a1b2c3d4e5f6 --start 41 --end 188
  203. ```
  204. ## Troubleshooting
  205. Working and silently disabled look the same from inside a session, so check in this order.
  206. 1. **Is the plugin enabled?** `claude plugin list` should show `winnow@winnow` as enabled. Enable with `claude plugin enable winnow@winnow` and start a new session.
  207. 2. **Is the sidecar up?** `winnow serve --status`. If not, `winnow serve --ensure` starts it; the SessionStart hook does the same, and an open session starts it again when it next needs it. When it can't be started, results pass through, winnow shows one message saying so, and `claude --debug` logs why.
  208. 3. **Can the judge start?** `winnow doctor`. The common failure is a missing key, or a key set in a terminal that the desktop app never sees. When the judge can't start, winnow also posts one message per session saying so.
  209. 4. **Did it fire?** `tail -1 ~/.winnow/decisions.jsonl` after reading a large file. A line with `"rewritten": true` and a `key` means a stub went to Claude. `"reason": "nothing_to_prune"` means the judge thought every block mattered; `"below_min_prune_ratio"` means it would have hidden less than `WINNOW_MIN_PRUNE_RATIO` of the text, so the rewrite was skipped (the usual outcome on ordinary source files at a conservative `WINNOW_DROP`). No line at all means the hook didn't run: `winnow doctor` checks the function-hooks flag; then `~/.winnow/errors.log`; then `claude --debug`, which logs `hooks module winnow@winnow loaded` when the module is in.
  210. 5. **Everything passes through with `judge_error`.** Read `~/.winnow/errors.log`; it has the traceback. Timeouts show up as `TypeSafeAPITimeoutError`; raise `WINNOW_JUDGE_TIMEOUT` or lower `WINNOW_MAX_STATE_CHARS`.
  211. 6. **Stubs appear but nothing is summarized.** Summaries need Anthropic credentials. `winnow doctor` shows whether they were found.
  212. 7. **A file you need came back pruned.** Use the stub's key with `winnow_recall`, or read the range it names with `offset`/`limit`. To keep a directory out of winnow's reach entirely, add it to `WINNOW_EXCLUDE_PATHS`.
  213. ## Turning it off
  214. ```bash
  215. claude plugin disable winnow@winnow
  216. winnow serve --stop
  217. ```
  218. New sessions won't load winnow. Sessions already open keep the module until they end, but after `--stop` they leave the sidecar off and pass results through untouched. `claude plugin enable winnow@winnow` turns it back on from the next session.
  219. ## Uninstall
  220. ```bash
  221. claude plugin uninstall winnow@winnow
  222. claude plugin marketplace remove winnow
  223. ```
  224. Then delete `~/.winnow` (cache, decision log, and your env file) if you don't want it kept.
  225. ## Windows notes
  226. The SessionStart hook that starts the sidecar runs under Git Bash when it is installed, otherwise PowerShell; the command works in both. Paths from Claude Code arrive with backslashes, which winnow handles. The env file lives at `%USERPROFILE%\.winnow\env`. `WINNOW_CONTEXT_DIRS` uses `;` between directories. `uv` installs with `winget install astral-sh.uv` or from [astral.sh](https://docs.astral.sh/uv/getting-started/installation/).
  227. ## Layout
  228. ```
  229. winnow/
  230. ├── .claude-plugin/plugin.json plugin manifest
  231. ├── .claude-plugin/marketplace.json makes the repo installable as a marketplace
  232. ├── hooks/hooks.json loads the module; SessionStart starts the sidecar
  233. ├── hooks/winnow.ts the function-hook module: tool.call for Read/Bash/Grep, prompt.submit for context
  234. ├── tests/winnow.test.ts its tests, for `claude plugin test`
  235. ├── .mcp.json winnow_recall / winnow_stats MCP server
  236. ├── skills/winnow/SKILL.md teaches Claude what a stub means
  237. ├── sidecar/ Python package (uv project)
  238. │ ├── src/winnow/
  239. │ │ ├── hooks.py the two handlers
  240. │ │ ├── judge.py Jev / adapter backends, one interface
  241. │ │ ├── transcript.py derive "current task" from the session transcript
  242. │ │ ├── extract.py tool_response → text → tool_response
  243. │ │ ├── serve.py the resident sidecar the module talks to
  244. │ │ ├── questions.py question sets the judge is asked with
  245. │ │ ├── replay.py labels.py the offline benchmark and hand-labeling tools
  246. │ │ ├── demo.py bench.py winnow demo, winnow bench
  247. │ │ ├── chunk.py policy.py stub.py summarize.py cache.py log.py memory.py config.py
  248. │ │ ├── mcp_server.py recall server
  249. │ │ └── cli.py all commands
  250. │ └── tests/
  251. └── docs/DESIGN.md decisions, limits, roadmap
  252. ```
  253. ## Development
  254. ```bash
  255. cd winnow/sidecar
  256. uv sync
  257. uv run pytest
  258. ```
  259. Tests run with the judge off and a fake judge, so they need no keys and no network. The function-hook module has its own tests under Claude Code's kit, which needs no login either:
  260. ```bash
  261. cd winnow
  262. CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude plugin test .
  263. ```
  264. One trap when developing: with this checkout as Claude Code's working directory, `.mcp.json` is also read as a project-level MCP config, where `${CLAUDE_PLUGIN_ROOT}` is undefined, so that copy of the recall server fails to start (uv silently runs the wrong interpreter). The installed plugin's copy is unaffected.
  265. ## Roadmap
  266. See [docs/DESIGN.md](docs/DESIGN.md). In short: a `session.compact` pass with the same calibrated question, read-narrowing on `PreToolUse`, a done-ness gate on `Stop`, and a published regret-versus-threshold curve on more people's sessions.
  267. ## License
  268. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.