| Without OpenWolf | With OpenWolf | |------------------|---------------| | Each agent starts cold and learns your project separately | One .wolf/ brain, shared across Claude Code, Codex and OpenCode | | Switching agents means losing everything the last one learned | Corrections, bug fixes and project map follow you across tools | | Your token usage is a monthly invoice with no line items | Real usage read from the transcript, per session, per agent | | Nobody can tell you what broke the prompt cache | Attributed: model switch, compaction, version change, expiry | | The agent rereads a file it already saw | Repeated reads caught; oversized Bash output condensed before it enters context |

What it does

Coding agents waste tokens in predictable ways. A grep -rn dumps 40,000 tokens into context, and the session re-reads them from cache on every later API call. The same file gets printed three times with cat. Conventions you taught the agent last week are gone today. When context compacts, the agent forgets what it already did.

OpenWolf installs lifecycle hooks into your agent and fixes this underneath your normal workflow:

• Oversized Bash output is condensed before it enters context. The full text stays on disk with a pointer. Test failures are never touched.
• Your project gets a durable index. openwolf find locates any symbol in under 1k tokens. Large files carry exact line ranges so the agent reads one function, not the whole file.
• Corrections, conventions, and bug fixes are written to files that survive sessions, travel through git, and reach every agent and teammate.
• After compaction, OpenWolf restores what was lost: in-flight state, your rules, and the path-scoped instructions the platform drops.
• Everything is measured. Real usage from transcripts, hook delivery verified against the harness's own records, and savings counted only where OpenWolf can prove them.

Quick start

npm install -g openwolf
cd your-project
openwolf init

init detects the agents installed on your machine and wires each of them. Then use your agents as normal.

Supported agents

| Agent | Integration | |-------|-------------| | Claude Code | Full: 12 hooks, output governor, skills, verified measurement | | Codex CLI | Core hooks via .codex/hooks.json + AGENTS.md: session, read, write, compaction, stop | | OpenCode | Native plugin + AGENTS.md: session and tool before/after | | Cursor | Rules file (context only) | | Gemini CLI | GEMINI.md block (context only) | | Antigravity | AGENTS.md block (context only) |

All agents share the same .wolf/ directory. It ships with a .gitignore that commits the useful state (conventions, handoff, bug log, index) and ignores the machine-local runtime (ledgers, caches). On Claude Code the learned conventions also sync with native auto-memory, in both directions.

How it works

openwolf init creates .wolf/ and registers hooks with your agent. The hooks are plain Node.js scripts: no network, no AI calls, no dependencies.

| File | Purpose | |------|---------| | anatomy-index.json | Project index: descriptions, sizes, symbols, import graph | | cerebrum.md | Preferences, conventions, and a Do-Not-Repeat list | | STATUS.md | Session handoff. Regenerate with /handoff | | buglog.json | Searchable memory of bugs and their fixes | | memory.md | Action log per session | | token-ledger.json | Measured, estimated, and verified usage | | hooks/ | The 12 lifecycle hooks, with health heartbeats | | cache/bash/ | Verbatim copies of every condensed Bash output |

During a session:

• Session start. A ~400-token index of your project state is injected: what each file holds, the top rules, the current handoff. Pointers, not content.
• Before reads. Duplicate reads get a note. Large files get their symbol map so the agent can read a slice.
• After Bash. Output over 2,000 tokens is condensed by command family: grep floods keep the first matches per file plus counts, git show keeps the header and diff stats, file re-prints keep head and tail. Original preserved, delta recorded. Test and build output is suggested-only by default because failure detail matters more than tokens.
• Every 25 tool batches. The top rules are repeated in one short note. Instruction compliance decays as sessions get longer (the one controlled study of this, across 1,650 sessions, found the decay and found that file size does not matter). Cadence is the fix.
• On compaction. State, rules, and scoped instructions are re-injected.
• On stop. The ledger records real usage per model and verifies against the transcript which hooks fired, which failed, and which injected context actually reached the model.

Measurement

openwolf report

  Measured (all project transcripts, scanned now)
    API calls:              814
    Output tokens:          737,952
    Cache reads:            238,172,904
    Cache writes:           3,323,678

  Bash governor (measured at the rewrite point)
    Governed calls:         12
    Original output:        96,410
    Entered context:        14,867
    Kept out of context:    81,543

  Cache rebuilds (last 7 days): 6 events, 1,942,520 tokens re-written
    model_switch         3 events  929,737 tok
    cache_expired        1 events  524,661 tok
    unattributed         2 events  488,122 tok

