claude-smart: Turning Corrections into Skills for Claude Code, Codex, and OpenCode

The gap claude-smart targets: recording a mistake versus changing the next session

Most agent memory tools store what happened. The README draws a line between that and what it calls learning, and the distinction is concrete rather than rhetorical. Its own example: a deploy fails after Claude bumps prisma from 5.x to 6.0, you say roll back because 6.0 breaks nested writes in your order flow. A memory tool would record "deploy broke after prisma bump; user rolled back". claude-smart instead aims to produce a rule of the form "treat major-version bumps of ORMs/DB drivers as breaking, verify with integration tests, not just unit tests". The second artifact is portable to the next session; the first is a log entry. The second example in the README is the more telling one for daily work: a repo where the local stack only starts with pnpm dev:all, not npm run dev. Memory preserves the complaint. Learning preserves the command. Whoever is installing this is a developer running an agent CLI locally, correcting the same class of mistake across sessions, and tired of paying the exploration cost again. It is not aimed at teams who want a shared, server-side knowledge base, because the design is explicitly local-first.

Lifecycle hooks, an in-process ONNX embedder, and three scopes of learned rule

The mechanism the README describes has three parts. First, capture: every user turn, tool call and assistant response is collected through lifecycle hooks, with no manual trigger. Second, extraction: those captures become structured, deduplicated rules rather than transcript replays, and the README says this happens automatically. Third, retrieval: semantic search runs on an in-process ONNX embedder using all-MiniLM-L6-v2, with no external API call. That last point is the architecture decision worth dwelling on. Running the embedder in-process means no network round trip and no key to manage, but it also means the model ships with the plugin and executes on your hardware. The rules themselves live in three scopes. Preferences stay scoped to the current project, so per-repo preferences do not leak across projects. Project-specific skills capture repo-local rules. Shared skills roll up patterns intended to transfer between projects. The README also claims the library is continuously refined rather than append-only: wording is clarified, when-to-apply triggers tighten or broaden as evidence accumulates, near-duplicates merge, stale rules are superseded and dead ones are archived. Its illustration of that loop is a repeated npm test --run gotcha consolidating into one rule, then broadening to vitest when new evidence appears, then being archived when policy switches to pnpm test. Treat that as a described design, not an observed one; the README does not show the merge or archive logic itself.

Installing into Claude Code, Codex or OpenCode, and what uninstall leaves behind

Requirements are Node.js 20 or later for npx and the target host CLI on PATH. For Claude Code the command is npx claude-smart install, followed by a restart of Claude Code. For Codex it is npx claude-smart install --host codex, and the README says to fully quit and reopen Codex so hooks reload. For OpenCode it is npx claude-smart install --host opencode, then restart OpenCode in your project so it loads the plugin from opencode.json; adding --global installs for all OpenCode projects on the machine. Removal mirrors the install: npx claude-smart uninstall, or the same command with --host codex or --host opencode, with a host restart afterward. The important detail is what uninstall does not do. Learned data under ~/.reflexio/ and ~/.claude-smart/ is preserved and shared across hosts, so switching from Claude Code to Codex or back does not discard accumulated skills and preferences. That is a deliberate design choice and it cuts both ways: reinstalling is cheap, but so is leaving state on disk that you may have forgotten about. The README points to DEVELOPER.md for per-host installer and uninstaller details, OpenCode config resolution, model and environment overrides, and Windows notes. If you are installing on Windows or overriding the OpenCode model, read that file first, because the README does not reproduce those specifics.

The hosts that cannot run it, and the benchmark you should not take on faith

The README states plainly that Claude Code Cowork, claude.ai/code web and remote Codex environments without local plugin hooks are not supported. The reason given is that they run outside your local machine, so the local backend, the dashboard and ~/.reflexio/ are not reachable. This is not a configuration problem you can work around; the learning loop depends on local hooks and local storage, so a hosted or remote agent session has nowhere to write. That single constraint disqualifies a whole class of users, and it is the first thing to check against how your team actually runs its agents. The second thing to check is the comparison the README makes against claude-mem: roughly 3x better at turning corrections into rules Claude follows, and roughly 50% more of your guidance retained, with a link to EXPERIMENT.md. Those are the project's own numbers from its own experiment. No third-party replication is cited in the material available, and the benchmark design, the scoring method and the sample are not summarised in the README. A reader deciding whether to adopt should open EXPERIMENT.md and judge whether the evaluation matches their own usage, rather than repeating the multiplier. The same caution applies to the token claim, that distilled skills stay in dozens of tokens rather than thousands even as a project grows. That is a plausible consequence of deduplication, but it is asserted, not demonstrated in the README.

