openwolf

Why Openwolf?

Coding agents are powerful but they work blind. An agent does not know what a file contains until it opens it. It cannot tell a 50-token config from a 2,000-token module. It rereads the same file in one session without noticing, forgets your corrections between sessions, and loses everything when its context window compacts.

OpenWolf gives your agent a second brain that fixes all of that:

• Context management. A budget-capped digest of your project's most valuable state (current goals, known mistakes, fixed bugs, the project map) is injected at every session start. A PreCompact hook plus a compaction-aware restart mean context compaction no longer erases what the session already did.
• Architecture scaffolding. A durable, self-healing project index maps every file with a description, a token estimate, and (for large files) its functions and classes with exact line ranges. Agents navigate your codebase instead of rediscovering it.
• Token utilization. Repeated reads are caught, whole-file reads become targeted slice reads, and real usage is measured from harness transcripts so you can verify the savings instead of trusting an estimate.

Quick Start

npm install -g openwolf
cd your-project
openwolf init

That is it. init auto-detects the coding agents installed on your machine and wires each of them to the same .wolf/ brain. Use your agents normally; OpenWolf works underneath.

Supported Agents

One .wolf/ brain, many agents:

openwolf init                          # auto-detect installed agents (recommended)
openwolf init --agent codex opencode   # wire exactly these
openwolf init --agent all              # wire every detected agent
openwolf init --agent claude           # Claude Code only

Protocol blocks are marker-fenced: your own content in AGENTS.md or GEMINI.md is never touched, and re-running init never duplicates anything.

What It Creates

openwolf init creates a .wolf/ directory in your project:

How It Works

Session starts
    |
OpenWolf injects a token-budgeted digest: current goals, known mistakes,
recent bug fixes, project map pointer
    |
Agent decides to read a big file
    |
OpenWolf: "auth.ts (~2,900 tok). Symbols: validateToken L82-140 ~450 tok.
Read with offset/limit to fetch just the part you need."
    |
Agent edits files
    |
OpenWolf updates the index under a cross-process lock, logs the action,
estimates the cost
    |
Context compacts mid-session
    |
OpenWolf snapshots state before compaction and re-injects a digest of the
files already modified, so the agent does not redo finished work
    |
Session ends
    |
OpenWolf reads the real token usage from the transcript into the ledger

Context Management

• Session digest. The highest-value state is pushed into the model's context at session start, capped to a configurable token budget per agent. The model gets what it needs without reading six files.
• Compaction survival. The PreCompact hook snapshots in-flight session state; after compaction the digest lists the files already modified with a pointer to the action log. Resume and compaction no longer reset tracking.
• Staleness detection. Scans pin the git HEAD. If the HEAD moves or the scan ages out, the agent is told to rescan before trusting the map. A wrong index is never silently trusted.
• STATUS.md handoff. End-of-phase state lives in one small document, so a fresh session reaches productive context in a single read.

Project Anatomy

The index is a durable store (anatomy-index.json) with a rendered, human-readable view (anatomy.md). Writers coordinate through a cross-process lock, so concurrent hook fires cannot lose entries. Edits made to the markdown by hand or by older hook versions are detected by content hash and absorbed additively.

Files above 500 estimated tokens also index their top-level symbols:

- `shared.ts` (~3,200 tok)
  - fn `parseAnatomy` L82-104 (~180 tok)
  - fn `serializeAnatomy` L106-129 (~200 tok)

Before the agent reads a large file, the hint lists the biggest symbols with line ranges so it can fetch one function with offset/limit instead of the whole file. Hints are suppressed automatically if the file changed since indexing; a stale range is never allowed to misdirect a read. Languages with symbol support today: TypeScript, JavaScript, Python, Go, Rust.

Token Intelligence

Estimates are useful; measurements are trustworthy. At session end OpenWolf reads the real usage from the harness transcript: input tokens, output tokens, cache reads, cache writes, and API calls, attributed to the agent that ran the session.

openwolf report

  Estimated (char-ratio heuristic)
    Total tokens:           1,549,658
    Est. savings vs bare:   1,772,690

  Measured (from harness transcripts)
    API calls:              29
    Input tokens:           57,489
    Cache reads:            309,141

Field results from 1.x deployments (20 projects, 132+ sessions) averaged a 65.8% estimated token reduction, with 71% of repeated file reads caught and blocked. Those figures are heuristic estimates; 2.0 exists so your own numbers are measured, not modeled.

Security

• Dashboard binds to 127.0.0.1 and requires a per-project token (timing-safe comparison) for all API and WebSocket access.
• Every dynamic process invocation uses argument arrays; no shell interpolation anywhere.
• Path traversal guards on all cron file access, realpath-based and symlink-safe.
• Secret-bearing files (keys, keystores, credential files, .npmrc, .env and friends) never enter the index or the memory log.
• A security regression suite runs with pnpm test.

Bundled Skills

openwolf init installs two slash commands into every configured agent (Claude Code, Codex, OpenCode):

• /security-audit [scope]: layered audit covering dependencies, secrets, injection surfaces, and authorization, ending in