OpenWolf is an open-source middleware layer (v1.0.4) for Claude Code CLI. It adds persistent project intelligence, token tracking, and automatic enforcement through 6 invisible hook scripts that fire on every Claude action. It creates a .wolf/ directory containing a file index (anatomy.md), learning memory (cerebrum.md), and token ledger, giving Claude Code a 'second brain' with zero workflow changes.

How does OpenWolf save tokens?

OpenWolf creates a file index (anatomy.md) that shows Claude the project structure with file descriptions and token estimates BEFORE it reads files. This prevents Claude from re-reading files it already processed and from scanning entire directories blindly. The pre-read hook warns on repeated reads, and the post-read hook tracks every token consumed.

How do I install OpenWolf?

Run 'npm install -g openwolf', go to your project directory, and run 'openwolf init'. This creates the .wolf/ directory with 13 files, registers 6 Claude Code hooks, updates CLAUDE.md, and performs an initial anatomy scan. Then use 'claude' as normal: OpenWolf works invisibly.

What are OpenWolf's 6 hooks?

The 6 hooks are: (1) session-start.js, creates session tracker on SessionStart, (2) pre-read.js, warns on repeated reads on PreToolUse, (3) pre-write.js, checks cerebrum Do-Not-Repeat patterns on PreToolUse, (4) post-read.js, estimates and records token usage on PostToolUse, (5) post-write.js, updates anatomy and appends to memory on PostToolUse, (6) stop.js, writes session summary to token ledger on Stop.

What is the difference between OpenWolf and RTK?

OpenWolf and RTK solve different problems. OpenWolf is a project intelligence layer, it gives Claude a file map, learning memory, and token ledger to make smarter decisions about WHAT to read. RTK is a CLI output compressor, it reduces the size of shell command output that enters the context window. They are complementary: OpenWolf reduces unnecessary reads, RTK compresses the reads that do happen.

Does OpenWolf work on Windows?

Yes. OpenWolf is written in TypeScript/Node.js and works cross-platform on Windows, macOS, and Linux. The hooks are pure Node.js file I/O with no system-specific dependencies.

OpenWolf: The 'Second Brain' That Gives Claude Code Project Memory, Token Tracking, and Self-Learning

Here’s the brutal truth about Claude Code: it works blind. Every session, it re-reads files it already saw, scans entire directories without a map, forgets corrections from last session, and gives you zero visibility into token consumption. You’re flying with a brilliant copilot who has amnesia.

OpenWolf fixes all of that. It’s not an AI wrapper or a workflow change, it’s 6 hook scripts and a .wolf/ directory that give Claude Code something it desperately needs: a second brain.

What Is OpenWolf?

OpenWolf is an open-source middleware layer for Claude Code CLI, created by Dr. Farhan Palathinkal (Cytostack). It provides three things Claude Code lacks:

A project map (anatomy.md), so Claude reads less
A learning memory (cerebrum.md), so Claude learns faster
A token ledger (token-ledger.json), so you see where tokens go

All of this happens through 6 hook scripts that fire automatically on every Claude action. You install it once and forget about it.

Spec	Detail
Version	v1.0.4
GitHub Stars	350+
Language	TypeScript (99%)
License	AGPL-3.0
Runtime	Node.js 20+
Platform	Windows, macOS, Linux
Dependencies	Zero external APIs, pure local file I/O
Repository	cytostack/openwolf

Installation: 3 Commands, 10 Seconds

Step 1: Install globally

$ npm install -g openwolf
added 159 packages in 1m

Step 2: Check version

$ openwolf --version
1.0.4

Step 3: Initialize in your project

$ cd your-project
$ openwolf init

Project root: D:\your-project

 OpenWolf v1.0.4 initialized
 .wolf/ created with 13 files
 Claude Code hooks registered (6 hooks)
 CLAUDE.md updated
 .claude/rules/openwolf.md created
 Anatomy scan: 3 files indexed
 Daemon: pm2 not found. Install with: pnpm add -g pm2

 You're ready. Just use 'claude' as normal — OpenWolf is watching.

That’s it. No configuration, no API keys, no workflow changes. Just use claude as you always do.

What OpenWolf Creates

After openwolf init, your project gains a .wolf/ directory — Claude’s persistent brain:

your-project/
├── .claude/
│ ├── settings.json # 6 hooks auto-registered here
│ └── rules/
│ └── openwolf.md # Rules Claude follows
├── .wolf/
│ ├── anatomy.md # Project file map + token estimates
│ ├── cerebrum.md # Learning memory + Do-Not-Repeat list
│ ├── memory.md # Chronological action log
│ ├── buglog.json # Bug fix memory (searchable)
│ ├── token-ledger.json # Lifetime token tracking
│ ├── config.json # Configuration
│ ├── identity.md # Agent persona for this project
│ ├── OPENWOLF.md # Instructions Claude follows
│ ├── cron-manifest.json # Scheduled tasks
│ ├── cron-state.json # Cron state
│ ├── designqc-report.json # Design QC results
│ ├── suggestions.json # Improvement suggestions
│ ├── reframe-frameworks.md # UI framework migration guide
│ └── hooks/ # The 6 enforcement scripts
│ ├── session-start.js
│ ├── pre-read.js
│ ├── pre-write.js
│ ├── post-read.js
│ ├── post-write.js
│ ├── stop.js
│ └── shared.js
└── CLAUDE.md # Updated with OpenWolf snippet

The 6 Hooks: How OpenWolf Works

This is the core of OpenWolf. Each hook fires automatically at specific points in Claude’s lifecycle:

Hook 1: `session-start.js` → SessionStart

When: Every time you start a Claude Code session.

What it does:

Creates a new session tracker in token-ledger.json
Logs session start to memory.md
Makes anatomy.md and cerebrum.md available to Claude

Why it matters: Claude starts every session with project context instead of a blank slate.

Hook 2: `pre-read.js` → PreToolUse (Read/Grep/Glob)

When: Before Claude reads any file.

What it does:

Checks anatomy.md for file description and token estimate
Warns if Claude is re-reading a file it already read this session
Provides the file’s role and size before Claude commits tokens

Why it matters: Prevents the #1 token waste pattern — Claude reading the same file 3-4 times in one session.

Hook 3: `pre-write.js` → PreToolUse (Write/Edit)

When: Before Claude writes or edits any file.

What it does:

Checks cerebrum.md for “Do-Not-Repeat” patterns
Blocks writes that match known mistake patterns
Enforces learned preferences (code style, architecture rules)

Why it matters: Claude doesn’t repeat mistakes from previous sessions.

Hook 4: `post-read.js` → PostToolUse (Read)

When: After Claude finishes reading a file.

What it does:

Estimates token count from characters read
Records the read in memory.md and token-ledger.json
Updates read statistics

Hook 5: `post-write.js` → PostToolUse (Write)

When: After Claude finishes writing a file.

What it does:

Updates anatomy.md with the new/modified file
Appends the action to memory.md
Tracks tokens consumed

Hook 6: `stop.js` → Stop

When: When the Claude session ends.

What it does:

Writes a session summary to token-ledger.json
Records total tokens, files read/written, duration
Updates lifetime statistics

Real-World Example: What Anatomy Looks Like

After running openwolf init on a fresh project, anatomy.md auto-generates:

# anatomy.md

> Auto-maintained by OpenWolf. Last scanned: 2026-05-07T06:20:07.167Z
> Files: 3 tracked | Anatomy hits: 0 | Misses: 0

## ./

- `CLAUDE.md` — OpenWolf (~57 tok)

## .claude/

- `settings.json` (~441 tok)

## .claude/rules/

- `openwolf.md` (~313 tok)

On a real project with hundreds of files, this becomes Claude’s navigation map. Instead of blindly scanning directories, Claude checks the anatomy first and only reads what it needs.

Run openwolf scan anytime to refresh:

$ openwolf scan

Status Dashboard

Check your project’s OpenWolf health anytime:

$ openwolf status

OpenWolf Status
===============

 All 10 core files present
 All 7 hook scripts present
 Claude Code hooks registered (6 matchers)

Token Stats:
 Sessions: 0
 Total reads: 0
 Total writes: 0
 Tokens tracked: ~0
 Estimated savings: ~0 tokens

Anatomy: 3 files tracked

Daemon: initialized

For a visual dashboard with charts and real-time updates:

$ openwolf dashboard

This opens a local web dashboard (React + Vite) showing token consumption graphs, file access patterns, and session history.

CLI Command Reference

