claude-smart

Quick Start

Claude Code

npx claude-smart install     # or: uvx claude-smart install

Then restart Claude Code.

Requires Node.js (for npx) or uv (for uvx) to already exist.

Alternatively, install via Claude Code's plugin marketplace:

claude plugin marketplace add ReflexioAI/claude-smart
claude plugin install claude-smart@reflexioai

To uninstall:

npx claude-smart uninstall     # or: uvx claude-smart uninstall

Or, if installed via the plugin marketplace:

claude plugin uninstall claude-smart@reflexioai

Codex

npx claude-smart install --host codex

Then fully quit and reopen Codex so hooks reload.

Requires the codex CLI on PATH and Node.js (for npx).

To uninstall:

npx claude-smart uninstall --host codex

Restart Codex after uninstalling. Learned data under ~/.reflexio/ and ~/.claude-smart/ is preserved and shared with Claude Code, so you can switch between hosts without losing skills or preferences.

Developing the plugin itself? See DEVELOPER.md for what the installer does, manual toggles via /plugins, and clone-based development.

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.

Vanilla OS support

| Platform | Status | Notes | | --- | --- | --- | | Apple Silicon macOS 14+ | Supported | Runtime bootstrap installs private Node/npm, uv, Python 3.12 deps, and dashboard deps. | | Windows x64 | Supported | Runtime bootstrap uses PowerShell for uv/Node archive extraction and patches Codex hooks to the Node wrapper. | | Linux | Supported when host hooks are local | Existing Linux behavior is preserved; install coverage depends on available Python wheels. | | Intel Mac, macOS 13 or older, Windows ARM | Not supported | Current local embedding/ML dependencies do not publish a complete native wheel set for these targets. |

Network access is required during first install for npm, PyPI/uv, Node.js, and the first local embedding model download. The ONNX model cache lives at ~/.cache/chroma/onnx_models/all-MiniLM-L6-v2/.

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 or Codex:

• 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:

✨ 2 claude-smart learnings applied [cs:s1-252,p1-5aed]

That signals a preference (p…) or skill (s…) 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.