You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**Persistent memory, token tracking, and context management for Claude Code.**
7
-
_Your Claude subscription shouldn't empty itself in a week._
7
+
<palign="center">
8
+
<strong>A second brain for Claude Code.</strong><br />
9
+
Project intelligence, token tracking, and invisible enforcement through 6 hook scripts. Zero workflow changes.
10
+
</p>
8
11
9
-
## Why OpenWolf Exists
10
-
11
-
Most Claude Code users hit their subscription limits faster than expected. The reason: Claude re-reads files it already saw, forgets corrections between sessions, and scans entire directories when a summary would do. There is no built-in way to see where tokens go or why they're being spent.
Claude Code reads the same file three times in one session and doesn't notice. It forgets the correction you gave it yesterday. It loads your entire codebase to find one function. When the session ends, everything it learned, your naming conventions, the bug it just fixed, the architecture decision you explained, vanishes. Next session, it starts from zero. And you have no idea where your tokens went.
18
+
---
14
19
15
-
OpenWolf fixes the visibility problem. It tracks every token, remembers across sessions, and gives Claude the context it needs without redundant reads.
20
+
## Why OpenWolf Exists
16
21
17
-
## What OpenWolf Does
22
+
Claude Code is powerful but it works blind. It doesn't know what a file contains until it opens it. It can't tell a 50-token config from a 2,000-token module. It reads the same file multiple times in one session without noticing. It has no index of your project, no memory of your corrections, and no awareness of what it already tried.
18
23
19
-
OpenWolf is invisible middleware that hooks into Claude Code's lifecycle. It tracks every file read and write with token estimates. It maintains a learning file - `cerebrum.md` - that accumulates your preferences, corrections, and past mistakes across sessions. It keeps a project structure map - `anatomy.md` - so Claude navigates your codebase without scanning every file. All of this happens automatically through 6 hook scripts. You just type `claude` and work normally.
24
+
OpenWolf gives Claude a second brain: a file index so it knows what files contain before reading them, a learning memory that accumulates your preferencesand past mistakes, and a token ledger that tracks everything. All through 6 invisible hook scripts that fire on every Claude action.
20
25
21
26
## Real Numbers
22
27
23
-
```
24
-
Tested across 20 projects on Windows 11 & Ubuntu 24.04.4 | 132+ sessions | Node v24.13
28
+
Tested on a large active project. Same codebase, same prompts, different setups:
25
29
26
-
Average token reduction: 65.8%
27
-
Repeated reads caught: 71% of all read attempts (106/148 in one project)
30
+
```
31
+
OpenClaw + Claude ██████████████████████████████████████ ~3.4M tokens
32
+
Claude CLI (no OpenWolf) ████████████████████████████████ ~2.5M tokens
33
+
OpenWolf + Claude CLI ████████ ~425K tokens
28
34
```
29
35
30
-
These are numbers from real projects, not benchmarks. Your results will vary by project size and usage patterns.
36
+
**OpenWolf saved ~80% of tokens** compared to bare Claude CLI on the same project.
37
+
38
+
Across 20 projects, 132+ sessions: average token reduction of 65.8%, with 71% of repeated file reads caught and blocked. These are numbers from real usage, not benchmarks. Your results will vary by project size and usage patterns.
31
39
32
40
## Quick Start
33
41
@@ -39,27 +47,25 @@ openwolf init
39
47
40
48
That's it. Use `claude` normally. OpenWolf is watching.
41
49
42
-
`openwolf init` creates a `.wolf/` directory:
50
+
## What It Creates
43
51
44
-
```
45
-
.wolf/
46
-
├── OPENWOLF.md Instructions Claude follows every session
47
-
├── cerebrum.md Learns your preferences, remembers corrections
48
-
├── memory.md Logs every action with token estimates
49
-
├── anatomy.md Project file map - AI navigates without scanning
|`token-ledger.json`| Lifetime token tracking and session history |
61
+
|`hooks/`| 6 Claude Code lifecycle hooks (pure Node.js) |
62
+
|`config.json`| Configuration with sensible defaults |
63
+
|`identity.md`| Agent persona for this project |
64
+
|`OPENWOLF.md`| Instructions Claude follows every session |
59
65
60
66
## How It Works
61
67
62
-
When you ask Claude to read a file, OpenWolf checks if it was already read this session. If yes, it warns Claude. When Claude writes code, OpenWolf checks your `cerebrum.md` for known mistakes. After every write, it auto-updates the project map. When the session ends, it logs everything to the token ledger. You see none of this. It just happens.
68
+
Before Claude reads a file, OpenWolf tells it what the file contains and how large it is. If Claude already read that file this session, OpenWolf warns it. Before Claude writes code, OpenWolf checks your `cerebrum.md` for known mistakes. After every write, it auto-updates the project map and logs token usage. You see none of this. It just happens.
<summary><strong>cerebrum.md</strong> - the learning memory</summary>
88
94
89
-
This is the "wow" feature. Claude updates this file when you correct it, express a preference, or make a decision. The Do-Not-Repeat list prevents the same mistake across sessions.
95
+
Claude updates this file when you correct it, express a preference, or make a decision. The Do-Not-Repeat list prevents the same mistake across sessions.
90
96
91
97
```markdown
92
98
## Do-Not-Repeat
@@ -104,8 +110,8 @@ This is the "wow" feature. Claude updates this file when you correct it, express
104
110
## Key Learnings
105
111
106
112
- This project uses pnpm workspaces with strict hoisting
107
-
- The gateway WebSocket server runs on port 18789
108
-
-`tsdown` dead-code-eliminates process.env.NODE_ENV at build time
113
+
- The API rate limiter uses a sliding window, not fixed buckets
114
+
-Auth middleware reads from env.JWT_SECRET, not config file
109
115
```
110
116
111
117
</details>
@@ -137,14 +143,14 @@ Every session gets a line item. Lifetime totals tell you if OpenWolf is actually
137
143
```json
138
144
{
139
145
"lifetime": {
140
-
"total_tokens_estimated": 142800,
146
+
"total_tokens_estimated": 503978,
141
147
"total_reads": 287,
142
-
"total_writes": 94,
143
-
"total_sessions": 44,
148
+
"total_writes": 269,
149
+
"total_sessions": 15,
144
150
"anatomy_hits": 198,
145
151
"anatomy_misses": 89,
146
152
"repeated_reads_blocked": 106,
147
-
"estimated_savings_vs_bare_cli": 34200
153
+
"estimated_savings_vs_bare_cli": 2066959
148
154
}
149
155
}
150
156
```
@@ -177,7 +183,7 @@ openwolf status Show health, stats, file integrity
@@ -192,21 +198,21 @@ openwolf restore [backup] Restore .wolf/ from a timestamped backup
192
198
193
199
## Design QC
194
200
195
-
Capture full-page screenshots of your running app and let Claude evaluate the design - no separate API key needed.
201
+
Capture full-page screenshots of your running app and let Claude evaluate the design.
196
202
197
203
```bash
198
204
openwolf designqc
199
205
```
200
206
201
-
OpenWolf auto-detects your dev server (or starts one from `package.json`), captures viewport-height JPEG sections of every route, and saves them to `.wolf/designqc-captures/`. Then tell Claude to read the screenshots and evaluate. Requires `puppeteer-core` (`npm install puppeteer-core`).
207
+
Auto-detects your dev server, captures viewport-height JPEG sections of every route, and saves them to `.wolf/designqc-captures/`. Then tell Claude to read the screenshots and evaluate. Requires `puppeteer-core`.
202
208
203
209
## Reframe
204
210
205
-
Ask Claude to help you pick a UI framework. OpenWolf ships a curated knowledge base of 12 frameworks (shadcn/ui, Aceternity, Magic UI, DaisyUI, HeroUI, Chakra, Flowbite, Preline, Park UI, Origin UI, Headless UI, Cult UI) with battle-tested migration prompts. No CLI command needed - Claude reads `.wolf/reframe-frameworks.md`, asks you a few questions, and executes the migration with the right prompt for your project.
211
+
Ask Claude to help you pick a UI framework. OpenWolf ships a curated knowledge base of 12 frameworks (shadcn/ui, Aceternity, Magic UI, DaisyUI, HeroUI, Chakra, Flowbite, Preline, Park UI, Origin UI, Headless UI, Cult UI) with battle-tested migration prompts. Claude reads `.wolf/reframe-frameworks.md`, asks you a few questions, and executes the migration with the right prompt for your project.
206
212
207
213
## How OpenWolf Compares
208
214
209
-
OpenWolf is a `.wolf/` directory with 6 hook scripts and a learning protocol. It doesn't run your AI for you. It doesn't replace your workflow. It gives Claude Code two things it doesn't have: a memory that survives between sessions, and a budget you can see. If you want an AI operating system, look elsewhere. If you want your AI assistant to stop re-reading the same file four times and forgetting what you told it yesterday, this is that.
215
+
OpenWolf is not an AI wrapper. It is 6 hook scripts and a `.wolf/` directory. It doesn't run your AI for you or change your workflow. It gives Claude Code what it lacks: a project map so it reads less, a memory so it learns faster, and a ledger so you see where tokens go.
210
216
211
217
## Requirements
212
218
@@ -218,14 +224,14 @@ OpenWolf is a `.wolf/` directory with 6 hook scripts and a learning protocol. It
218
224
219
225
## Limitations
220
226
221
-
- Claude Code hooks are a relatively new feature. `PreToolUse`/`PostToolUse` have had reliability issues in some Claude Code versions. OpenWolf falls back to `CLAUDE.md` instructions when hooks don't fire.
227
+
- Claude Code hooks are a relatively new feature. OpenWolf falls back to `CLAUDE.md` instructions when hooks don't fire.
222
228
- Token tracking is estimation-based (character-to-token ratio), not exact API counts. Accurate to within ~15%.
223
-
-`cerebrum.md` depends on the AI following instructions to update it after corrections. Compliance is ~85-90%, not 100%.
224
-
- This is v1.0.0. Things may break. [File issues](https://github.com/cytostack/openwolf/issues).
229
+
-`cerebrum.md` depends on Claude following instructions to update it after corrections. Compliance is ~85-90%, not 100%.
230
+
- This is v1.0.4. Things may break. [File issues](https://github.com/cytostack/openwolf/issues).
225
231
226
232
## Origin Story
227
233
228
-
We were building products with Claude Code at Cytostack when we noticed something off. Sessions were eating through tokens faster than they should. When we dug in, we found Claude re-reading the same files multiple times, forgetting corrections from an hour ago, and scanning entire directories to find one function. There was no way to see where tokens went or why. So we built the tooling we wished existed — a persistent memory layer, a project map that eliminates redundant reads, and a ledger that tracks every token. That became OpenWolf.
234
+
We were building products with Claude Code at Cytostack when we noticed something off. Sessions were eating through tokens faster than they should. When we dug in, we found Claude re-reading the same files multiple times, scanning entire directories to find one function, and having no way to know what a file contained without opening it. There was no project map, no read awareness, no token visibility. So we built the tooling we wished existed -- a file index so Claude reads less, a learning memory so it gets smarter, and a ledger that tracks every token. That became OpenWolf.
Copy file name to clipboardExpand all lines: docs/.vitepress/config.ts
+5-5Lines changed: 5 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ import tailwindcss from "@tailwindcss/vite";
4
4
exportdefaultdefineConfig({
5
5
title: "OpenWolf",
6
6
description:
7
-
"Open-source middleware for Claude Code that tracks tokens, remembers preferences, and catches repeated mistakes. 65% average token reduction across 132+ sessions.",
7
+
"Open-source middleware for Claude Code. Project intelligence, persistent memory, and token tracking through invisible hooks. 65% average token reduction.",
content: "OpenWolf: Sharper Context, Fewer Tokens for Claude Code",
41
+
content: "OpenWolf -- A Second Brain for Claude Code",
42
42
},
43
43
],
44
44
[
45
45
"meta",
46
46
{
47
47
property: "og:description",
48
48
content:
49
-
"Open-source middleware that tracks every token, remembers your preferences across sessions, and catches repeated mistakes. 65% average token reduction.",
49
+
"Open-source hooks that give Claude Code project intelligence, token tracking, and mistake prevention. 2M+ tokens saved across real projects.",
50
50
},
51
51
],
52
52
// Twitter Card
@@ -55,15 +55,15 @@ export default defineConfig({
55
55
"meta",
56
56
{
57
57
name: "twitter:title",
58
-
content: "OpenWolf: Sharper Context, Fewer Tokens for Claude Code",
58
+
content: "OpenWolf -- A Second Brain for Claude Code",
59
59
},
60
60
],
61
61
[
62
62
"meta",
63
63
{
64
64
name: "twitter:description",
65
65
content:
66
-
"Open-source middleware that tracks every token, remembers your preferences across sessions, and catches repeated mistakes. 65% average token reduction.",
66
+
"Open-source hooks that give Claude Code project intelligence, token tracking, and mistake prevention. 2M+ tokens saved across real projects.",
0 commit comments