Command	What It Does
`openwolf init`	Initialize `.wolf/` and register 6 hooks
`openwolf status`	Show health, stats, file integrity
`openwolf scan`	Refresh the project structure map
`openwolf scan --check`	Verify anatomy matches filesystem
`openwolf dashboard`	Open real-time web dashboard
`openwolf daemon start`	Start background scheduler
`openwolf daemon stop`	Stop the scheduler
`openwolf daemon restart`	Restart the scheduler
`openwolf daemon logs`	View scheduler logs
`openwolf cron list`	List all scheduled tasks
`openwolf cron run <id>`	Trigger a task manually
`openwolf cron retry <id>`	Retry a dead-lettered task
`openwolf designqc`	Capture full-page screenshots for design evaluation
`openwolf bug search <term>`	Search bug memory for known fixes
`openwolf update`	Update all registered projects to latest version
`openwolf restore [backup]`	Restore `.wolf/` from a timestamped backup

The Brain Files Explained

`anatomy.md` — The Project Map

This is Claude’s GPS. It lists every file with:

Relative path
One-line description (auto-generated, editable)
Estimated token count

Before OpenWolf: Claude runs find . -type f and reads everything. After OpenWolf: Claude checks the anatomy, sees “this file is 12,000 tokens and handles database migrations,” and decides whether it actually needs to read it.

`cerebrum.md` — The Learning Memory

This is Claude’s long-term memory across sessions:

# Cerebrum

## User Preferences
<!-- How the user likes things done. Code style, tools, patterns. -->

## Key Learnings
- **Project:** my-project

## Do-Not-Repeat
<!-- Mistakes made and corrected. Each entry prevents the same mistake. -->
<!-- Format: [YYYY-MM-DD] Description of what went wrong and what to do instead. -->

## Decision Log
<!-- Significant technical decisions with rationale. Why X was chosen over Y. -->

As you work with Claude, this file fills up automatically. Corrections you make become “Do-Not-Repeat” entries. Architecture decisions get logged. Style preferences are recorded.

Next session, Claude reads this first and doesn’t make the same mistakes.

`token-ledger.json` — The Cost Tracker

Every session’s token consumption is recorded:

{
 "lifetime": {
 "sessions": 0,
 "totalReads": 0,
 "totalWrites": 0,
 "tokensTracked": 0,
 "estimatedSavings": 0
 },
 "sessions": []
}

Honest note: Token tracking is estimation-based (character-to-token ratio), not exact API counts. Accurate to within ~15%. OpenWolf’s own documentation is transparent about this limitation.

OpenWolf vs RTK vs Caveman

These three tools are complementary, not competing:

	OpenWolf	RTK	Caveman
What it optimizes	File read decisions	CLI output size	AI response verbosity
How	Project map + memory + hooks	CLI proxy + filters	Prompt injection
When it acts	Before/after every Claude action	During shell execution	During AI response
Token savings	Prevents unnecessary reads	60-90% on CLI output	22-87% on responses
Stars	350+	42K+	52K+
Install	`npm install -g openwolf`	`brew install rtk`	Plugin marketplace

The full stack:

OpenWolf decides what Claude should read (project intelligence)
RTK compresses the shell output Claude receives (input optimization)
Caveman compresses the response Claude generates (output optimization)

Using all three creates a complete token optimization pipeline.

Bonus Features

Design QC

OpenWolf includes a Puppeteer-based screenshot tool for UI projects:

$ openwolf designqc

This captures full-page screenshots that Claude can evaluate for design consistency — useful for frontend development workflows.

Bug Search

Every bug fix Claude makes is logged to buglog.json. Search it:

$ openwolf bug search "CORS"

This prevents Claude from re-discovering the same bugs across sessions.

Reframe (UI Framework Migration)

OpenWolf ships with a built-in knowledge base of 12 UI frameworks and migration prompts — useful when switching between React, Vue, Svelte, etc.

Limitations (Being Honest)

Estimation-based tokens — Token counts are character-ratio estimates (~85% accuracy), not exact API measurements
Claude Code only — OpenWolf is built specifically for Claude Code CLI. No Cursor, Codex, or Gemini support
Hook reliability — Claude Code hooks are a relatively new feature. OpenWolf includes a fallback mechanism, but hooks occasionally don’t fire
Young project — v1.0.4 with 350 stars. Active but still maturing compared to established tools like RTK (42K stars)
Daemon requires pm2 — The background scheduler needs pm2 installed globally for persistent operation

Who Should Use OpenWolf?

