openreflex 0.1.0__tar.gz → 0.1.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. openreflex-0.1.2/PKG-INFO +193 -0
  2. openreflex-0.1.2/README.md +161 -0
  3. {openreflex-0.1.0 → openreflex-0.1.2}/pyproject.toml +2 -2
  4. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex/__init__.py +1 -1
  5. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex/benchmark.py +11 -11
  6. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex/cli.py +1 -1
  7. openreflex-0.1.2/src/openreflex.egg-info/PKG-INFO +193 -0
  8. openreflex-0.1.0/PKG-INFO +0 -250
  9. openreflex-0.1.0/README.md +0 -218
  10. openreflex-0.1.0/src/openreflex.egg-info/PKG-INFO +0 -250
  11. {openreflex-0.1.0 → openreflex-0.1.2}/LICENSE +0 -0
  12. {openreflex-0.1.0 → openreflex-0.1.2}/setup.cfg +0 -0
  13. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex/__main__.py +0 -0
  14. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex/detect.py +0 -0
  15. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex/engine.py +0 -0
  16. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex/hooks.py +0 -0
  17. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex/install.py +0 -0
  18. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex/integrations/opencode.ts +0 -0
  19. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex/learning.py +0 -0
  20. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex/mcp_server.py +0 -0
  21. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex/metrics.py +0 -0
  22. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex/models.py +0 -0
  23. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex/privacy.py +0 -0
  24. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex/project.py +0 -0
  25. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex/routing.py +0 -0
  26. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex/store.py +0 -0
  27. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex.egg-info/SOURCES.txt +0 -0
  28. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex.egg-info/dependency_links.txt +0 -0
  29. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex.egg-info/entry_points.txt +0 -0
  30. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex.egg-info/requires.txt +0 -0
  31. {openreflex-0.1.0 → openreflex-0.1.2}/src/openreflex.egg-info/top_level.txt +0 -0
  32. {openreflex-0.1.0 → openreflex-0.1.2}/tests/test_engine.py +0 -0
  33. {openreflex-0.1.0 → openreflex-0.1.2}/tests/test_hooks.py +0 -0
  34. {openreflex-0.1.0 → openreflex-0.1.2}/tests/test_install_cli.py +0 -0
  35. {openreflex-0.1.0 → openreflex-0.1.2}/tests/test_mcp_metrics_benchmark.py +0 -0
  36. {openreflex-0.1.0 → openreflex-0.1.2}/tests/test_stress.py +0 -0
