claude-smart

---

Quick Start

Requires Node.js 20+ (for npx) and the host CLI you're installing into (claude, codex, or opencode) on PATH.

Claude Code

npx claude-smart install

Then restart Claude Code.

Codex

npx claude-smart install --host codex

Then fully quit and reopen Codex so hooks reload.

OpenCode

npx claude-smart install --host opencode

Then restart OpenCode in your project so it loads the plugin from opencode.json. Add --global to install for all OpenCode projects on this machine instead.

Uninstall

npx claude-smart uninstall                    # Claude Code
npx claude-smart uninstall --host codex       # Codex
npx claude-smart uninstall --host opencode    # OpenCode

Restart the host afterward. Learned data under ~/.reflexio/ and ~/.claude-smart/ is preserved and shared across hosts, so you can uninstall or switch hosts without losing skills or preferences.

For per-host details — the Claude Code plugin-marketplace alternative, what the installers and uninstallers touch, OpenCode config resolution and model/env overrides, and Windows notes — see Host install notes in DEVELOPER.md. Developing the plugin itself? See Developing locally.

Not supported: Claude Code Cowork, claude.ai/code web, or remote Codex environments without local plugin hooks — they run outside your local machine, so the local backend/dashboard and ~/.reflexio/ aren't reachable.

---

Why Learning, Not Memory

Most memory tools just record. Claude remembers what happened, but doesn't change what it does next.

claude-smart focuses on learning instead.

Four things this changes:

• 💡 Stop repeating the same mistakes: Produces actionable skills Claude can follow next time; memory only records what happened.

  Example: a deploy fails after Claude bumps prisma from 5.x to 6.0; you tell it to roll back because 6.0 breaks nested writes in your order flow. Memory: “deploy broke after prisma bump; user rolled back” Learning: “treat major-version bumps of ORMs/DB drivers as breaking — verify with integration tests, not just unit tests”

• 🚀 Start from the optimized path: Records and optimizes the steps that worked so Claude can reuse them, instead of re-exploring each session.

  Example: Claude spends several iterations trying to start the local dev environment before discovering that this repo requires pnpm dev:all instead of the usual npm run dev. Memory: “user mentioned that npm run dev did not work” Learning: “for this repo, always use pnpm dev:all to start the full local stack — npm run dev only starts the frontend and causes missing service errors”

  Instead of re-exploring, Claude Code starts from the proven path—reducing planning steps, latency, and token usage.

• 🌐 Project-specific and shared skills: Session memory disappears with the conversation. Project-specific skills preserve repo-local rules, while shared skills roll up patterns that should transfer across projects. Preferences stay scoped to the current project so per-repo preferences don't leak across projects.

• 🪶 Better context without prompt bloat: Distilled, deduplicated skills stay in dozens of tokens—not thousands—even as the project grows.

---

Demo

https://github.com/user-attachments/assets/ed84d73a-d5b7-4a0d-ab2c-f2c060c3f276

---

Key Features

• 🧠 Learn, don't just remember — Corrections become structured, deduplicated rules, not transcript replays.
• ⚡ Fully automatic learning — Every user turn, tool call, and assistant response is captured via lifecycle hooks and extracted into rules without you running anything.
• 📈 Continuously self-tuning, not just append-on-conflict — Existing rules are continuously refined, not just appended to. 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 library gets sharper, not just bigger.

  e.g. correct the same npm test --run gotcha twice → consolidated into one rule. New evidence shows it applies to vitest too → scope broadened. Switch policy to pnpm test → old rule archived, new one supersedes it.

• 🔌 No external API call — semantic search runs on an in-process ONNX embedder (all-MiniLM-L6-v2), and all data (preferences, skills, interaction buffers) is stored locally on your machine (~/.reflexio/ and ~/.claude-smart/).
• 🔎 Hybrid search — Skills and preferences are indexed with vector + BM25 search for fast, robust retrieval.
• 🧪 Offline resilience — If the reflexio backend is down, hooks buffer to disk; the next successful publish drains them.
• 🧰 Manual correction marker — /claude-smart:learn in Claude Code, or bash ~/.reflexio/plugin-root/scripts/cli.sh learn in Codex, flags the last turn as a correction so the extractor weights it heavily.

---

Dashboard

A web UI for browsing session histories, inspecting preferences, and editing project-specific and shared skills. The dashboard auto-starts alongside the backend, so you can open http://localhost:3001 directly. Or run /claude-smart:dashboard in Claude Code to open it in your browser. In Codex, run bash ~/.reflexio/plugin-root/scripts/dashboard-open.sh.

---

How It Works

claude-smart builds three artifacts as you work and injects the relevant ones into Claude Code, Codex, or OpenCode:

• Preferences (project-scoped) — how you work in this specific repo (stack, role, small quirks). e.g. "uses pnpm, not npm"; "prefers terse answers"; "backend engineer — explain frontend with backend analogues."
• Project-specific skills — durable rules with triggers and rationales learned from corrections in a project. e.g. "always pass --run to npm test — watch mode hangs CI."
• Shared skills — optimized rollups of project-specific skills that should transfer across projects. e.g. "use real Postgres for integration tests — mocks once hid a broken migration."

Skills clean themselves up: correct the same thing twice and they merge; change your mind and the old one is archived.

Under the hood: hooks watch your turns, tool calls, and assistant replies, auto-flagging corrections (or anything you flag with /claude-smart:learn). At session end (or on /claude-smart:learn), reflexio — the self-improving engine that powers claude-smart — extracts preferences and project-specific skills, then rolls durable patterns into shared skills. On each new user prompt, claude-smart searches for matching context and injects only the relevant hits. Run /claude-smart:show or the equivalent CLI command to audit the current learned state. Everything runs on your machine.

Citations. At the end of a reply, the assistant may append a short marker:

✨ claude-smart rule applied: [git safety](http://localhost:3001/rules/s1-123) | [brief answer preference](http://localhost:3001/rules/p1-pref) · [⚡Reflexio](https://github.com/ReflexioAI/reflexio)

That signals a preference or skill materially shaped the reply. Open the session's detail page in the dashboard to see the exact cited item.

See ARCHITECTURE.md for hooks, data flow, and reflexio details.

---

Commands

Claude Code installs these as plugin slash commands. Codex does not currently support plugin-provided slash commands, so claude-smart ships a Codex skill that maps requests like "claude-smart show" or "run claude-smart learn" to the equivalent action.

---

Configuration

Advanced users can tune claude-smart via environment variables — see DEVELOPER.md for the full list.

Where data lives

For troubleshooting, see TROUBLESHOOTING.md.

---

Powered by Reflexio

claude-smart is powered by Reflexio (reflexio.ai) — the open-source self-improving engine that turns interactions into durable, reusable skills. If claude-smart is useful to you, ⭐ star reflexio on GitHub.

---

License

This project is licensed under the Apache License 2.0. Reflexio is a separate Apache 2.0 project consumed as the reflexio-ai Python package. Claude Code is Anthropic's and not covered by this license.

See the LICENSE file for details.

---

Support

• Discord: join the community at discord.gg/7fnCxahase.
• Issues: open one on GitHub describing the symptom and include the reflexio backend log (~/.claude-smart/backend.log) and the relevant lines of ~/.claude-smart/sessions/{session_id}.jsonl.

---

Powered by Reflexio · Runs on Claude Code, Codex, and OpenCode · Written in Python 3.12+