OpenReflex

Muscle memory for AI coding agents.

Ambient execution intelligence for AI coding agents. Install it once and keep working normally. It records how each task actually went (strategy, tool calls, failures, what fixed them, which files mattered). Before the next similar task it hands the agent a short Execution Context. While a task runs, it steps in only when the evidence says re-planning is worthwhile.

Everything runs locally in SQLite. There is no service, no account, and no network access.

install once  ->  work normally  ->  OpenReflex learns continuously

Install (under 2 minutes)

pipx install openreflex          # or: uv tool install openreflex   (puts `openreflex` on PATH)
cd your-project
openreflex install claude-code   # or codex | cursor | opencode; also enables the project

install writes project-level hook and MCP config for one agent, merging with any existing files, and approves the project. Use --dry-run to preview the changes.

Plugin install (no project files)

Nothing is captured in a project until it is approved. An unapproved project shows a one-line notice at most once a day. To stop capture, run openreflex revoke. To delete a project's data, run openreflex forget --yes.

How it works

 agent hooks ──► openreflex hook <agent> <event> ──► Engine ──► Experience Graph (SQLite)
   prompt        normalize payload per agent               │
   tool start    (hooks.py)                                ├─ before: retrieve experience, score 3 candidate
   tool end                                                │          paths, render Execution Context
   compaction                                              ├─ during: detect failure loops, repeated calls,
   stop                                                    │          stagnation, context growth, over-budget
                                                           └─ after:  infer outcome + chosen path, estimate
 agent ◄── additionalContext / alerts ◄────────────────────           Execution Regret, extract lessons
 agent ──► MCP tools (get_execution_context, choose_path, record_outcome, search_experience, ...)

Experience Graph. The nodes are Task, Context, CandidatePath, Execution, ToolCall, Outcome, Experience, and Lesson. They are connected by used, caused, failed_with, resolved_by, and recommended_for:

Task -caused-> Execution -used-> Context -used-> Experience
CandidatePath -recommended_for-> Task            Lesson -recommended_for-> Task
Execution -failed_with-> ToolCall -resolved_by-> ToolCall (the edit that fixed it)
Execution -caused-> Outcome -caused-> Experience -caused-> Lesson

Before a task. A prompt counts as substantial if it has at least 5 words and isn't a follow-up like "yes, continue". For those prompts, OpenReflex:

1. Retrieves similar past experiences.
2. Scores inspect-first, test-first, and incremental on success probability, time, tool calls, context cost, risk, uncertainty, and reversibility. Each score is a Beta-style blend of a prior and observed outcomes.
3. Injects a context of at most 1,400 characters: the suggested path, alternatives, likely relevant files, and lessons.

Nothing is injected when there is no relevant experience, so a new project costs zero context tokens.

During a task. Each alert kind fires at most once per execution, with a 3-minute cooldown. Stagnation is only judged after implementation has started, so exploratory reading does not trigger it. An alert names a concrete alternative path and any known fix for the current error.

After a task. The Stop hook finalizes the execution. Later turns reopen it and finalize it again, so the same task keeps one experience. Outcome and chosen path come from record_outcome/choose_path when the agent calls them. Otherwise they are inferred: only a check that passed or failed after the last edit counts as evidence. Execution Regret is the best alternative's expected utility minus the chosen path's realized utility. It is withheld (not guessed) when the outcome is unknown.

Agent integrations

* Cursor's beforeSubmitPrompt cannot inject context, so the context is held until the first tool result. Cursor can also run Claude Code hook configs. Those calls are attributed to Cursor and de-duplicated.

Claude Code is verified in live sessions (see Testing). The Codex, Cursor, and OpenCode adapters follow each agent's documented hook protocol (checked September 2026) and are tested with protocol-shaped and fuzzed payloads, but have not yet run inside live sessions of those agents.

A hook always exits 0 and never blocks. Errors go to ~/.openreflex/logs/errors.log, which openreflex doctor shows. Measured on Windows: median 381 ms per hook process, where bare Python startup is about 255 ms. Sixteen parallel tool-call hooks were stored with no lost writes.

Privacy

• Stored per tool call: tool name, a coarse category (read/edit/search/test/...), a SHA-256 fingerprint of the arguments, project-relative file paths, status, duration, output size, and a masked one-line error signature. Paths outside the project, file contents, command text, tool output, and transcripts are never stored.
• Prompts are stored as task descriptions, at most 1,000 characters, with secrets (API keys, tokens, bearer headers, private keys) redacted.
• Data lives in ~/.openreflex/projects/<hash>/experience.sqlite3. Set OPENREFLEX_HOME to relocate it, or OPENREFLEX_DISABLE=1 to turn capture off everywhere.

CLI

Measuring the success metrics

openreflex status --json reports these per project:

Cross-project aggregation (retention across projects, fleet-level activation) belongs with M5 sync.

Benchmark (simulated)

openreflex benchmark runs synthetic coding tasks from five task families, in two arms, through the real engine. Both arms send real hook events and read back the real contexts and alerts; only the guided arm acts on them. Default run: 150 tasks per arm × 3 seeds.

How to read this. These are properties of the simulator, not evidence of real-world gains. Most of the tool-call and token reduction comes from one assumption: a relevant-files hint cuts search and read calls from 6–9 down to 2–3. Time is modeled as calls × 25 s, so it moves exactly with calls. All assumptions are listed in SIMULATION_ASSUMPTIONS in benchmark.py and written into the JSON report. What the benchmark does show: the engine learns family-specific best strategies from noisy outcomes, regret declines, and alerts shorten failure loops. Routing agreement falls short because candidate evidence is pooled per task class, so families in the same class that prefer different strategies dilute each other.

Status

Suggested next steps, in order:

1. Run the Codex, Cursor, and OpenCode integrations in live sessions and fix protocol drift.
2. Weight candidate evidence by similarity instead of pooling by task class; this is the cause of the routing-agreement miss.
3. Build a real-task A/B harness: the same task set with capture on and off.
4. Add a pluggable semantic embedder (keep lexical as the offline default) and a vector index once there are more than ~5k experiences.
5. M5.

Testing

The live Claude Code scenarios assert on the captured graph and on the session transcript, not on model wording:

1. plugin-capture: the plugin is loaded with --plugin-dir; a real bug fix is captured with categorized tool calls, an inferred success, and lessons.
2. context-injection: a similar task in a new session gets an Execution Context naming the right file, and the transcript shows the model received it.
3. failure-loop-alert: repeated failing test runs raise one alert, and the transcript shows it reached the model.
4. mcp-tools: the plugin's MCP server starts inside Claude Code and search_experience returns the captured files.
5. project-install: openreflex install claude-code works without the plugin.

Development

pip install -e ".[dev]"
pytest                                   # unit, integration, stress
ruff check src tests scripts
python scripts/live_claude_code.py       # live Claude Code scenarios (real model calls, default haiku)

Layout: engine.py (event → graph), routing.py (retrieval features, candidates, utility), detect.py (live alerts), learning.py (outcome/strategy inference, regret, lessons), hooks.py (agent adapters), mcp_server.py, install.py, metrics.py, benchmark.py, integrations/opencode.ts, and plugins/openreflex (Claude Code / Codex / Cursor plugin; its hook files are checked against install.py by tests).