Documentation

OpenReflex docs

OpenReflex is an open-source plugin that helps AI coding agents learn from every task. It reuses what worked, catches failure loops while they happen, and keeps everything on your machine.

Install

OpenReflex needs Python 3.11 or newer. Install the CLI with pipx, uv or pip.

$pipx install openreflex

Then install it for your agent. Nothing is recorded until a project is enabled; openreflex install enables the project for you.

Set up your agent

OpenReflex follows the same execution loop in every supported agent. Choose an integration below only for its setup and hook details.

Retrieve

Find similar past tasks, successful files and reusable lessons from local project memory.

Route

Score candidate approaches and recommend the best fit for success, cost, risk, uncertainty and the current budget.

Observe

Watch tool calls, verification, failures, context growth and progress, then intervene when the current path degrades.

Learn

Verify the outcome, record path, cost and regret, then turn successful resolutions into evidence for the next similar task.

OpenReflex for Claude CodeInstallation, hook events and troubleshooting for Claude Code.OpenReflex for CodexInstallation, hook events and troubleshooting for Codex.OpenReflex for CursorInstallation, hook events and troubleshooting for Cursor.OpenReflex for OpenCodeInstallation, hook events and troubleshooting for OpenCode.

CLI reference

Command	What it does
openreflex install <agent>	Write hooks and MCP config for claude-code, codex, cursor or opencode, and enable the project. Add --dry-run to preview.
openreflex uninstall <agent>	Remove OpenReflex-owned hooks and MCP entries for an agent while preserving local project memory.
openreflex approve	Enable capture for the current project (needed after a plugin install).
openreflex revoke	Disable capture for the current project. Existing data is kept.
openreflex context "<task>"	Preview the Execution Context a task would receive, without recording anything.
openreflex status [--json]	Show what has been captured, reused and learned in this project.
openreflex why	Explain the latest recommendation, Reflex Score, confidence, signals and next-best route.
openreflex trace	Show the latest execution decision timeline.
openreflex doctor	Check installation, project resolution and recent hook activity.
openreflex forget --yes	Delete all captured data for the project.
openreflex benchmark	Run the assumption-driven execution-policy simulator.
openreflex mcp	Start the MCP server over stdio (used by agent configs).

MCP tools

The OpenReflex MCP server runs over stdio. Agent installs register it automatically; any other MCP client can add it:

{
  "mcpServers": {
    "openreflex": { "command": "openreflex", "args": ["mcp"] }
  }
}

Tool	What it does
get_execution_context	Retrieve relevant past experience, candidate strategies, an execution budget, likely files and lessons for a task.
choose_path	Declare the strategy the agent is following, so the outcome is compared against the right plan.
check_progress	Estimate whether more work on the current path is worth it, and recommend continue, pivot or stop.
record_outcome	Record a verified outcome, such as tests passing, with short evidence.
search_experience	Search past tasks in the project by description.
explain_decision	Explain the latest OpenReflex recommendation, Reflex Score signals, confidence and next-best route.
get_execution_trace	Return the current execution's OpenReflex decision timeline without raw tool output.
get_reflex_score	Return the latest structured Reflex Score and its component signals.
explain_node	Show an Experience Graph node and its relations.
get_project_insights	Summarise capture, reuse, outcomes and learning for the project.
forget_experience	Delete one past task from the project's memory, only when the user explicitly asks.
approve_project	Enable the project, only when the user explicitly asks.

To limit every task without an MCP call, set OPENREFLEX_BUDGET, for example calls=40,minutes=20,tokens=60000. The recommended path is the best one that fits, and the execution budget never exceeds these limits.

Privacy and data

Kept: tool names and categories, a fingerprint of each call's arguments, project-relative file paths, pass or fail, duration, output size, and a masked one-line error signature.
Never kept: file contents, command text, tool output, transcripts, or paths outside the project.
Prompts: stored as a task description of up to 1,000 characters, with keys and tokens redacted.
Location: ~/.openreflex/projects/<hash>/experience.sqlite3. Set OPENREFLEX_HOME to move it or OPENREFLEX_DISABLE=1 to turn capture off everywhere.

Troubleshooting

Nothing is being captured: Run openreflex doctor. Check the project is enabled (openreflex approve) and that the openreflex command is on your PATH.
Hooks seem to do nothing in Codex: Open /hooks in Codex and trust the OpenReflex entries; untrusted hooks do not run.
Where are hook errors logged?: In ~/.openreflex/logs/errors.log. Hooks never block your agent, so errors are recorded there instead of shown.
No context was injected: Context is only added when relevant past experience exists, so a new project starts silent.

Still stuck? Open an issue on GitHub.