OpenWolf: Shared Project Memory and Token Accounting for Claude Code, Codex and OpenCode

The problem OpenWolf targets: cold starts and unaccounted context

Coding agents lose state at predictable boundaries. A session ends, context compacts, or you switch from Claude Code to Codex, and the conventions you explained last week are gone. OpenWolf's README frames this as two separate failures that share a cause: each agent starts cold and learns the project separately, and token usage arrives as a monthly invoice with no line items. The project's answer is a single .wolf/ directory that all supported agents read from and write to, plus a ledger built from the harness transcript rather than from estimates.

The intended user is someone running more than one agent against the same repository, or running one agent long enough that compaction and repeated file reads become visible costs. The README gives a concrete example of the waste: a grep -rn dumping 40,000 tokens into context that the session then re-reads from cache on every later API call, and the same file printed three times with cat. OpenWolf is not a model, a proxy or a hosted service. It is a set of lifecycle hooks plus a CLI, and the README states the hooks are plain Node.js scripts with no network, no AI calls and no dependencies.

How the hook layer and the .wolf/ directory fit together

The architecture is a directory plus hooks. openwolf init creates .wolf/ and registers hooks with each detected agent. Inside .wolf/, anatomy-index.json holds the project index with descriptions, sizes, symbols and an import graph; cerebrum.md holds preferences, conventions and a Do-Not-Repeat list; STATUS.md is the session handoff, regenerated with /handoff; buglog.json is a searchable record of bugs and fixes; memory.md is a per-session action log; token-ledger.json separates measured, estimated and verified usage; hooks/ contains the twelve lifecycle hooks with health heartbeats; and cache/bash/ stores verbatim copies of every condensed Bash output.

The data flow during a session is described step by step in the README. At session start, roughly 400 tokens of project state are injected as pointers rather than content: what each file holds, the top rules, the current handoff. Before reads, duplicate reads get a note and large files get their symbol map so the agent can read a slice instead of the whole file. 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, and file re-prints keep head and tail. The original stays on disk and the delta is recorded. Every 25 tool batches the top rules are repeated in one short note, on the stated reasoning that instruction compliance decays as sessions get longer. On compaction, state, rules and path-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 reached the model.

Two design choices are worth naming. Test and build output is suggested-only by default, because the README says failure detail matters more than tokens. And the condensation is measured at the rewrite point, which is a narrower claim than end-to-end savings.

Installation and the commands you actually type

The quick start is three commands:

npm install -g openwolf cd your-project openwolf init

init detects the agents installed on the machine and wires each of them; after that you use your agents as normal. The CLI surfaces mentioned in the README are openwolf find, which locates any symbol in under 1k tokens according to the project, and openwolf report, which prints the measurement block. The /handoff command regenerates STATUS.md.

Integration is not uniform, and the README is explicit about the tiers. Claude Code gets full support: twelve hooks, the output governor, skills and verified measurement. Codex CLI gets core hooks through .codex/hooks.json plus an AGENTS.md block, covering session, read, write, compaction and stop. OpenCode gets a native plugin plus AGENTS.md, with session and tool before/after events. Cursor, Gemini CLI and Antigravity are context only: a rules file for Cursor, a GEMINI.md block for Gemini CLI, and an AGENTS.md block for Antigravity. Node.js 20 or later is required, per the badge in the README.

The sharing model is git-mediated. .wolf/ ships with a .gitignore that commits conventions, handoff, bug log and index, and ignores machine-local runtime such as ledgers and caches. On Claude Code the learned conventions also sync with native auto-memory in both directions. That last point matters for anyone who wants a single source of truth: on Claude Code, memory has two writers.

What the measurement block does and does not prove

openwolf report prints three groups. The first is measured usage scanned from all project transcripts: API calls, output tokens, cache reads and cache writes. The second is the Bash governor, measured at the rewrite point, with governed calls, original output, tokens that entered context and tokens kept out. The third is cache rebuilds over the last seven days, broken out by cause: model_switch, cache_expired and unattributed, each with an event count and a token figure.

The cache rebuild attribution is the most interesting part, because the README's own comparison table asks who can tell you what broke the prompt cache and answers with model switch, compaction, version change and expiry. The sample output shows two unattributed events in a seven-day window, which tells you the attribution is not total. That is a fair thing to disclose, and it is also the number to watch in your own repository.

The claim that savings are counted only where OpenWolf can prove them is doing real work here. The governor figures are measured at the rewrite point, which is where OpenWolf controls the text, not at the API boundary. Whether the condensed text actually reduced billed input depends on cache behaviour and on how the harness assembled the request. The README does not claim otherwise. Read the report as two different kinds of number: transcript usage, which is read from the harness's records, and governor deltas, which are local measurements at the point of rewriting.

Where OpenWolf is the wrong tool