@@ -0,0 +1,193 @@
1
+ Metadata-Version: 2.4
2
+ Name: openreflex
3
+ Version: 0.1.2
4
+ Summary: Muscle memory for AI coding agents: learns from every task, advises the next one, and flags failure loops live
5
+ Author: vishnu-77
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://openreflex.cc
8
+ Project-URL: Repository, https://github.com/vishnu-77/openreflex
9
+ Project-URL: Issues, https://github.com/vishnu-77/openreflex/issues
10
+ Keywords: ai-agents,coding-agents,claude-code,codex,cursor,opencode,mcp,memory,hooks
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Software Development
20
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
21
+ Requires-Python: >=3.11
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: mcp<2,>=1.26
25
+ Requires-Dist: pydantic<3,>=2.10
26
+ Provides-Extra: dev
27
+ Requires-Dist: pytest<9,>=8; extra == "dev"
28
+ Requires-Dist: ruff>=0.12; extra == "dev"
29
+ Requires-Dist: build>=1.2; extra == "dev"
30
+ Requires-Dist: twine>=6; extra == "dev"
31
+ Dynamic: license-file
32
+
33
+ <div align="center">
34
+
35
+ <a href="https://openreflex.cc" target="_blank">
36
+ <picture>
37
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/openreflex-logo-dark.svg">
38
+ <img alt="OpenReflex" src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/openreflex-logo-light.svg" width="380" height="auto">
39
+ </picture>
40
+ </a>
41
+
42
+ ### OpenReflex: muscle memory for AI coding agents
43
+
44
+ <a href="https://openreflex.cc">Website</a> · <a href="https://github.com/vishnu-77/openreflex">GitHub</a> · <a href="https://pypi.org/project/openreflex/">PyPI</a> · <a href="https://github.com/vishnu-77/openreflex/issues">Issues</a> · <a href="https://buymeacoffee.com/vishnuprashanth">Buy me a coffee</a>
45
+
46
+ [![PyPI](https://img.shields.io/pypi/v/openreflex?style=flat-square&labelColor=black&color=286a70)](https://pypi.org/project/openreflex/)
47
+ [![Python](https://img.shields.io/pypi/pyversions/openreflex?style=flat-square&labelColor=black&color=7cc9c8)](https://pypi.org/project/openreflex/)
48
+ [![CI](https://img.shields.io/github/actions/workflow/status/vishnu-77/openreflex/ci.yml?branch=main&style=flat-square&labelColor=black&label=CI)](https://github.com/vishnu-77/openreflex/actions/workflows/ci.yml)
49
+ [![License](https://img.shields.io/badge/license-MIT-white?style=flat-square&labelColor=black)](https://github.com/vishnu-77/openreflex/blob/main/LICENSE)
50
+
51
+ </div>
52
+
53
+ ***
54
+
55
+ ## What is OpenReflex
56
+
57
+ OpenReflex gives AI coding agents muscle memory. It plugs into Claude Code, Codex, Cursor, and OpenCode through
58
+ lifecycle hooks and MCP, quietly records how each task actually went, and hands the next similar task what worked
59
+ before: the approach, the files that mattered, and the fix for the error you hit last time.
60
+
61
+ You install it once and keep working normally. Everything stays on your machine in a local SQLite database.
62
+ There is no account, no service, and no telemetry.
63
+
64
+ ## Why OpenReflex
65
+
66
+ - **It remembers what worked.** Before a substantial task, OpenReflex retrieves similar past tasks and injects a
67
+ compact Execution Context: a suggested approach with alternatives, the files that were changed, and lessons
68
+ such as which edit resolved a recurring error.
69
+ - **It catches loops while they happen.** Repeated failing commands, identical retries, stalled progress, and
70
+ runaway context growth raise a single, specific alert with an alternative path, never a stream of nags.
71
+ - **It learns after every task.** OpenReflex infers the outcome from real verification (a test or build that
72
+ passed or failed after the last edit), estimates Execution Regret against the alternatives, and extracts lessons.
73
+ - **It is private by design.** Only coarse, project-relative metadata is stored. File contents, commands, tool
74
+ output, and transcripts never are, and capture is off until you approve a project.
75
+
76
+ ```
77
+ before a task during a task after a task
78
+ ┌──────────────────────┐ ┌──────────────────────────┐ ┌───────────────────────┐
79
+ │ retrieve experience │ │ watch tool calls │ │ infer outcome │
80
+ │ score candidate paths│ → │ flag loops and stalls │ → │ estimate regret │
81
+ │ inject context │ │ suggest an alternative │ │ extract lessons │
82
+ └──────────────────────┘ └──────────────────────────┘ └───────────────────────┘
83
+ ▲ │
84
+ └──────────────────── Experience Graph ◄─────────────────┘
85
+ ```
86
+
87
+ ## Quick start
88
+
89
+ Requires Python 3.11 or newer.
90
+
91
+ ```bash
92
+ pipx install openreflex # or: uv tool install openreflex
93
+ cd your-project
94
+ openreflex install claude-code # writes hooks + MCP config and enables this project
95
+ ```
96
+
97
+ Then work as usual. After a few tasks:
98
+
99
+ ```bash
100
+ openreflex context "fix the login redirect bug" # preview the context a task would receive
101
+ openreflex status # what has been captured and learned
102
+ openreflex doctor # installation checks and recent hook errors
103
+ ```
104
+
105
+ ## Use it with your agent
106
+
107
+ OpenReflex installs per project with `openreflex install <agent>`, or as a plugin.
108
+
109
+ <table>
110
+ <tbody>
111
+ <tr>
112
+ <td align="center" valign="bottom" width="25%"><strong>Claude&nbsp;Code</strong><br><sub>Plugin&nbsp;or&nbsp;hooks&nbsp;+&nbsp;MCP</sub></td>
113
+ <td align="center" valign="bottom" width="25%"><strong>Codex</strong><br><sub>Plugin&nbsp;or&nbsp;hooks&nbsp;+&nbsp;MCP</sub></td>
114
+ <td align="center" valign="bottom" width="25%"><strong>Cursor</strong><br><sub>Hooks&nbsp;+&nbsp;MCP</sub></td>
115
+ <td align="center" valign="bottom" width="25%"><strong>OpenCode</strong><br><sub>Plugin&nbsp;+&nbsp;MCP</sub></td>
116
+ </tr>
117
+ </tbody>
118
+ </table>
119
+
120
+ | Agent | Install |
121
+ |---|---|
122
+ | Claude Code | `claude plugin marketplace add vishnu-77/openreflex` and `claude plugin install openreflex@openreflex`, or `openreflex install claude-code` |
123
+ | Codex | `codex plugin marketplace add vishnu-77/openreflex`, or `openreflex install codex`, then trust the hooks once in `/hooks` |
124
+ | Cursor | `openreflex install cursor` |
125
+ | OpenCode | `openreflex install opencode` |
126
+
127
+ With a plugin install, enable each project with `openreflex approve`. Claude Code is verified in live sessions;
128
+ the Codex, Cursor, and OpenCode integrations follow each agent's documented hook protocol.
129
+
130
+ ## How it works
131
+
132
+ Hooks send lifecycle events (prompt, tool start, tool end, compaction, stop) to the OpenReflex engine, which
133
+ stores them in an **Experience Graph**:
134
+
135
+ ```
136
+ Task -caused-> Execution -used-> Context -used-> Experience
137
+ CandidatePath -recommended_for-> Task Lesson -recommended_for-> Task
138
+ Execution -failed_with-> ToolCall -resolved_by-> ToolCall
139
+ Execution -caused-> Outcome -caused-> Experience -caused-> Lesson
140
+ ```
141
+
142
+ - **Before a task:** similar experiences are retrieved, three strategies (`inspect-first`, `test-first`,
143
+ `incremental`) are scored on success probability, time, tool calls, context cost, risk, uncertainty, and
144
+ reversibility, and a context of at most 1,400 characters is injected. Nothing is injected without relevant
145
+ experience.
146
+ - **During a task:** each alert fires at most once per task with a cooldown, and names a concrete alternative.
147
+ - **After a task:** outcome and chosen path come from the agent's `record_outcome` / `choose_path` MCP calls when
148
+ available, and are otherwise inferred from tool activity. Execution Regret is withheld when the outcome is unknown.
149
+
150
+ Agents can also query OpenReflex directly through its MCP server: `get_execution_context`, `choose_path`,
151
+ `record_outcome`, `search_experience`, `explain_node`, `project_insights`, and `approve_project`.
152
+
153
+ ## CLI
154
+
155
+ | Command | Purpose |
156
+ |---|---|
157
+ | `install <agent> [--dry-run]` | Write project hooks and MCP config, and enable the project |
158
+ | `approve` / `revoke` | Enable or disable capture for the current project |
159
+ | `context "<task>"` | Preview the Execution Context a task would receive |
160
+ | `status [--json]` | What has been captured, reused, and learned |
161
+ | `doctor` | Installation checks and recent hook errors |
162
+ | `forget --yes` | Delete the project's data |
163
+ | `benchmark` | Run the simulated benchmark |
164
+ | `hook <agent> <event>` / `mcp` | Used by agent configs |
165
+
166
+ ## Privacy
167
+
168
+ - Stored per tool call: tool name, a coarse category (`read`, `edit`, `search`, `test`, ...), a fingerprint of the
169
+ arguments, project-relative file paths, status, duration, output size, and a masked one-line error signature.
170
+ - Never stored: file contents, command text, tool output, transcripts, or paths outside the project.
171
+ - Prompts are kept as task descriptions (up to 1,000 characters) with secrets such as API keys and tokens redacted.
172
+ - Data lives in `~/.openreflex/projects/<hash>/experience.sqlite3`. Set `OPENREFLEX_HOME` to move it,
173
+ `OPENREFLEX_DISABLE=1` to turn capture off everywhere, or run `openreflex forget --yes` to delete a project's data.
174
+
175
+ ## Community & Contributing
176
+
177
+ - **Issues and ideas:** [GitHub Issues](https://github.com/vishnu-77/openreflex/issues)
178
+ - **Support the project:** [Buy me a coffee](https://buymeacoffee.com/vishnuprashanth)
179
+ - **Develop locally:**
180
+
181
+ ```bash
182
+ git clone https://github.com/vishnu-77/openreflex && cd openreflex
183
+ pip install -e ".[dev]"
184
+ pytest && ruff check src tests scripts
185
+ ```
186
+
187
+ <a href="https://github.com/vishnu-77/openreflex/graphs/contributors">
188
+ <img src="https://contrib.rocks/image?repo=vishnu-77/openreflex" alt="Contributors">
189
+ </a>
190
+
191
+ ## License
192
+
193
+ OpenReflex is released under the [MIT License](https://github.com/vishnu-77/openreflex/blob/main/LICENSE).
@@ -0,0 +1,161 @@
1
+ <div align="center">
2
+
3
+ <a href="https://openreflex.cc" target="_blank">
4
+ <picture>
5
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/openreflex-logo-dark.svg">
6
+ <img alt="OpenReflex" src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/openreflex-logo-light.svg" width="380" height="auto">
7
+ </picture>
8
+ </a>
9
+
10
+ ### OpenReflex: muscle memory for AI coding agents
11
+
12
+ <a href="https://openreflex.cc">Website</a> · <a href="https://github.com/vishnu-77/openreflex">GitHub</a> · <a href="https://pypi.org/project/openreflex/">PyPI</a> · <a href="https://github.com/vishnu-77/openreflex/issues">Issues</a> · <a href="https://buymeacoffee.com/vishnuprashanth">Buy me a coffee</a>
13
+
14
+ [![PyPI](https://img.shields.io/pypi/v/openreflex?style=flat-square&labelColor=black&color=286a70)](https://pypi.org/project/openreflex/)
15
+ [![Python](https://img.shields.io/pypi/pyversions/openreflex?style=flat-square&labelColor=black&color=7cc9c8)](https://pypi.org/project/openreflex/)
16
+ [![CI](https://img.shields.io/github/actions/workflow/status/vishnu-77/openreflex/ci.yml?branch=main&style=flat-square&labelColor=black&label=CI)](https://github.com/vishnu-77/openreflex/actions/workflows/ci.yml)
17
+ [![License](https://img.shields.io/badge/license-MIT-white?style=flat-square&labelColor=black)](https://github.com/vishnu-77/openreflex/blob/main/LICENSE)
18
+
19
+ </div>
20
+
21
+ ***
22
+
23
+ ## What is OpenReflex
24
+
25
+ OpenReflex gives AI coding agents muscle memory. It plugs into Claude Code, Codex, Cursor, and OpenCode through
26
+ lifecycle hooks and MCP, quietly records how each task actually went, and hands the next similar task what worked
27
+ before: the approach, the files that mattered, and the fix for the error you hit last time.
28
+
29
+ You install it once and keep working normally. Everything stays on your machine in a local SQLite database.
30
+ There is no account, no service, and no telemetry.
31
+
32
+ ## Why OpenReflex
33
+
34
+ - **It remembers what worked.** Before a substantial task, OpenReflex retrieves similar past tasks and injects a
35
+ compact Execution Context: a suggested approach with alternatives, the files that were changed, and lessons
36
+ such as which edit resolved a recurring error.
37
+ - **It catches loops while they happen.** Repeated failing commands, identical retries, stalled progress, and
38
+ runaway context growth raise a single, specific alert with an alternative path, never a stream of nags.
39
+ - **It learns after every task.** OpenReflex infers the outcome from real verification (a test or build that
40
+ passed or failed after the last edit), estimates Execution Regret against the alternatives, and extracts lessons.
41
+ - **It is private by design.** Only coarse, project-relative metadata is stored. File contents, commands, tool
42
+ output, and transcripts never are, and capture is off until you approve a project.
43
+
44
+ ```
45
+ before a task during a task after a task
46
+ ┌──────────────────────┐ ┌──────────────────────────┐ ┌───────────────────────┐
47
+ │ retrieve experience │ │ watch tool calls │ │ infer outcome │
48
+ │ score candidate paths│ → │ flag loops and stalls │ → │ estimate regret │
49
+ │ inject context │ │ suggest an alternative │ │ extract lessons │
50
+ └──────────────────────┘ └──────────────────────────┘ └───────────────────────┘
51
+ ▲ │
52
+ └──────────────────── Experience Graph ◄─────────────────┘
53
+ ```
54
+
55
+ ## Quick start
56
+
57
+ Requires Python 3.11 or newer.
58
+
59
+ ```bash
60
+ pipx install openreflex # or: uv tool install openreflex
61
+ cd your-project
62
+ openreflex install claude-code # writes hooks + MCP config and enables this project
63
+ ```
64
+
65
+ Then work as usual. After a few tasks:
66
+
67
+ ```bash
68
+ openreflex context "fix the login redirect bug" # preview the context a task would receive
69
+ openreflex status # what has been captured and learned
70
+ openreflex doctor # installation checks and recent hook errors
71
+ ```
72
+
73
+ ## Use it with your agent
74
+
75
+ OpenReflex installs per project with `openreflex install <agent>`, or as a plugin.
76
+
77
+ <table>
78
+ <tbody>
79
+ <tr>
80
+ <td align="center" valign="bottom" width="25%"><strong>Claude&nbsp;Code</strong><br><sub>Plugin&nbsp;or&nbsp;hooks&nbsp;+&nbsp;MCP</sub></td>
81
+ <td align="center" valign="bottom" width="25%"><strong>Codex</strong><br><sub>Plugin&nbsp;or&nbsp;hooks&nbsp;+&nbsp;MCP</sub></td>
82
+ <td align="center" valign="bottom" width="25%"><strong>Cursor</strong><br><sub>Hooks&nbsp;+&nbsp;MCP</sub></td>
83
+ <td align="center" valign="bottom" width="25%"><strong>OpenCode</strong><br><sub>Plugin&nbsp;+&nbsp;MCP</sub></td>
84
+ </tr>
85
+ </tbody>
86
+ </table>
87
+
88
+ | Agent | Install |
89
+ |---|---|
90
+ | Claude Code | `claude plugin marketplace add vishnu-77/openreflex` and `claude plugin install openreflex@openreflex`, or `openreflex install claude-code` |
91
+ | Codex | `codex plugin marketplace add vishnu-77/openreflex`, or `openreflex install codex`, then trust the hooks once in `/hooks` |
92
+ | Cursor | `openreflex install cursor` |
93
+ | OpenCode | `openreflex install opencode` |
94
+
95
+ With a plugin install, enable each project with `openreflex approve`. Claude Code is verified in live sessions;
96
+ the Codex, Cursor, and OpenCode integrations follow each agent's documented hook protocol.
97
+
98
+ ## How it works
99
+
100
+ Hooks send lifecycle events (prompt, tool start, tool end, compaction, stop) to the OpenReflex engine, which
101
+ stores them in an **Experience Graph**:
102
+
103
+ ```
104
+ Task -caused-> Execution -used-> Context -used-> Experience
105
+ CandidatePath -recommended_for-> Task Lesson -recommended_for-> Task
106
+ Execution -failed_with-> ToolCall -resolved_by-> ToolCall
107
+ Execution -caused-> Outcome -caused-> Experience -caused-> Lesson
108
+ ```
109
+
110
+ - **Before a task:** similar experiences are retrieved, three strategies (`inspect-first`, `test-first`,
111
+ `incremental`) are scored on success probability, time, tool calls, context cost, risk, uncertainty, and
112
+ reversibility, and a context of at most 1,400 characters is injected. Nothing is injected without relevant
113
+ experience.
114
+ - **During a task:** each alert fires at most once per task with a cooldown, and names a concrete alternative.
115
+ - **After a task:** outcome and chosen path come from the agent's `record_outcome` / `choose_path` MCP calls when
116
+ available, and are otherwise inferred from tool activity. Execution Regret is withheld when the outcome is unknown.
117
+
118
+ Agents can also query OpenReflex directly through its MCP server: `get_execution_context`, `choose_path`,
119
+ `record_outcome`, `search_experience`, `explain_node`, `project_insights`, and `approve_project`.
120
+
121
+ ## CLI
122
+
123
+ | Command | Purpose |
124
+ |---|---|
125
+ | `install <agent> [--dry-run]` | Write project hooks and MCP config, and enable the project |
126
+ | `approve` / `revoke` | Enable or disable capture for the current project |
127
+ | `context "<task>"` | Preview the Execution Context a task would receive |
128
+ | `status [--json]` | What has been captured, reused, and learned |
129
+ | `doctor` | Installation checks and recent hook errors |
130
+ | `forget --yes` | Delete the project's data |
131
+ | `benchmark` | Run the simulated benchmark |
132
+ | `hook <agent> <event>` / `mcp` | Used by agent configs |
133
+
134
+ ## Privacy
135
+
136
+ - Stored per tool call: tool name, a coarse category (`read`, `edit`, `search`, `test`, ...), a fingerprint of the
137
+ arguments, project-relative file paths, status, duration, output size, and a masked one-line error signature.
138
+ - Never stored: file contents, command text, tool output, transcripts, or paths outside the project.
139
+ - Prompts are kept as task descriptions (up to 1,000 characters) with secrets such as API keys and tokens redacted.
140
+ - Data lives in `~/.openreflex/projects/<hash>/experience.sqlite3`. Set `OPENREFLEX_HOME` to move it,
141
+ `OPENREFLEX_DISABLE=1` to turn capture off everywhere, or run `openreflex forget --yes` to delete a project's data.
142
+
143
+ ## Community & Contributing
144
+
145
+ - **Issues and ideas:** [GitHub Issues](https://github.com/vishnu-77/openreflex/issues)
146
+ - **Support the project:** [Buy me a coffee](https://buymeacoffee.com/vishnuprashanth)
147
+ - **Develop locally:**
148
+
149
+ ```bash
150
+ git clone https://github.com/vishnu-77/openreflex && cd openreflex
151
+ pip install -e ".[dev]"
152
+ pytest && ruff check src tests scripts
153
+ ```
154
+
155
+ <a href="https://github.com/vishnu-77/openreflex/graphs/contributors">
156
+ <img src="https://contrib.rocks/image?repo=vishnu-77/openreflex" alt="Contributors">
157
+ </a>
158
+
159
+ ## License
160
+
161
+ OpenReflex is released under the [MIT License](https://github.com/vishnu-77/openreflex/blob/main/LICENSE).
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "openreflex"
7
- version = "0.1.0"
7
+ version = "0.1.2"
8
8
  description = "Muscle memory for AI coding agents: learns from every task, advises the next one, and flags failure loops live"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -27,7 +27,7 @@ classifiers = [
27
27
  ]
28
28
 
29
29
  [project.urls]
30
- Homepage = "https://github.com/vishnu-77/openreflex"
30
+ Homepage = "https://openreflex.cc"
31
31
  Repository = "https://github.com/vishnu-77/openreflex"
32
32
  Issues = "https://github.com/vishnu-77/openreflex/issues"
33
33
 
@@ -1,3 +1,3 @@
1
1
  """Ambient, local execution intelligence."""
2
2
 
3
- __version__ = "0.1.0"
3
+ __version__ = "0.1.2"
@@ -198,7 +198,6 @@ def run_benchmark(episodes: int = 150, seeds: int = 3) -> dict:
198
198
  "baseline": baseline, "guided": guided,
199
199
  "relative_change": {"tool_calls": change("tool_calls"), "tokens": change("tokens"), "time": change("seconds"),
200
200
  "success_rate_points": round(guided["success_rate"] - baseline["success_rate"], 3)},
201
- "targets": {"tool_calls": -0.20, "tokens": -0.20, "time": -0.15, "routing_agreement": 0.70},
202
201
  "per_seed": per_seed,
203
202
  }
204
203
 
@@ -206,20 +205,21 @@ def run_benchmark(episodes: int = 150, seeds: int = 3) -> dict:
206
205
  def format_report(report: dict) -> str:
207
206
  b, g, c = report["baseline"], report["guided"], report["relative_change"]
208
207
  rows = [
209
- ("tool calls / task", b["tool_calls"], g["tool_calls"], f"{c['tool_calls']:+.0%}", "-20..-30%"),
210
- ("output tokens / task", b["tokens"], g["tokens"], f"{c['tokens']:+.0%}", "-20%"),
211
- ("time / task (s)", b["seconds"], g["seconds"], f"{c['time']:+.0%}", "-15%"),
212
- ("success rate", b["success_rate"], g["success_rate"], f"{c['success_rate_points']:+.3f} pts", ">= baseline"),
213
- ("regret, first quarter", b["regret_first_quarter"], g["regret_first_quarter"], "", ""),
214
- ("regret, last quarter", b["regret_last_quarter"], g["regret_last_quarter"], "", "declining"),
215
- ("routing agreement (2nd half)", "-", g["routing_agreement_second_half"], "", "> 0.70"),
208
+ ("tool calls / task", b["tool_calls"], g["tool_calls"], f"{c['tool_calls']:+.0%}"),
209
+ ("output tokens / task", b["tokens"], g["tokens"], f"{c['tokens']:+.0%}"),
210
+ ("time / task (s)", b["seconds"], g["seconds"], f"{c['time']:+.0%}"),
211
+ ("success rate", b["success_rate"], g["success_rate"], f"{c['success_rate_points']:+.3f} pts"),
212
+ ("regret, first quarter", b["regret_first_quarter"], g["regret_first_quarter"], ""),
213
+ ("regret, last quarter", b["regret_last_quarter"], g["regret_last_quarter"], ""),
214
+ ("routing agreement (2nd half)", "-", g["routing_agreement_second_half"], ""),
216
215
  ]
217
216
  lines = [f"SIMULATED benchmark - {report['episodes_per_arm']} tasks/arm x {report['seeds']} seeds "
218
217
  "(assumption-driven; not evidence of real-world gains)", ""]
219
- lines.append(f"{'metric':30} {'baseline':>10} {'guided':>10} {'change':>12} target")
218
+ lines.append(f"{'metric':30} {'baseline':>10} {'guided':>10} {'change':>12}")
219
+
220
220
  def cell(value):
221
221
  return f"{value:,.3f}".rstrip("0").rstrip(".") if isinstance(value, float) else str(value)
222
222
 
223
- for name, base, guide, delta, target in rows:
224
- lines.append(f"{name:30} {cell(base):>10} {cell(guide):>10} {delta:>12} {target}")
223
+ for name, base, guide, delta in rows:
224
+ lines.append(f"{name:30} {cell(base):>10} {cell(guide):>10} {delta:>12}")
225
225
  return "\n".join(lines)
@@ -96,7 +96,7 @@ def cmd_status(args) -> int:
96
96
  print(f" tasks: {data['engagement']['tasks']} experiences: {data['engagement']['experiences']} lessons: {data['lessons']}")
97
97
  print(f" first session captured: {data['activation']['first_session_captured']} "
98
98
  f"seconds to first task: {data['activation']['seconds_to_first_task']}")
99
- print(f" tasks benefiting from prior experience: {reuse['benefit_rate']}")
99
+ print(f" tasks that used prior experience: {reuse['benefit_rate']}")
100
100
  print(f" success rate (known outcomes): {data['outcomes']['success_rate']} verified: {data['outcomes']['verified']}")
101
101
  print(f" tool calls with vs without prior experience: {eff['with_prior_experience']['tool_calls']} vs "
102
102
  f"{eff['without_prior_experience']['tool_calls']} (observational)")
@@ -0,0 +1,193 @@
1
+ Metadata-Version: 2.4
2
+ Name: openreflex
3
+ Version: 0.1.2
4
+ Summary: Muscle memory for AI coding agents: learns from every task, advises the next one, and flags failure loops live
5
+ Author: vishnu-77
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://openreflex.cc
8
+ Project-URL: Repository, https://github.com/vishnu-77/openreflex
9
+ Project-URL: Issues, https://github.com/vishnu-77/openreflex/issues
10
+ Keywords: ai-agents,coding-agents,claude-code,codex,cursor,opencode,mcp,memory,hooks
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Software Development
20
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
21
+ Requires-Python: >=3.11
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: mcp<2,>=1.26
25
+ Requires-Dist: pydantic<3,>=2.10
26
+ Provides-Extra: dev
27
+ Requires-Dist: pytest<9,>=8; extra == "dev"
28
+ Requires-Dist: ruff>=0.12; extra == "dev"
29
+ Requires-Dist: build>=1.2; extra == "dev"
30
+ Requires-Dist: twine>=6; extra == "dev"
31
+ Dynamic: license-file
32
+
33
+ <div align="center">
34
+
35
+ <a href="https://openreflex.cc" target="_blank">
36
+ <picture>
37
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/openreflex-logo-dark.svg">
38
+ <img alt="OpenReflex" src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/openreflex-logo-light.svg" width="380" height="auto">
39
+ </picture>
40
+ </a>
41
+
42
+ ### OpenReflex: muscle memory for AI coding agents
43
+
44
+ <a href="https://openreflex.cc">Website</a> · <a href="https://github.com/vishnu-77/openreflex">GitHub</a> · <a href="https://pypi.org/project/openreflex/">PyPI</a> · <a href="https://github.com/vishnu-77/openreflex/issues">Issues</a> · <a href="https://buymeacoffee.com/vishnuprashanth">Buy me a coffee</a>
45
+
46
+ [![PyPI](https://img.shields.io/pypi/v/openreflex?style=flat-square&labelColor=black&color=286a70)](https://pypi.org/project/openreflex/)
47
+ [![Python](https://img.shields.io/pypi/pyversions/openreflex?style=flat-square&labelColor=black&color=7cc9c8)](https://pypi.org/project/openreflex/)
48
+ [![CI](https://img.shields.io/github/actions/workflow/status/vishnu-77/openreflex/ci.yml?branch=main&style=flat-square&labelColor=black&label=CI)](https://github.com/vishnu-77/openreflex/actions/workflows/ci.yml)
49
+ [![License](https://img.shields.io/badge/license-MIT-white?style=flat-square&labelColor=black)](https://github.com/vishnu-77/openreflex/blob/main/LICENSE)
50
+
51
+ </div>
52
+
53
+ ***
54
+
55
+ ## What is OpenReflex
56
+
57
+ OpenReflex gives AI coding agents muscle memory. It plugs into Claude Code, Codex, Cursor, and OpenCode through
58
+ lifecycle hooks and MCP, quietly records how each task actually went, and hands the next similar task what worked
59
+ before: the approach, the files that mattered, and the fix for the error you hit last time.
60
+
61
+ You install it once and keep working normally. Everything stays on your machine in a local SQLite database.
62
+ There is no account, no service, and no telemetry.
63
+
64
+ ## Why OpenReflex
65
+
66
+ - **It remembers what worked.** Before a substantial task, OpenReflex retrieves similar past tasks and injects a
67
+ compact Execution Context: a suggested approach with alternatives, the files that were changed, and lessons
68
+ such as which edit resolved a recurring error.
69
+ - **It catches loops while they happen.** Repeated failing commands, identical retries, stalled progress, and
70
+ runaway context growth raise a single, specific alert with an alternative path, never a stream of nags.
71
+ - **It learns after every task.** OpenReflex infers the outcome from real verification (a test or build that
72
+ passed or failed after the last edit), estimates Execution Regret against the alternatives, and extracts lessons.
73
+ - **It is private by design.** Only coarse, project-relative metadata is stored. File contents, commands, tool
74
+ output, and transcripts never are, and capture is off until you approve a project.
75
+
76
+ ```
77
+ before a task during a task after a task
78
+ ┌──────────────────────┐ ┌──────────────────────────┐ ┌───────────────────────┐
79
+ │ retrieve experience │ │ watch tool calls │ │ infer outcome │
80
+ │ score candidate paths│ → │ flag loops and stalls │ → │ estimate regret │
81
+ │ inject context │ │ suggest an alternative │ │ extract lessons │
82
+ └──────────────────────┘ └──────────────────────────┘ └───────────────────────┘
83
+ ▲ │
84
+ └──────────────────── Experience Graph ◄─────────────────┘
85
+ ```
86
+
87
+ ## Quick start
88
+
89
+ Requires Python 3.11 or newer.
90
+
91
+ ```bash
92
+ pipx install openreflex # or: uv tool install openreflex
93
+ cd your-project
94
+ openreflex install claude-code # writes hooks + MCP config and enables this project
95
+ ```
96
+
97
+ Then work as usual. After a few tasks:
98
+
99
+ ```bash
100
+ openreflex context "fix the login redirect bug" # preview the context a task would receive
101
+ openreflex status # what has been captured and learned
102
+ openreflex doctor # installation checks and recent hook errors
103
+ ```
104
+
105
+ ## Use it with your agent
106
+
107
+ OpenReflex installs per project with `openreflex install <agent>`, or as a plugin.
108
+
109
+ <table>
110
+ <tbody>
111
+ <tr>
112
+ <td align="center" valign="bottom" width="25%"><strong>Claude&nbsp;Code</strong><br><sub>Plugin&nbsp;or&nbsp;hooks&nbsp;+&nbsp;MCP</sub></td>
113
+ <td align="center" valign="bottom" width="25%"><strong>Codex</strong><br><sub>Plugin&nbsp;or&nbsp;hooks&nbsp;+&nbsp;MCP</sub></td>
114
+ <td align="center" valign="bottom" width="25%"><strong>Cursor</strong><br><sub>Hooks&nbsp;+&nbsp;MCP</sub></td>
115
+ <td align="center" valign="bottom" width="25%"><strong>OpenCode</strong><br><sub>Plugin&nbsp;+&nbsp;MCP</sub></td>
116
+ </tr>
117
+ </tbody>
118
+ </table>
119
+
120
+ | Agent | Install |
121
+ |---|---|
122
+ | Claude Code | `claude plugin marketplace add vishnu-77/openreflex` and `claude plugin install openreflex@openreflex`, or `openreflex install claude-code` |
123
+ | Codex | `codex plugin marketplace add vishnu-77/openreflex`, or `openreflex install codex`, then trust the hooks once in `/hooks` |
124
+ | Cursor | `openreflex install cursor` |
125
+ | OpenCode | `openreflex install opencode` |
126
+
127
+ With a plugin install, enable each project with `openreflex approve`. Claude Code is verified in live sessions;
128
+ the Codex, Cursor, and OpenCode integrations follow each agent's documented hook protocol.
129
+
130
+ ## How it works
131
+
132
+ Hooks send lifecycle events (prompt, tool start, tool end, compaction, stop) to the OpenReflex engine, which
133
+ stores them in an **Experience Graph**:
134
+
135
+ ```
136
+ Task -caused-> Execution -used-> Context -used-> Experience
137
+ CandidatePath -recommended_for-> Task Lesson -recommended_for-> Task
138
+ Execution -failed_with-> ToolCall -resolved_by-> ToolCall
139
+ Execution -caused-> Outcome -caused-> Experience -caused-> Lesson
140
+ ```
141
+
142
+ - **Before a task:** similar experiences are retrieved, three strategies (`inspect-first`, `test-first`,
143
+ `incremental`) are scored on success probability, time, tool calls, context cost, risk, uncertainty, and
144
+ reversibility, and a context of at most 1,400 characters is injected. Nothing is injected without relevant
145
+ experience.
146
+ - **During a task:** each alert fires at most once per task with a cooldown, and names a concrete alternative.
147
+ - **After a task:** outcome and chosen path come from the agent's `record_outcome` / `choose_path` MCP calls when
148
+ available, and are otherwise inferred from tool activity. Execution Regret is withheld when the outcome is unknown.
149
+
150
+ Agents can also query OpenReflex directly through its MCP server: `get_execution_context`, `choose_path`,
151
+ `record_outcome`, `search_experience`, `explain_node`, `project_insights`, and `approve_project`.
152
+
153
+ ## CLI
154
+
155
+ | Command | Purpose |
156
+ |---|---|
157
+ | `install <agent> [--dry-run]` | Write project hooks and MCP config, and enable the project |
158
+ | `approve` / `revoke` | Enable or disable capture for the current project |
159
+ | `context "<task>"` | Preview the Execution Context a task would receive |
160
+ | `status [--json]` | What has been captured, reused, and learned |
161
+ | `doctor` | Installation checks and recent hook errors |
162
+ | `forget --yes` | Delete the project's data |
163
+ | `benchmark` | Run the simulated benchmark |
164
+ | `hook <agent> <event>` / `mcp` | Used by agent configs |
165
+
166
+ ## Privacy
167
+
168
+ - Stored per tool call: tool name, a coarse category (`read`, `edit`, `search`, `test`, ...), a fingerprint of the
169
+ arguments, project-relative file paths, status, duration, output size, and a masked one-line error signature.
170
+ - Never stored: file contents, command text, tool output, transcripts, or paths outside the project.
171
+ - Prompts are kept as task descriptions (up to 1,000 characters) with secrets such as API keys and tokens redacted.
172
+ - Data lives in `~/.openreflex/projects/<hash>/experience.sqlite3`. Set `OPENREFLEX_HOME` to move it,
173
+ `OPENREFLEX_DISABLE=1` to turn capture off everywhere, or run `openreflex forget --yes` to delete a project's data.
174
+
175
+ ## Community & Contributing
176
+
177
+ - **Issues and ideas:** [GitHub Issues](https://github.com/vishnu-77/openreflex/issues)
178
+ - **Support the project:** [Buy me a coffee](https://buymeacoffee.com/vishnuprashanth)
179
+ - **Develop locally:**
180
+
181
+ ```bash
182
+ git clone https://github.com/vishnu-77/openreflex && cd openreflex
183
+ pip install -e ".[dev]"
184
+ pytest && ruff check src tests scripts
185
+ ```
186
+
187
+ <a href="https://github.com/vishnu-77/openreflex/graphs/contributors">
188
+ <img src="https://contrib.rocks/image?repo=vishnu-77/openreflex" alt="Contributors">
189
+ </a>
190
+
191
+ ## License
192
+
193
+ OpenReflex is released under the [MIT License](https://github.com/vishnu-77/openreflex/blob/main/LICENSE).