How claude-smart differs from claude-mem and from plain CLAUDE.md files

The nearest named alternative in the material is claude-mem, and the difference is not the storage layer but the output artifact. A memory-oriented tool records what happened so it can be recalled later; claude-smart's stated goal is to emit rules the agent follows on the next run, with an explicit lifecycle for those rules: merge near-duplicates, broaden or tighten triggers, supersede stale entries, archive dead ones. If your problem is "I cannot find what we decided three weeks ago", a retrieval tool addresses it. If your problem is "the agent keeps making the same category of mistake and I keep re-explaining it", the rule-extraction approach is the one aimed at you. The other alternative is the one most teams already use: hand-written instruction files such as CLAUDE.md or AGENTS.md, maintained by a human. That approach has no runtime, no Node dependency, no embedder and nothing to uninstall, and it is fully auditable because a person wrote every line. What it lacks is automatic capture and the refinement loop. A hand-maintained file grows stale silently and depends on someone remembering to edit it after a correction. claude-smart trades that manual upkeep for an automated pipeline whose judgement you have to trust. Neither is strictly better; they fail in opposite directions, one by neglect and one by automation you have not inspected.

Maintenance surface, versioning and the Apache-2.0 licence

The version badge in the README points at plugin/pyproject.toml and reads 0.2.50, which tells you the project ships frequently and that the minor version has not yet reached 1.0. Treat pre-1.0 as a real signal here: the rule lifecycle described in the README (merging, broadening, superseding, archiving) is the kind of behaviour that changes shape as evidence accumulates in real repositories. No releases were retrieved for this review, so there is no changelog to reason about. The runtime requirements are the practical maintenance cost: Python 3.12 or later for the plugin, Node 20 or later for the npx installer, and an ONNX embedder executing locally. The embedder is bundled rather than called over the network, which removes an API dependency and an API bill, but it does mean local CPU and memory are consumed on your machine and that model updates arrive with plugin updates. The licence is Apache-2.0, which permits commercial and private use and includes an explicit patent grant, with the usual obligations around preserving notices and stating changes. That is a permissive licence and a reasonable fit for internal developer tooling. This is a description of the licence text, not legal advice; if you are redistributing a modified plugin or embedding it in a product, have your own counsel read the NOTICE and attribution requirements.

What to verify before you let it write rules into your repositories

Start by confirming your host is one of the three supported local setups. If your team works in claude.ai/code web or a remote Codex environment, stop here, because the README is explicit that the local backend and ~/.reflexio/ are unreachable and the plugin cannot function. If you are on a supported host, install into a single throwaway repository first rather than with --global, so the shared-skill rollup has one project's worth of evidence to work from and you can see what it produces. Then inspect the actual files under ~/.reflexio/ and ~/.claude-smart/ after a few sessions of deliberate correction, and check two things: whether the extracted rules are phrased as instructions the agent can act on, and whether anything landed in shared skills that you would not want applied to a different repository. The scoping claim, that preferences stay project-local while shared skills transfer, is the one to test directly, because a leak there is the failure mode with the widest blast radius. Finally, open EXPERIMENT.md and decide whether its evaluation resembles your work before you quote the 3x figure to anyone. The uninstall path preserves your learned data by design, so if you decide the extracted rules are not good enough, removing the plugin will not remove them; you will have to clean those directories yourself.

Editorial conclusion

Adopt claude-smart if you already run Claude Code, Codex or OpenCode locally, you correct the same agent repeatedly, and you want those corrections stored as rules under ~/.reflexio/ rather than re-typed each session. Do not adopt it if your agent runs in Claude Code Cowork, claude.ai/code web or a remote Codex environment without local plugin hooks, because the README states the local backend and ~/.reflexio/ are unreachable there, and do not adopt it if a Node 20 runtime and an in-process ONNX embedder on your machine are unacceptable. Before installing, read EXPERIMENT.md and reproduce the claude-mem comparison yourself, since the roughly 3x and 50% figures are the project's own benchmark and no independent run is cited.

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. ReflexioAI/claude-smart on GitHub