Three things worth knowing about these numbers:

1. The governor delta is measured where nothing else can measure it. The platform's telemetry logs tool output before hooks run, so only the hook that rewrites the output knows what actually entered context.
2. Cache rebuilds are the most expensive events in an agent session: a full rebuild re-pays your entire context at the write rate instead of the 0.1x read rate. OpenWolf names the trigger and the cost.
3. Earlier releases reported estimated savings from a heuristic that counted tokens that were actually spent. That math is gone. OpenWolf also reports its own injection cost next to any saving it claims. If a context tool cannot show you measured numbers including its own overhead, doubt it.

openwolf bench --repo <fixture> --yes runs the same tasks with and without OpenWolf and reports each token dimension separately, plus completion rate and the bash re-run rate. It spends real API budget, so it requires --yes.

Reliability

Invisible tools need proof of life. Every hook writes a heartbeat. Session start verifies the installed hooks can load. openwolf update runs a selfcheck on every hook after install and fails loudly instead of leaving a broken install. The dashboard shows failing hooks with the error. This exists because a hook once crashed silently 440 times over three weeks before anyone noticed.

Security

• Dashboard binds to 127.0.0.1 with per-project token auth.
• No shell interpolation anywhere; every process call uses argument arrays.
• Hooks never auto-approve tool calls. Permission decisions stay yours.
• Secret-bearing files (.env, keys, credentials) never enter any index.
• Path traversal guards on all cron file access.

Skills

Installed for every wired agent:

• /handoff regenerates STATUS.md from git, the action log, and open items.
• /security-audit runs a layered audit and files results into the bug log.
• /reframe picks or migrates a UI framework from a curated comparison of 13, with an anti-generic design mandate.

On Claude Code, the operating protocol ships as a proper skill so CLAUDE.md stays a five-line stub.

Dashboard

openwolf dashboard

Local, token-authenticated, live. The hero number is tokens verifiably kept out of context, with a plain-language reading of what that means. Around it: what the measured usage is worth at list price and where that cost sits (cache reads usually dominate), OpenWolf's own overhead as a share of what it saved, the governor's results per command family, cache rebuild attribution, per-agent breakdown, hook health, the anatomy browser, activity, and cron control.

Commands

openwolf init              Set up .wolf/ and wire detected agents
openwolf status            Health, stats, file integrity
openwolf scan              Rebuild the project index
openwolf scan --check      CI check: does the index match the tree
openwolf find <query>      Locate a symbol or file (ranked, ~1k tokens max)
openwolf find --file <p>   One file's description, size, and symbol map
openwolf map               Token-budgeted overview of the important files
openwolf report            Measured, verified, governed, attributed usage
openwolf bench             A/B benchmark with and without OpenWolf (--yes)
openwolf bug search <term> Full-text search over the bug memory
openwolf dashboard         Open the dashboard
openwolf cron list         Scheduled maintenance tasks
openwolf update            Update every registered project (backup first)
openwolf restore [backup]  Roll back .wolf/ from a backup

Requirements

Node.js 20+ and at least one supported agent. Works on macOS, Linux, and Windows. Bug-log full-text search uses Node's built-in SQLite on 22.5+ and falls back to a simpler matcher below that.

Limitations

• Estimates use a character-ratio heuristic. Measured and verified numbers come from transcripts and the rewrite point.
• The Bash governor and decay re-injection currently run on Claude Code. Codex and OpenCode get the core lifecycle hooks; Gemini and Cursor are context-only.
• Protocol compliance still depends on the model. Hooks enforce what can be enforced and measure the rest.

Found something broken? File an issue.

Contributors

OpenWolf is better because people fixed it. Every merged contribution is credited here. Kindly let us know if we have missed a contribution.

| | | | | | |:-:|:-:|:-:|:-:|:-:| | fsener | albertomenache | whydoyouwork | mann1x | GordongWang | | WeathermanTony | goashem | bryandent | levnikmyskin | svanack404 | | riverwolf67 | nottyjay | alfasin | ChasLui | JarrodAI | | meketreve | Laptopcorei7 | statik1 | spignataro | Esturban | | prghbla | 1re2turn1 | aevnar | davdittrich | krsfer | | kantorcodes | | | | |

License

AGPL-3.0

Author

Built by Farhan Palathinkal, Cytostack