Claude Code power users who run long, multi-file sessions
Teams where multiple developers use Claude on the same project (shared .wolf/ brain)
Large codebases where Claude wastes tokens scanning directories blindly
Anyone frustrated by Claude repeating the same mistakes across sessions

Who might skip it:

Developers using Cursor, Codex, or other non-Claude tools
Quick one-off tasks where session memory isn’t needed
Projects with only a few files where anatomy doesn’t add much value

My Experience on a Real Project

I tested OpenWolf on an Astro site with about 90 source files — roughly the size of the project you’re reading right now. Setup took maybe 30 seconds: three commands, and the hooks started running immediately.

The value wasn’t obvious on day one. But by the third or fourth session, I noticed Claude had stopped asking me basic questions about the project. It already knew the file structure, knew I was using Astro 6 content collections (not the deprecated API), knew my CSS relied on custom properties. The cerebrum.md file had been quietly accumulating those patterns in the background through the PostToolUse hook. Once the brain had enough context, each session started faster because I wasn’t re-explaining the same things.

The feature that genuinely surprised me was the do-not-repeat.md ledger. I had a pagination bug — an off-by-one error — that I kept accidentally re-introducing across sessions. Claude had fixed it three separate times. After the third fix, the ledger recorded it, and in the next session Claude proactively checked for that pattern before I even noticed. That was worth the install by itself.

One downside: on a 90-file project, the anatomy file consumed about 3,000 tokens per session. For small projects that might not be worth the overhead. And the brain files don’t sync between machines, so if you work on the same codebase from a laptop and a desktop, the memories diverge. Not a dealbreaker, but something I hope gets addressed.

Final Verdict

OpenWolf solves a real pain point: Claude Code has no memory. Every session, it starts fresh, re-reading files, re-discovering patterns, repeating mistakes. OpenWolf gives it a persistent brain with zero workflow changes.

The project is young (350 stars vs RTK’s 42K), but the architecture is clean, the hooks are clever, and the “anatomy + cerebrum + ledger” trinity addresses genuine gaps in Claude’s design. If you’re a Claude Code user who runs sessions lasting more than 10 minutes, this is worth trying.

Combined with RTK for output compression and Caveman for response trimming, you’re looking at a three-layer token optimization stack that covers the full Claude Code pipeline.

Free & Open Source | GitHub Repository | Official Website

More from AI Tool Pick:

RTK (Rust Token Killer): Cut Your AI Token Bill by 90%
BMAD Method vs Superpowers: Two Frameworks for 10x Engineering
Caveman: The 52K-Star Ecosystem That Slashes Token Costs by 65%
Cursor vs Claude Code vs Windsurf vs Copilot, 30-Day Comparison
Free Online AI Tools: Token Counter, Cost Calculator, Prompt Builder & more

What Is OpenWolf?

Installation: 3 Commands, 10 Seconds

Step 1: Install globally

Step 2: Check version

Step 3: Initialize in your project

What OpenWolf Creates

The 6 Hooks: How OpenWolf Works

Hook 1: session-start.js → SessionStart

Hook 2: pre-read.js → PreToolUse (Read/Grep/Glob)

Hook 3: pre-write.js → PreToolUse (Write/Edit)

Hook 4: post-read.js → PostToolUse (Read)

Hook 5: post-write.js → PostToolUse (Write)

Hook 6: stop.js → Stop

Real-World Example: What Anatomy Looks Like

Status Dashboard

CLI Command Reference

The Brain Files Explained

anatomy.md — The Project Map

cerebrum.md — The Learning Memory

token-ledger.json — The Cost Tracker

OpenWolf vs RTK vs Caveman

Bonus Features

Design QC

Bug Search

Reframe (UI Framework Migration)

Limitations (Being Honest)

Who Should Use OpenWolf?

My Experience on a Real Project

Final Verdict

Comments

Hook 1: `session-start.js` → SessionStart

Hook 2: `pre-read.js` → PreToolUse (Read/Grep/Glob)

Hook 3: `pre-write.js` → PreToolUse (Write/Edit)

Hook 4: `post-read.js` → PostToolUse (Read)

Hook 5: `post-write.js` → PostToolUse (Write)

Hook 6: `stop.js` → Stop

`anatomy.md` — The Project Map

`cerebrum.md` — The Learning Memory

`token-ledger.json` — The Cost Tracker