# OpenWolf: Shared Project Memory Across Claude Code, Codex and OpenCode

> OpenWolf installs lifecycle hooks into coding agents so one .wolf/ directory carries conventions, bug history and a project index between tools, and reports token usage read from the harness transcript. Here is how to install it, what the hooks actually do, and where it stops being the right choice.

**cytostack/openwolf** — Portable project memory across Claude Code, Codex and OpenCode, plus token accounting measured from harness transcripts. Local file I/O, no API calls, no telemetry.

- Repository: https://github.com/cytostack/openwolf
- Website: https://openwolf.com
- Stars: 2,367 · Forks: 215
- Language: TypeScript
- License: AGPL-3.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/cytostack-openwolf

## The problem OpenWolf targets: agent memory that dies with the session

A coding agent starts each session cold. It re-reads files it has already seen, re-learns conventions you explained last week, and forgets what it was in the middle of when context compaction runs. The README's own framing is blunt about the second half of the problem: token usage arrives as a monthly invoice with no line items, and when the prompt cache breaks, nobody can say whether the cause was a model switch, a compaction, a version change or expiry.

OpenWolf is aimed at engineers who run more than one agent against the same repository. The README lists Claude Code, Codex CLI and OpenCode as supported harnesses, with Cursor, Gemini CLI and Antigravity receiving context only. If you use exactly one agent and never switch, the cross-tool argument does not apply to you, and the remaining value is the Bash output governor and the token report. That is a narrower pitch, and the README does not pretend otherwise: the comparison table leads with agents learning your project separately, and with switching agents meaning you lose what the last one learned.

## How the .wolf/ directory and its hooks work

The mechanism is a directory, not a service. The README states that `openwolf init` creates `.wolf/` and registers hooks with your agent, and that the hooks are plain Node.js scripts with no network, no AI calls and no dependencies. The repository layout backs that up: `src/`, `bin/`, `tests/`, a `tsconfig.hooks.json` separate from the main `tsconfig.json`, and a `dist/bin/openwolf.js` entry point declared in `package.json`. The hooks are compiled separately from the CLI, which fits the claim that they run as standalone scripts.

Inside `.wolf/`, the README names files with distinct jobs. `anatomy-index.json` holds 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 memory of bugs and fixes. `memory.md` is a per-session action log, `token-ledger.json` holds measured, estimated and verified usage, `hooks/` holds the twelve lifecycle hooks with health heartbeats, and `cache/bash/` keeps verbatim copies of every condensed Bash output.

The session flow is documented in order. At session start a roughly 400-token index is injected: what each file holds, the top rules, the current handoff. Before reads, duplicate reads get a note and large files get a symbol map so the agent can read a slice. After Bash, output over 2,000 tokens is condensed by command family, with grep floods keeping the first matches per file plus counts, `git show` keeping the header and diff stats, and file re-prints keeping head and tail. Every 25 tool batches the top rules are repeated in one short note, on the argument that instruction compliance decays as sessions get longer. On compaction, state, rules and scoped instructions are re-injected. On stop, the ledger records usage per model and verifies against the transcript which hooks fired, which failed, and which injected context reached the model.

Two design choices stand out. The governor keeps the original text on disk with a pointer rather than discarding it, and test and build output is suggested-only by default because failure detail matters more than tokens. That is a sensible boundary, and it also means the headline savings do not come from the place where context usually explodes.

## Installing OpenWolf and running a first session

The README's quick start is three commands. The package requires Node.js 20 or newer, per the `engines` field in `package.json`, and it installs globally from npm.

```bash
npm install -g openwolf
cd your-project
openwolf init
```

The README states that `init` detects which agents are installed on your machine and wires each of them. After that you use your agents normally. There is no separate daemon to start and no configuration file to hand-write for the default path; the wiring is the point of the command.

To see what a session cost, run the report command. The README shows the shape of the output: measured API calls, output tokens, cache reads and cache writes across all project transcripts, a Bash governor block with original output, tokens that entered context and tokens kept out, and a cache rebuild section broken down by cause such as `model_switch`, `cache_expired` and `unattributed`.

```bash
openwolf report
```

The README also documents `openwolf find`, which locates a symbol using the project index and is described as staying under 1k tokens. The README does not document a rollback command for `openwolf init`, so if you want to know what the command changes in your agent configuration, read the diff it produces before committing anything.

## What the integration table does not promise

The support tiers are not cosmetic. Claude Code gets full integration: twelve hooks, the output governor, skills and verified measurement. Codex CLI gets core hooks through `.codex/hooks.json` plus `AGENTS.md`, covering session, read, write, compaction and stop. OpenCode gets a native plugin plus `AGENTS.md` with session and tool before/after. Cursor, Gemini CLI and Antigravity get context only, through a rules file, a `GEMINI.md` block and an `AGENTS.md` block respectively.

Read that as a real limitation. On the context-only harnesses you get the shared `.wolf/` state and nothing that intercepts Bash output or verifies hook delivery, because there are no hooks to intercept with. The token accounting the README leads with is measured from the harness transcript, so it is only as complete as the harness integration allows. If your team standardised on Cursor, most of what makes OpenWolf interesting is unavailable to you.

A second boundary sits in the governor itself. Output over 2,000 tokens is condensed by command family, and test and build output is suggested-only by default. That default is defensible, but it means the tool deliberately declines to compress the output most likely to be huge, and the README does not describe an override for that behaviour. The `cache/bash/` directory exists precisely because condensation is lossy at the point of context, even though the original is preserved on disk.

