OpenWolf

Token-conscious AI brain for Claude Code projects.

OpenWolf gives Claude Code a persistent memory: a project map so it reads less, a learning brain so it remembers your corrections, and a token ledger so you see where tokens go. All through six invisible hook scripts that fire on every Claude action -- zero workflow changes.

---

Installation

Requires Node.js 20 or later.

npm install -g openwolf

Verify the installation:

openwolf --version

Quick start

1. Navigate to your project directory:

   cd your-project

2. Initialize OpenWolf:

   openwolf init

3. Verify everything is ready:

   openwolf status

That's it. Use claude normally. OpenWolf is watching.

Usage examples

Initialize a new project

openwolf init

Creates a .wolf/ directory with the project brain files:

File	Purpose
anatomy.md	Project file map with descriptions and token estimates
cerebrum.md	Learned preferences, corrections, and Do-Not-Repeat list
memory.md	Chronological action log with token estimates
buglog.json	Bug fix memory, searchable, prevents re-discovery
token-ledger.json	Lifetime token tracking and session history
config.json	Project configuration (ports, intervals, thresholds)
identity.md	Project name and description
STATUS.md	Project health and next-phase tracker
OPENWOLF.md	Operating protocol for Claude Code sessions
reframe-frameworks.md	UI framework selection knowledge base
hooks/	Six Claude Code lifecycle hooks (pure Node.js)

Monitor project health

openwolf status

Shows daemon health, file integrity, token stats, and hook registration status.

Launch the real-time dashboard

openwolf dashboard

Opens http://localhost:18791 with live token usage, project anatomy, cron status, and cerebrum state.

Force a full project rescan

openwolf scan

Refreshes anatomy.md to match the current filesystem. Use --check to verify without writing changes:

openwolf scan --check

Capture design screenshots

openwolf designqc

Auto-detects your dev server, captures viewport-height JPEG sections of every route, and saves them to .wolf/designqc-captures/ for design evaluation by Claude.

Available commands

openwolf init              Initialize .wolf/ and register 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 the real-time web dashboard
openwolf daemon start      Start background task scheduler
openwolf daemon stop       Stop the scheduler
openwolf daemon restart    Restart the scheduler
openwolf daemon logs       View scheduler logs
openwolf cron list         Show all scheduled tasks
openwolf cron run <id>     Trigger a task manually
openwolf cron retry <id>   Retry a dead-lettered task
openwolf designqc          Capture screenshots for design evaluation
openwolf bug search <term> Search bug memory for known fixes
openwolf update            Update all registered projects
openwolf restore [backup]  Restore .wolf/ from a backup

Documentation

• Getting Started
• How It Works
• Architecture
• Commands Reference
• Configuration
• Hooks
• Dashboard
• Design QC
• Reframe
• Troubleshooting
• Updating
• Development
• Testing

Contributing

See CONTRIBUTING.md for guidelines.

License

Licensed under the GNU Affero General Public License v3.0.