The Problem
Coding agents operate blind. They reread files they already saw, read whole files to find a single function, and lose session state when context compacts. Each wasted read costs tokens directly, and there is no visibility into where the budget went.
What This Does
OpenWolf is middleware that gives coding agents a persistent "second brain." It maintains a project index (src/scanner/anatomy-scanner.ts) with descriptions and token estimates per file, plus symbol-level line ranges so agents can do targeted slice reads instead of whole-file reads. Seven lifecycle hooks (src/hooks/) inject a budget-capped digest at session start, snapshot before compaction, and restore after.
A local dashboard (src/dashboard/app/App.tsx) visualizes token usage measured from harness transcripts, not estimates. The system supports six agents: Claude Code, Codex, Cursor, Gemini, OpenCode, and Antigravity (src/agents/).
How It Is Wired
Execution starts at src/cli/index.ts. The init command (src/cli/init.ts) auto-detects the agent, writes hooks into the project, and creates a .wolf/ directory. The daemon (src/daemon/wolf-daemon.ts) watches files via src/daemon/file-watcher.ts and updates the anatomy index. The scan command (src/cli/scan.ts) rebuilds the index on demand.
The hook lifecycle is the core: pre-read.ts and post-read.ts catch repeated reads, pre-write.ts and post-write.ts track changes, precompact.ts snapshots state, and session-start.ts injects the digest. All hooks route through src/hooks/shared.ts, which has 421 branch points over 538 lines — the highest complexity in the repo.
The module graph shows two hubs: src/utils/fs-safe.ts (16 modules depend on it) and src/hooks/anatomy-store.ts (12 dependents). Both are leaf modules with zero imports, so they are stable but high-blast-radius. A cycle exists in src/agents/index.ts (7 importers, 6 imports, in a 6-module circular dependency) — changing agent registration logic risks subtle init-order bugs.
How To Use It
npm install -g openwolf
cd your-project
openwolf initinit auto-detects the agent and writes the hook configuration. No environment variables are required. The daemon starts via openwolf daemon, the dashboard via openwolf dashboard. Configuration lives in .wolf/config.json (template at src/templates/config.json).
Real-World Use
A Claude Code session working on a 2,000-line module. Without OpenWolf, the agent reads the whole file three times in one session (~6,000 tokens). With it, the first read is a 50-token description from the index, subsequent reads target exact line ranges via offset/limit. When context compacts, the precompact hook saves the session summary, and session-start restores it — the agent continues without re-discovering state.
Code Health & Issues
Static analysis found 32 findings (7 high, 25 medium). High severity:
- Import cycle —
src/agents/index.ts,src/agents/antigravity.ts,src/agents/codex.tsparticipate in a circular dependency. Extract shared types or defer imports. - Duplicated code blocks — 112 repeated 6-line blocks across 26 files. DRY the logic.
Medium findings include high branching density (421 branch points in src/hooks/shared.ts), deep nesting in two dashboard components (DotBar.tsx, MemoryViewer.tsx), and oversized files (src/scanner/description-extractor.ts at 752 lines).
SDLC observations: CI exists but never runs the 6 test files — the green check is cosmetic. No dependency update bot, and npm install runs in CI instead of npm ci, so the tested dependency set is not the locked one. The demo.gif is 6.4MB and should move to LFS. Checkout in docs.yml keeps credentials for later steps.
The Bottom Line
OpenWolf solves a real, measurable cost problem for agent-based development. The architecture is sound — hooks are invisible, the index is self-healing, and the dashboard gives actual usage data. The duplication and cycle in the agent layer will slow contributors, and the CI gap is a credibility issue. Worth using for teams running Claude Code or Codex on large codebases; the payoff scales with project size.