windvane

A Claude Code plugin that keeps the state of a session and steers it: the recorder drafts the checkpoint, compaction happens at the right point with the state banked, the rules and the checkpoint ride inside the compacted conversation and every subagent's prompt, tool results are trimmed and secrets redacted, and project memory and rules are a tool call away. The principle: never ask the model to write what the machine can record.

This file is for people working on windvane itself. Users read README.md and docs/.

Layout

• .claude-plugin/plugin.json is the manifest and holds the config rows. marketplace.json makes the repository its own marketplace.
• hooks/ is the mod, in TypeScript. register.ts registers every hook and is the only file that holds $; the pieces keep their logic in their own modules and take a Host of closures (engine.ts): the band, the pane, /remember, the strict, export and import commands, the door, the ledger, the agent briefs, the compaction brief, the bridge, the tools and the first-run offer of the semantic tier (setup.ts). hooks.json declares the classic command hooks used headless and as the bridge's fallback. The mod's tests are tests/mod/*.test.ts.
• windvane/ is the Python engine. No dependencies. events/ there holds the hook handlers, mining/ the session miner, semantic/ the optional encoder. daemon.py and daemon_client.py are the resident process and its thin client. config.py holds every setting in KNOBS.
• skills/reference/SKILL.md is the quick reference the model reads (/windvane:reference; the plain /windvane is the pane, so the skill cannot share that name).
• docs/ is the user documentation. docs/assets/ holds the logo marks, the social card (uploaded in the repository's settings, nothing links it) and the two SVG diagrams the README and how-it-works embed; the diagrams use only neutral greys and the accent so they read on GitHub's light and dark themes. demo/ holds the demo tapes and gif.
• tests/ holds the Python tests.
• types/ and .claude-plugin/types/ are the type declarations for the mod. The second folder is written by Claude Code when the plugin loads and is not committed.

Tests

Python tests, from the repository root (needs pytest, available as the test extra):

python -m pytest tests/test_config.py

Run the tests for the module you changed, not the whole suite by default. pyproject.toml puts the repository root on the path, so windvane imports from the tree.

The installed plugin on a development machine is usually this folder. A change that moves or renames windvane/daemon_client.py, or the commands in hooks/hooks.json that name it, breaks every hook of the running session the moment it lands: fix hooks.json first, run /reload-plugins, then move the file.

Plugin tests and checks, from the repository root:

claude plugin test .
claude plugin validate .

Python needs 3.10 or later.

Rules for the code

• The engine stays standard-library only. The semantic tier is an optional extra and is imported only inside the functions that need it.
• Every on(...) lives in register.ts, with the hook's body written there, and $ is passed only to functions declared at the top of that file (the plugin directory's reader refuses $ or on handed to another file). The other modules take a Host (engine.ts) built by hostOf in register.ts, where every $.noun.method call and every environment variable name is spelled; the $.state references are declared in register.ts and the drawings get plain values. The engine takes one unmatched hook per event per plugin. No hook sits on a pattern (*, tool.*, classic.*): the classic events are hooked by name, and PreToolUse has no mod hook at all, because the directory reads a permission check's hook only when it returns a literal { deny } or { ask } or next(e) with e read plainly (a member, or handed whole to a function, never through a cast); a tool.call hook answers that way or with { result }. Keep that shape.
• register.ts mirrors the engine's pressure constants (output reserve, checkpoint margin, heads-up fraction, default compaction point). Change both together.
• Never write a file with a call that turns line endings into CRLF. The repository is LF, and .gitattributes normalises on read, so a CRLF file looks clean in git status while its bytes differ. Write bytes with the terminator the file already has.
• A hook handler must never raise into Claude Code. Failures degrade to an empty answer.
• The mod writes nothing to the store. The engine writes it.

Rules for text

• Docs and comments are plain prose for a stranger: no personal names, machine names, workspace paths, email addresses or network addresses, and no emoji.
• Every claim in a doc is backed by code in this tree. When a doc and the code disagree, the code wins and the doc is fixed.
• Do not describe internal function names in user docs.
• Commits and published text carry no personal names.
• Keep user-visible numbers (defaults, thresholds, counts) in step with config.py, rules.py and hooks.json.