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

What claude-smart actually solves, and for whom

Most agent memory tools record what happened. claude-smart's README makes a sharper claim: it turns interactions into skills the assistant follows in future sessions. The distinction is spelled out with a Prisma example. A memory tool would store "deploy broke after prisma bump; user rolled back". claude-smart would store "treat major-version bumps of ORMs/DB drivers as breaking, verify with integration tests, not just unit tests". One is a log entry. The other changes the next decision.

The target user is someone running Claude Code, Codex or OpenCode locally on a repository they return to. The plugin keeps three kinds of output: Preferences, Project-specific skills, and Shared skills. Preferences stay scoped to the current project, so per-repo preferences do not leak into other repositories. Project-specific skills hold repo-local rules. Shared skills roll up patterns considered durable enough to transfer across projects.

That three-way split is the part worth judging. A rule like "this repo uses pnpm dev:all, not npm run dev" is meaningless in another codebase, so keeping it project-scoped is correct. A rule like "verify ORM major bumps with integration tests" is a general engineering habit, so promoting it to shared is reasonable. The plugin's value depends on that promotion being right often enough.

How the learning loop works: hooks in, distilled rules out

The README states that every user turn, tool call and assistant response is captured via lifecycle hooks, and that extraction happens without you running anything. That is the whole mechanism at a high level: the host fires hooks, the plugin observes, and rules are written out.

Two design choices stand out. First, semantic search runs on an in-process ONNX embedder using all-MiniLM-L6-v2, and the README states there is no external API call. That matters for anyone working in a private repository, because the correction text does not leave the machine for embedding. Second, the rule library is described as continuously refined rather than append-only. The README lists the operations: wording gets clearer, when-to-apply triggers tighten or broaden as evidence accumulates, near-duplicates merge, stale rules are superseded, and dead ones are archived.

The worked example is concrete. Correct the same npm test --run gotcha twice and the plugin consolidates it into one rule. New evidence shows it applies to vitest too, and the scope broadens. Switch policy to pnpm test and the old rule is archived while a new one supersedes it. This is a mutation model, not an append model, and it is the main architectural difference from a transcript store. The risk is symmetrical: a merge that fires too eagerly can collapse two rules that were genuinely separate, and the README does not describe a manual review step before supersession.

Installing claude-smart and getting one real rule out of it

The prerequisites are Node.js 20+ for npx, plus the host CLI you are installing into (claude, codex or opencode) on PATH. For Claude Code, the README gives a single command:

npx claude-smart install

After it finishes, restart Claude Code. For Codex the install takes a host flag, and the README says to fully quit and reopen Codex so hooks reload:

npx claude-smart install --host codex

OpenCode follows the same pattern. Restart OpenCode inside your project so it loads the plugin from opencode.json:

npx claude-smart install --host opencode

Add --global to that command to install for all OpenCode projects on the machine instead of just the current one. Uninstalling uses the same host flag, for example npx claude-smart uninstall --host codex, followed by a host restart. Learned data under ~/.reflexio/ and ~/.claude-smart/ is preserved across uninstall and shared between hosts, so switching from Codex to OpenCode does not wipe your skills.

A first real use: work in one repository, make a mistake the assistant repeats, and correct it twice. The README's own example is a dev command. If the assistant keeps reaching for npm run dev and the repo needs pnpm dev:all, correct it the first time, then correct it again in a later session. According to the README, the second correction should consolidate into one rule rather than producing two near-identical entries. That consolidation is the thing to watch, because it is the behaviour that separates this from a memory log.

Where claude-smart does not work, and what the README leaves open

The README is unusually direct about one boundary. Claude Code Cowork, claude.ai/code web, and remote Codex environments without local plugin hooks are listed as not supported, because they run outside your local machine and the local backend, dashboard and ~/.reflexio/ are not reachable. If your team works primarily in a hosted agent environment, this plugin is the wrong tool regardless of how good the learning is.

The second constraint is host coupling. Everything depends on lifecycle hooks firing, and the README tells Codex users to fully quit and reopen so hooks reload. A host update that changes hook behaviour is a failure mode the plugin cannot control. The troubleshooting page exists, which suggests hook and install problems are expected enough to document.

There is also a benchmark claim in the README: roughly 3x better than claude-mem at turning corrections into rules Claude follows, and roughly 50% more guidance retained, pointing at EXPERIMENT.md. Treat that as the project's own experiment rather than an independent result. The README does not describe what happens when two projects disagree about the same shared skill, and it does not document a review queue before a rule is superseded. Both are real gaps for anyone who wants to audit what the assistant has learned.

claude-smart versus claude-mem and plain CLAUDE.md files

claude-mem is the comparison the README itself makes, and the difference is in the output artifact. A memory tool stores what happened and retrieves it later. claude-smart stores rules with when-to-apply triggers and then mutates them as evidence accumulates. If you have ever wanted your assistant to stop making the same mistake rather than merely recall making it, that is the gap being targeted.

The more common alternative is a hand-written instruction file, such as CLAUDE.md or an equivalent project rules file. The approach differs in who does the work and when it happens. A hand-written file is authored up front, is fully reviewable, and does not change unless a human edits it. claude-smart writes rules automatically from observed corrections and then refines them without a human in the loop. You trade auditability for coverage: the hand-written file never captures the twenty small corrections you made last week, and claude-smart does not give you a diff before it rewrites a rule.

For a small project with a few stable conventions, a checked-in rules file is cheaper and easier to reason about. For a long-lived repository where the assistant keeps rediscovering the same local commands and the same library gotchas, automatic extraction earns its keep. The README also notes that distilled skills stay in dozens of tokens rather than thousands, which is the argument against dumping every lesson into a growing prompt.

Maintenance, release flow and the Apache-2.0 licence

The repository's last push was on 2026-08-28, which is recent, and it is not archived. There are no retrieved releases, and the version in package.json is 0.2.50, so the project is versioned but the release list is not visible in the repository metadata available.

Upgrade cost is low by design. The Makefile states that claude-smart is distributed exclusively via npm and is no longer published to PyPI, so uvx install is unsupported. The reflexio-ai dependency still resolves from PyPI, and a release vendors the current reflexio submodule. That means the plugin and its engine move together: reflexio.lock.json pins the engine, and a release re-vendors it. If you are tracking the project, the npm package is the only channel to watch.

The Makefile also documents the release flow for maintainers (make bump, make release-npm, make publish), and notes that .claude-plugin/marketplace.json is generated at pack time from package.json's version by scripts/generate-marketplace.js via the prepack hook, so it is not bumped by hand. That is a small but real maintenance detail: the marketplace manifest follows the package version automatically.

On licensing, the project is Apache-2.0, which permits commercial use and modification with the usual notice and patent terms. If you plan to redistribute a modified plugin, read LICENSE and the vendored reflexio engine's own terms before shipping. That is a factual pointer, not legal advice.

Editorial conclusion

Adopt claude-smart if you work in Claude Code, Codex or OpenCode on a machine where local hooks run, and you want corrections to become reusable rules instead of transcript notes. Skip it on Claude Code Cowork, claude.ai/code web, or remote Codex environments, because the README states the local backend and ~/.reflexio/ are unreachable there. Before trusting it, run npx claude-smart install, restart the host, correct the same mistake twice in one repo, and check whether the second correction produced a merged rule rather than a duplicate.

Frequently asked questions

Official sources

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