## OpenWolf compared with a plain AGENTS.md and a rules file

The obvious alternative is what most teams already do: write an `AGENTS.md` or a rules file and let each agent read it. That approach is stateless. The file holds what you remembered to write down, it does not record which bugs you already fixed, it does not index symbols, and it cannot tell you that a `grep -rn` just pushed 40,000 tokens into the session. It also does not survive compaction, because nothing re-injects it when the platform drops context.

OpenWolf's difference is that memory is written during the session rather than before it. Corrections, conventions and bug fixes go to files, and the README states those files travel through git and reach every agent and teammate. The `.wolf/` directory ships with a `.gitignore` that commits conventions, handoff, bug log and index while ignoring machine-local runtime such as ledgers and caches. That split is the actual design decision: shared knowledge is versioned, per-machine measurement is not.

The cost is a second source of truth. You now maintain `.wolf/cerebrum.md` alongside whatever your team already keeps, and on Claude Code the README says learned conventions sync with native auto-memory in both directions. Bidirectional sync between two stores is the kind of thing that works until it does not, and the README does not describe conflict resolution when both sides change.

## Maintenance, releases and the AGPL-3.0 licence

The repository is not archived. The last push was on 2026-08-29, and the release history is tight: v2.4.1 on 2026-08-20, then v2.5.0 and v2.5.1 on 2026-08-29. A `CHANGELOG.md`, a `RELEASE_NOTES_2.0.0.md` and a `docs/` directory with VitePress scripts are present, so upgrade notes have somewhere to live. The project is published on npm as `openwolf`, and `package.json` pins the licence to `AGPL-3.0-only` under author Cytostack Pvt Ltd.

AGPL-3.0 is the constraint worth pausing on. It is a strong copyleft licence, and the network clause is the part that catches people: if you modify OpenWolf and let users interact with it over a network, the licence's terms reach that deployment. Running the CLI locally on your own repository is a different situation from embedding the hooks in a product you ship. This is not legal advice, and the practical step is to have whoever handles licensing at your company read `LICENSE` before the tool becomes part of a distributed build.

Upgrade cost is harder to judge from the repository alone. The hooks are compiled separately through `tsconfig.hooks.json` and registered inside your agents' configuration, so a version bump can change both the hook scripts and the registration. The README does not document a migration path between major versions, which is why the repository's `CHANGELOG.md` is the file to read before bumping.

## Where OpenWolf is the wrong tool

If your sessions are short and your repository is small, the ~400-token index injected at session start plus the periodic rule notes are overhead you will pay on every session to solve a problem you do not have. The governor's threshold sits at 2,000 tokens of Bash output, and on a small codebase you may rarely cross it, which leaves the shared memory as the only benefit and the token ledger as a curiosity.

If your debugging depends on reading raw command output, the condensation is a liability even with the original on disk, because the agent sees the condensed version and the pointer, not the full text. The README is explicit that test and build output is suggested-only by default for exactly this reason, which is an admission that compression and diagnosis pull in opposite directions.

And if your agents are not Claude Code, Codex CLI or OpenCode, you are on the context-only tier. You would be adopting a token governor that does not govern and a measurement layer that cannot verify hook delivery, because there are no hooks on those harnesses to fire.

## Conclusion

Adopt OpenWolf if you switch between Claude Code, Codex CLI and OpenCode on the same repository and want conventions, bug history and a symbol index to survive the switch, or if you need per-session token numbers instead of a monthly invoice. Skip it if your work is a single agent on a small codebase, if your build and test output is the material you most need verbatim, or if AGPL-3.0 does not fit how you ship. Before wiring it into a real project, run openwolf init in a throwaway repository, run openwolf report after one session, and read .wolf/.gitignore to see exactly which files would be committed and which stay machine-local.

## FAQ

### How do I install OpenWolf?

Install it globally from npm with npm install -g openwolf, then run openwolf init inside your project directory. The README states that init detects the agents installed on your machine and wires each of them. Node.js 20 or newer is required.

### How do I add OpenWolf to Claude Code?

Running openwolf init in your project wires Claude Code automatically, since it is listed as the full integration with twelve hooks, the output governor and verified measurement. All supported agents share the same .wolf/ directory afterwards.

### What is OpenWolf?

OpenWolf is a CLI that keeps one project memory across Claude Code, Codex and OpenCode in a .wolf/ directory, condenses oversized Bash output before it enters context, and reports token usage measured from the harness transcript. The README states it uses pure local file I/O with no API calls and no telemetry.

### Is OpenWolf safe to run?

The README states the hooks are plain Node.js scripts with no network, no AI calls and no dependencies, and that the tool performs pure local file I/O with no telemetry. Condensed Bash output is preserved verbatim under .wolf/cache/bash/. The README does not document a rollback command for openwolf init, so review the configuration changes it makes.

### What is a good OpenWolf alternative?

The low-tech alternative is a hand-written AGENTS.md or rules file per agent. It is stateless: it does not record bug fixes, index symbols, re-inject rules after compaction, or report token usage. OpenWolf's difference is that memory is written during the session and shared through git via .wolf/.

## Sources

- [cytostack/openwolf on GitHub](https://github.com/cytostack/openwolf)
- [License: AGPL-3.0](https://github.com/cytostack/openwolf/blob/main/LICENSE)
- [Project website](https://openwolf.com)
- [README](https://github.com/cytostack/openwolf/blob/main/README.md)
- [Releases](https://github.com/cytostack/openwolf/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cytostack-openwolf