openwolf

What it does

A coding session produces useful context: the task objective, files changed, failed tests and the next action. That information can be difficult to recover after compaction, a restart or a change of agent. Large file reads and command results can also fill a session with repeated text.

OpenWolf stores selected context beside your project and connects to the session and tool events your coding agent supports:

• Keep the objective, completed work, unresolved problems and next action in a checkpoint. Supported Claude and Codex hooks can restore saved context.
• Find files and symbols through a project map with descriptions, line ranges and import relationships. Partial scans preserve earlier entries.
• Save project notes and known fixes for later sessions. Archive eligible old session notes while retaining active, latest and pinned notes.
• Identify repeated reads of unchanged files. Supported Claude hooks can shorten selected large Bash results and retain the original output locally.
• Review available provider token counters, model cost estimates, hook health and completed OpenWolf activity in the dashboard.

Quick start

npm install -g openwolf
cd your-project
openwolf init

init detects installed agents and sets up their project integration. Complete any project or hook trust review shown by your agent, then start a new session. You can select agents with --agent claude codex opencode.

Supported agents

Agents use the project's .wolf/ directory. The generated .gitignore excludes local runtime data. Review notes, bug records and indexed content before sharing them. Hook coverage depends on the installed agent version. See the integration guide for details.

How it works

openwolf init creates .wolf/ and registers supported hooks or a plugin. Memory, indexing and usage processing run locally without extra model calls. The optional background update worker contacts npm to check for new runtimes.

During a session:

• Session start. Load a short project index and available saved task evidence. New sessions can select a verified compatible runtime update.
• Before reads. Identify eligible repeated reads and offer symbol guidance for large indexed files. Changed files and ranged reads are handled separately.
• After Bash. Supported Claude hooks can shorten selected output above an estimated size threshold. The original stays in a local cache. Test and build output are advisory-only by default.
• Every 25 tool batches. Supported Claude events can repeat selected approved rules within a size budget. Durable instruction injection requires an independently protected installation and administrator review.
• On compaction. Save a checkpoint for supported recovery paths. Recovery uses persisted task evidence; it cannot reproduce every part of live context.
• On stop. Record available usage and session observations. Eligible activity notices report completed work within the configured message limit.

Measurement

openwolf report

Example from a checked Codex session, shown in a shortened format:

  Recorded provider usage
    Input tokens:           50,393
      Cached input:         28,800
      Fresh input:          21,593
    Output tokens:             146
      Reasoning tokens:         80
    Total tokens:           50,539

  Cost calculation
    Fresh input:            model input rate
    Cached input:           model cached-input rate
    Output:                 model output rate

  Coverage
    Cached input is included in input tokens.
    Reasoning is included in output tokens in this record.
    Content-size estimates are reported separately.

How to read the reports:

1. Recorded usage comes from available Claude transcripts, Codex session records and OpenCode plugin records. Repeated records are reconciled. Missing counters remain unavailable rather than being reported as zero.
2. Cost estimates use the relevant provider and model rates, including separate cache categories where available. They represent API list prices, not subscription charges. Unknown models and pricing assumptions are shown.
3. Local estimates describe content size and output changes. They are separate from provider counters and do not prove a fixed amount of token savings.

openwolf usage report --json provides the recorded-usage report. openwolf bench --repo <fixture> --yes compares supported coding tasks with and without OpenWolf. It uses real model access and can consume paid usage.

Reliability

Hook heartbeats, runtime checks and dashboard health help identify missing or failing integrations. Project updates check installed hook modules and report errors. Concurrent writes use journals or locks where required, and incomplete project scans retain entries they did not reach.

Compatible stable hook and plugin updates can be prepared in the background for new sessions. Major upgrades are notification-only by default. A running session keeps its selected runtime. This does not replace the global CLI or a running dashboard daemon. See automatic updates.

Security

• The dashboard binds to 127.0.0.1 by default and requires a project token.
• Hooks do not approve tool calls. Permissions remain with the agent and user.
• Handover imports check project identity, source records and repository drift.
• Sensitive-file exclusions and path checks reduce accidental exposure. Review saved content before sharing it; automatic filtering has limits.
• Saved notes do not approve themselves. Automatic durable instruction injection requires independent administrator review and a protected runtime.

Skills

Available through the supported agent integration:

• /handoff helps update STATUS.md with current work and open items.
• /security-audit guides a project review and records findings in the bug log.
• /reframe guides interface review, framework selection and migration work.

Skills guide your coding agent and use its normal model budget. For an explicit Claude and Codex transfer, use the handover commands. OpenWolf can read supported local session records used for Claude recovery; it does not run Claude's /resume inside Codex or access privat