The integration table is the honest limit. If your work happens in Cursor, Gemini CLI or Antigravity, you get a rules file or a markdown block and nothing else: no hooks, no governor, no verified measurement. The README labels those context only, and that is exactly what it means. The measurement story, which is half the pitch, does not apply there.

On Codex CLI and OpenCode the hooks are described as core, covering session, read, write, compaction and stop. Verified measurement and the output governor are listed under Claude Code's full integration. So a Codex-first or OpenCode-first workflow gets the shared memory and the lifecycle events, but not the same verification of what reached the model. If your reason for adopting OpenWolf is token accounting, the agent you run determines how much of it you get.

The Bash governor has a second limit built into it. Test and build output is suggested-only by default, on the stated grounds that failure detail matters more than tokens. That is the right default for anyone who has watched an agent miss a failing assertion, but it means the governor's savings will be small in repositories where most large output is test runs. Condensation is also per command family, so an unusual command that does not match grep, git show or a file re-print has no described handling. The README does not document a fallback for that case.

There is also a maintenance surface. Twelve hooks with health heartbeats, a .gitignore split between committed state and machine-local runtime, and bidirectional sync with Claude Code's native auto-memory all have to keep working across agent releases. The release cadence in the repository listing shows v2.4.1 on 2026-08-20 and both v2.5.0 and v2.5.1 on 2026-08-29, which suggests active churn in the hook layer. The README does not describe a migration path for .wolf/ state between major versions.

Alternatives and the difference in approach

The obvious alternative is the agents' own memory features. Claude Code has native auto-memory, and OpenWolf does not replace it: the README states that on Claude Code learned conventions sync with native auto-memory in both directions. The difference is scope. Native memory is per-agent and does not travel to Codex or OpenCode, and it does not include the Bash output governor, the anatomy index or the transcript-derived ledger. If you only ever run Claude Code, native memory plus careful prompting covers part of what OpenWolf does, and you avoid the hook layer entirely.

A second alternative is a retrieval or context server that indexes the repository and serves slices on request. That approach puts the index behind a tool call the agent must decide to make, and it typically runs as a separate process. OpenWolf pushes instead: hooks fire on read, write and Bash events without the agent asking, and the index is injected at session start as roughly 400 tokens of pointers. The trade-off is control. A retrieval server lets you query the index yourself and inspect what was returned; OpenWolf's injection happens inside the agent's lifecycle, and your visibility into it comes from the ledger and the hook heartbeats rather than from a query interface.

A third option is to do nothing and accept the cost. That is defensible if your sessions are short, if you use one agent, and if you never hit compaction. The README's own framing, repeated rules every 25 tool batches because compliance decays in long sessions, assumes long sessions. If that is not your workload, the governor and the cadence note are overhead you will not recover.

Licence, upgrades and what to check before adopting

OpenWolf is AGPL-3.0. For a CLI installed globally and run against your own repositories, that is the ordinary case people expect from a copyleft dev tool. The complication is that OpenWolf writes files into your project: cerebrum.md, STATUS.md, buglog.json and the anatomy index are committed to git by design. Those are your content, not the project's code, and the README does not discuss licensing of generated files. If you plan to redistribute OpenWolf inside a product, or to modify the hooks and ship them, read the licence yourself rather than relying on this article. Nothing here is legal advice.

Upgrade cost is concentrated in the hook layer. The repository listing shows three releases inside nine days in August 2026, and the hooks are registered into agent-specific configuration such as .codex/hooks.json. A hook schema change in either OpenWolf or the host agent can leave stale registrations behind. The README does not describe an uninstall or re-init procedure, so the practical check is to look at what init wrote and keep that diff in version control.

The first thing to verify is the split in .wolf/.gitignore: confirm that cerebrum.md, STATUS.md, buglog.json and the index are committed, and that token-ledger.json and cache/bash/ are not. The second is to run openwolf report after a session and check the unattributed count in the cache rebuild section; if most rebuilds are unattributed, the attribution feature is not paying for itself in your setup. The third is to check the hook heartbeats under .wolf/hooks/ against the harness's own record of what fired, which is the verification the README says happens on stop. If those two disagree on Claude Code, the full-integration tier is not working as documented, and the shared-memory half of the tool is the only part you are actually running.

Editorial conclusion

Adopt OpenWolf if you run Claude Code as a primary agent and want conventions, a bug log and a project index to survive session boundaries and reach Codex or OpenCode as well. Do not adopt it if you need verified hook delivery and token attribution on Codex CLI or OpenCode, since the README labels those core hooks only, and do not adopt it if Cursor, Gemini CLI or Antigravity are your main tools, because there the integration is a rules file or a markdown block with no hook layer. Before committing, run openwolf init in a scratch repository and inspect what lands in .wolf/, confirm that .wolf/cache/bash/ and token-ledger.json are gitignored while cerebrum.md, STATUS.md, buglog.json and the index are committed, and check that your agents' hook configuration files were actually written.

Official sources

1. cytostack/openwolf on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases