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.
Badge for your README
Markdown
[](/listings/ghalebdweikat--winnow)HTML
<a href="/listings/ghalebdweikat--winnow"><img src="/api/listings/ghalebdweikat--winnow/badge.svg" alt="findsafeskills safety rating" /></a>Install
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)
- {
- "name": "winnow",
- "description": "winnow: a calibrated context sieve for Claude Code.",
- "owner": {
- "name": "Ghaleb Dweikat",
- "email": "ghalebdweikat@gmail.com",
- "url": "https://github.com/GhalebDweikat"
- },
- "plugins": [
- {
- "name": "winnow",
- "source": "./",
- "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.",
- "version": "0.5.2",
- "author": {
- "name": "Ghaleb Dweikat"
- },
- "category": "productivity",
- "tags": ["context", "typesafe", "jev", "system-one", "hooks"]
- }
- ]
- }
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)
- # winnow
- [](https://github.com/GhalebDweikat/winnow/actions/workflows/tests.yml)
- A calibrated context sieve for Claude Code.
- 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.
- **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.
- ## What it does
- ```
- Read big.py ──► Claude Code ──► tool.call hook ──► winnow
- │
- split into ~25-line blocks ◄─────────────────────────┘
- one call to the judge: "is block N needed for the current task?" ×N, in parallel
- keep confident-yes and uncertain blocks verbatim
- hide confident-no blocks: cache full text ─► summarize ─► stub
- │
- Claude sees ◄── { result } ◄───────────────────────────────┘
- ```
- A stub looks like this:
- ```
- [winnow] Lines 41-188 (148 lines) hidden: judged unlikely to matter for the current task (relevance <= 0.22).
- [winnow] Summary: Argparse setup for the --export and --format flags, plus the license header.
- [winnow] Full text cached as key a1b2c3d4e5f6. Call winnow_recall(key="a1b2c3d4e5f6", start=41, end=188) if you need it.
- ```
- 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.
- 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.
- 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.
- 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.
- What winnow changes is only what Claude sees. Files on disk, the commands that ran, and Claude Code's own transcript are untouched.
- ## Quick start
- 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):
- ```json
- { "env": { "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1" } }
- ```
- Then install:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- claude --plugin-dir ./winnow
- ```
- To scope the plugin to one project rather than your whole account, add `--scope project` to the `marketplace add` command.
- ## Add your keys
- 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.
- **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.
- **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:
- - 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.
- ```
- TYPESAFE_API_KEY=ts-...
- ANTHROPIC_API_KEY=sk-ant-...
- ```
- - Or the `env` block of `~/.claude/settings.json`, which Claude Code applies to every session and every subprocess it starts:
- ```json
- { "env": { "TYPESAFE_API_KEY": "ts-...", "ANTHROPIC_API_KEY": "sk-ant-..." } }
- ```
- A variable already in the environment wins over the file, so a plain shell export still works for CLI use.
- **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).
- **4. Verify.**
- ```bash
- uv run --project winnow/sidecar winnow doctor
- ```
- 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.
- Summaries use the Anthropic credentials. Set `WINNOW_SUMMARY=0` to turn them off; stubs then say "Summary unavailable" and everything else still works.
- ### Running `winnow` commands
- From the clone, every command is `uv run --project winnow/sidecar winnow <command>`. To have `winnow` on your PATH anywhere:
- ```bash
- uv tool install ./winnow/sidecar
- winnow doctor
- ```
- 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>`.
- ## What leaves your machine, and what it costs
- winnow's job is reading everything Claude reads, so be clear about where it goes.
- | Data | Sent to | When |
- |---|---|---|
- | 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` |
- | The hidden blocks only | Anthropic | when summaries are on and something was hidden |
- | Your prompt and the first 600 characters of each candidate memory file | the judge | every prompt, when candidate files exist |
- 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.
- Approximate cost per judged result, for a 10,000-token output:
- | Judge | Judge call | Summaries (up to 4, Haiku 4.5) | Total |
- |---|---|---|---|
- | Jev at $0.042 per million input tokens | $0.0004 | about $0.005 | under a cent |
- | Adapter on Haiku 4.5 at $1 per million input tokens | about $0.01 | about $0.005 | a few cents |
- `winnow stats` reports the judge's actual token usage and cost after the fact.
- ## Configuration
- All settings are environment variables (or lines in `~/.winnow/env`). Defaults are deliberately conservative.
- | Variable | Default | Meaning |
- |---|---|---|
- | `WINNOW_MODE` | `active` | `active` rewrites tool results; `shadow` judges and logs only |
- | `WINNOW_JUDGE` | `typesafe` | `typesafe`, `adapter`, or `off` |
- | `WINNOW_MODEL` | `jev-latest` | Jev model id |
- | `WINNOW_JUDGE_TIMEOUT` | `15` | Seconds per judge call, including one retry |
- | `WINNOW_ADAPTER_PROVIDER` | `anthropic` | Provider behind the adapter (`anthropic` or `openai`) |
- | `WINNOW_ADAPTER_MODEL` | `claude-haiku-4-5` | Model behind the adapter |
- | `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 |
- | `WINNOW_QUESTIONS` | `structured` | Question set the judge is asked with: `structured`, `default`, or `strict` |
- | `WINNOW_EXCLUDE_PATHS` | `WINNOW_HOME` | Reads under these directories are never judged (path-separator delimited) |
- | `WINNOW_EXCLUDE_COMMANDS` | `\bwinnow\b` | Bash commands matching this regex are never judged |
- | `WINNOW_PORT` | `47311` | Sidecar port; `PORT` in `hooks/winnow.ts` must match |
- | `WINNOW_MIN_CHARS` | `1500` | Outputs shorter than this are never touched |
- | `WINNOW_DROP` | `0.1` | Hide a block only when P(needed) is below this |
- | `WINNOW_KEEP` | `0.5` | Error-gate threshold; also the line between "confident keep" and "uncertain keep" |
- | `WINNOW_MIN_PRUNE_RATIO` | `0.2` | Skip the rewrite unless at least this fraction of the text would be hidden |
- | `WINNOW_BLOCK_LINES` | `25` | Target lines per block |
- | `WINNOW_MAX_BLOCKS` | `200` | Cap on questions per call; block size grows to fit |
- | `WINNOW_MAX_STATE_CHARS` | `120000` | Blocks beyond this budget are kept unjudged |
- | `WINNOW_SUMMARY` | `1` | Summarize hidden groups |
- | `WINNOW_SUMMARY_MODEL` | `claude-haiku-4-5` | Summarizer model |
- | `WINNOW_SUMMARY_MAX_GROUPS` | `4` | Summarize at most this many hidden groups per result; the rest get "Summary unavailable" |
- | `WINNOW_SUMMARY_MAX_CHARS` | `20000` | Characters of a hidden group sent to the summarizer |
- | `WINNOW_CONTEXT_DIRS` | | Extra directories of `.md` files for the prompt-time selector. Path-separator delimited: `:` on macOS and Linux, `;` on Windows |
- | `WINNOW_CONTEXT_GATE` | `0.5` | Minimum P(relevant) to inject a file |
- | `WINNOW_CONTEXT_TOP_K` | `3` | Max files injected per prompt |
- | `WINNOW_CONTEXT_MAX_CHARS` | `8000` | Total characters injected per prompt |
- | `WINNOW_CONTEXT_MAX_CANDIDATES` | `60` | Max files considered per prompt |
- | `WINNOW_HOME` | `~/.winnow` | Cache, decision log, env file |
- ## Shadow mode: run it for a week without trusting it
- ```
- WINNOW_MODE=shadow
- ```
- 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.
- ## Replay: score a judge on your own history, no key needed
- 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.
- ```bash
- winnow replay run --judge lexical # every transcript under ~/.claude/projects
- winnow replay run --judge lexical --limit 200 path/to/session.jsonl
- ```
- 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.
- 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:
- ```bash
- winnow replay judge --judge adapter # re-judge the same cases
- winnow replay judge --judge typesafe
- winnow replay score --judged ~/.winnow/replay/judged-typesafe.jsonl
- ```
- Cases, judged files and scores live in `~/.winnow/replay/`. Nothing leaves the machine unless you pick a judge that calls an API.
- ### Hand labels
- 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:
- ```bash
- winnow replay sample --judged ~/.winnow/replay/judged-typesafe.jsonl # 100 blocks, stratified by judge probability
- winnow replay label --sample ~/.winnow/replay/sample.jsonl --labeler you # interactive: y needed, x not needed, u unsure
- winnow replay agreement --sample ~/.winnow/replay/sample.jsonl # weak vs you, labeler vs labeler
- winnow replay score --judged ~/.winnow/replay/judged-typesafe.jsonl --labels ~/.winnow/replay/labels.jsonl --labeler you
- ```
- 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.
- ### Question sets
- 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:
- | set | what it is | result on hand labels |
- |---|---|---|
- | `structured` (default) | criteria as `what` / `not_for` / `examples` objects | clean below 0.1, hides ~5% of text there |
- | `default` | one-line criteria | clean below 0.1, hides ~2% |
- | `strict` | "directly about the task" | overconfident: 23% of its bottom bin was needed |
- ### Measured
- 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)).
- ## How it hooks in
- 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.
- 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.
- 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):
- ```bash
- CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude plugin test .
- ```
- 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.
- ## The resident sidecar
- 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.
- ```bash
- winnow serve --status # is it up, how many requests, is the judge built
- winnow serve --stop # off until the next session start; sessions already open won't restart it
- winnow serve --ensure # what SessionStart runs; prints nothing
- 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
- ```
- 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.
- ## Housekeeping
- ```bash
- winnow bench # hook overhead with the judge off
- winnow clean # drop cache entries older than 30 days, then trim to 200 MB
- ```
- ## Measuring it
- ```bash
- winnow stats
- ```
- 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.
- 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.
- ```bash
- winnow review --limit 10 # y fine, x should have been kept, u unsure
- ``` 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.
- Recall from the shell:
- ```bash
- winnow recall a1b2c3d4e5f6 --start 41 --end 188
- ```
- ## Troubleshooting
- Working and silently disabled look the same from inside a session, so check in this order.
- 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.
- 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.
- 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.
- 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.
- 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`.
- 6. **Stubs appear but nothing is summarized.** Summaries need Anthropic credentials. `winnow doctor` shows whether they were found.
- 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`.
- ## Turning it off
- ```bash
- claude plugin disable winnow@winnow
- winnow serve --stop
- ```
- 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.
- ## Uninstall
- ```bash
- claude plugin uninstall winnow@winnow
- claude plugin marketplace remove winnow
- ```
- Then delete `~/.winnow` (cache, decision log, and your env file) if you don't want it kept.
- ## Windows notes
- 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/).
- ## Layout
- ```
- winnow/
- ├── .claude-plugin/plugin.json plugin manifest
- ├── .claude-plugin/marketplace.json makes the repo installable as a marketplace
- ├── hooks/hooks.json loads the module; SessionStart starts the sidecar
- ├── hooks/winnow.ts the function-hook module: tool.call for Read/Bash/Grep, prompt.submit for context
- ├── tests/winnow.test.ts its tests, for `claude plugin test`
- ├── .mcp.json winnow_recall / winnow_stats MCP server
- ├── skills/winnow/SKILL.md teaches Claude what a stub means
- ├── sidecar/ Python package (uv project)
- │ ├── src/winnow/
- │ │ ├── hooks.py the two handlers
- │ │ ├── judge.py Jev / adapter backends, one interface
- │ │ ├── transcript.py derive "current task" from the session transcript
- │ │ ├── extract.py tool_response → text → tool_response
- │ │ ├── serve.py the resident sidecar the module talks to
- │ │ ├── questions.py question sets the judge is asked with
- │ │ ├── replay.py labels.py the offline benchmark and hand-labeling tools
- │ │ ├── demo.py bench.py winnow demo, winnow bench
- │ │ ├── chunk.py policy.py stub.py summarize.py cache.py log.py memory.py config.py
- │ │ ├── mcp_server.py recall server
- │ │ └── cli.py all commands
- │ └── tests/
- └── docs/DESIGN.md decisions, limits, roadmap
- ```
- ## Development
- ```bash
- cd winnow/sidecar
- uv sync
- uv run pytest
- ```
- 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:
- ```bash
- cd winnow
- CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude plugin test .
- ```
- 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.
- ## Roadmap
- 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.
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.