Skip to content
Back to search

claude-smart

Turns corrections into Preferences, Project-specific skills, and Shared skills for Claude Code, Codex, and OpenCode.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ReflexioAI/claude-smart with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ReflexioAI/claude-smart'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/reflexioai-claude-smart/badge.svg)](/listings/reflexioai-claude-smart)

HTML

<a href="/listings/reflexioai-claude-smart"><img src="/api/listings/reflexioai-claude-smart/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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 — what the installers and uninstallers touch, OpenCode config resolution and model/env overrides, and Windows notes — see [Host install notes](./DEVELOPER.md#host-install-notes) in DEVELOPER.md. Developing the plugin itself? See [Developing locally](./DEVELOPER.md#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.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 497 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/claude-smart-icon.png" alt="claude-smart" width="140">
  3. </p>
  4. <h1 align="center">
  5. claude-smart
  6. </h1>
  7. <h4 align="center">A self-improvement plugin for <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>, Codex, and OpenCode that turns interactions into durable skills they follow in future sessions.</h4>
  8. <p align="center">
  9. <a href="LICENSE">
  10. <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License">
  11. </a>
  12. <a href="plugin/pyproject.toml">
  13. <img src="https://img.shields.io/badge/version-0.3.17-green.svg" alt="Version">
  14. </a>
  15. <a href="plugin/pyproject.toml">
  16. <img src="https://img.shields.io/badge/python-%3E%3D3.12-brightgreen.svg" alt="Python">
  17. </a>
  18. <a href="package.json">
  19. <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node">
  20. </a>
  21. <a href="#quick-start">
  22. <img src="https://img.shields.io/badge/hosts-Claude%20Code%20%2B%20Codex%20%2B%20OpenCode-purple.svg" alt="Hosts">
  23. </a>
  24. <a href="https://discord.gg/7fnCxahase">
  25. <img src="https://img.shields.io/badge/Discord-Join%20community-5865F2?logo=discord&logoColor=white" alt="Discord">
  26. </a>
  27. <a href="https://github.com/ReflexioAI/reflexio">
  28. <img src="https://img.shields.io/github/stars/ReflexioAI/reflexio?style=flat&logo=github&label=Star%20reflexio&color=yellow&cacheSeconds=3600" alt="Star reflexio on GitHub">
  29. </a>
  30. </p>
  31. <p align="center">
  32. <a href="#quick-start">Quick Start</a> •
  33. <a href="#how-it-works">How It Works</a> •
  34. <a href="#commands">Commands</a> •
  35. <a href="#dashboard">Dashboard</a> •
  36. <a href="#configuration">Configuration</a> •
  37. <a href="TROUBLESHOOTING.md">Troubleshooting</a> •
  38. <a href="#license">License</a>
  39. </p>
  40. <p align="center">
  41. claude-smart learns from your corrections <i>and</i> from what's already working — so the assistant stops repeating mistakes and reuses proven paths. Project-specific skills capture repo-local rules, and shared skills roll up durable patterns for reuse across projects.
  42. </p>
  43. <p align="center">
  44. <b>vs <code>claude-mem</code>:</b> ~3× better at turning your corrections into rules Claude follows, ~50% more of your guidance is retained. <a href="EXPERIMENT.md"><b>Read the benchmark →</b></a>
  45. </p>
  46. <p align="center">
  47. ⭐ Built on the open-source <a href="https://github.com/ReflexioAI/reflexio"><b>reflexio</b></a> engine — if claude-smart helps you, <a href="https://github.com/ReflexioAI/reflexio"><b>star reflexio on GitHub</b></a>.
  48. </p>
  49. ---
  50. ## Quick Start
  51. Requires Node.js 20+ (for `npx`) and the host CLI you're installing into (`claude`, `codex`, or `opencode`) on `PATH`.
  52. ### Guided installation
  53. ```bash
  54. npx claude-smart install
  55. ```
  56. Choose one or more detected coding agents with the arrow keys and Space, then
  57. press Enter. Single-choice settings use the arrow keys and Enter. Esc or Ctrl+C
  58. cancels before configuration is saved.
  59. The guide asks where to store and process your data:
  60. - **Local Reflexio:** starts a background backend on this machine. Choose which
  61. available agent CLI powers background learning; it can analyze interactions
  62. from every installed integration.
  63. - **Managed Reflexio:** enter an HTTPS endpoint and a hidden API key. No local
  64. backend starts; memory storage and background learning run in Reflexio cloud.
  65. The local dashboard connects to that cloud backend by default.
  66. In local mode, Claude Code learning defaults to the `sonnet` alias, which Claude
  67. Code resolves independently of the coding model. Codex and OpenCode keep their
  68. provider-configured defaults. An explicit supported model ID overrides these
  69. choices. For unattended installs, use
  70. `--model <model-id>` with `--provider`. The chosen model is applied to extraction
  71. and optimizer calls. Managed mode reports the server-configured model when
  72. available, otherwise explicitly reports that its default model is not exposed.
  73. After install, update, or setup, the summary includes the Claude-smart version,
  74. learning provider, provider CLI version when available, and model selection.
  75. Configured aliases/defaults are distinguished from a reported model version;
  76. unknown versions are shown as “not reported.” Run `npx claude-smart setup` to
  77. change the learning settings.
  78. When local learning is already configured, **Keep current learning configuration**
  79. is selected by default. It preserves cloud generation, custom executables and the
  80. current native model; selecting a native provider entry explicitly changes that
  81. setup and opens its model choices. Supported caller overrides still apply, and
  82. `--provider` explicitly replaces a cloud/custom configuration with that native
  83. provider. Installing a different coding integration does not select its model.
  84. The dashboard's **Data source** dropdown selects Local or Managed Reflexio.
  85. It defaults to the saved runtime mode. Its endpoint, overview totals, preferences,
  86. skills, and backend sessions follow the selected source; viewing another source
  87. does not change learning/storage settings. The header shows the selected endpoint
  88. as a read-only connection label, with an **Open cloud dashboard** link in Managed
  89. mode. Change connection settings in **Configure**. Overview metrics use backend summary
  90. counts for the last 30 days, rather than list limits. Connection failures are
  91. shown explicitly. Older skill citations without a project/shared identity remain
  92. visible under Legacy skill usage; exact per-skill counts use identified citations.
  93. A backend must be configured and reachable to view its data.
  94. The dashboard follows the managed Reflexio workspace style: neutral light/dark
  95. surfaces, green accents, flat metric bands, and consistent page spacing. The
  96. theme switch applies across dashboard, sessions, preferences, skills, and settings.
  97. Previously configured connections are retained privately when changing modes.
  98. The dashboard currently trusts local OS users: other accounts on a shared machine
  99. can access its configured backend connections. Per-user dashboard authentication
  100. requires a separate change.
  101. **This device** lists local session buffers and hook activity separately. Those
  102. counts can differ between machines connected to the same managed account.
  103. Review the configuration before installation starts. Saved settings and installed
  104. agents are preselected on subsequent runs. Preparation and service startup show
  105. phase and elapsed progress; detailed logs live in `~/.claude-smart/install-logs/`.
  106. If an integration fails, the others still install and the summary reports each result.
  107. Runtime environments remain separate so an agent's rollback cannot break another.
  108. ### Explicit installation
  109. For an unattended first install, specify the backend. Multiple agents can be
  110. installed in one command:
  111. ```bash
  112. npx claude-smart install --host claude-code,codex --backend local --provider codex
  113. npx claude-smart install --host opencode --backend local --provider opencode --global
  114. ```
  115. For managed mode, supply the API key through a named environment variable rather
  116. than a command-line argument:
  117. ```bash
  118. npx claude-smart install --host claude-code,codex --backend managed \
  119. --url https://www.reflexio.ai/ --api-key-env REFLEXIO_API_KEY
  120. ```
  121. Existing `--host codex` and `--host opencode` commands still work. Without a terminal,
  122. saved backend/provider settings are reused; a fresh install requires `--backend`.
  123. Use `--yes` to skip interactive questions when all required settings are supplied
  124. or saved. For multiple local agents, specify `--provider` unless one is already saved.
  125. Use `--read-only` to retrieve memories without publishing interactions, or `--learn`
  126. to resume learning. The interactive guide offers both modes for either backend.
  127. Setup reads legacy duplicate settings with the same field rules as the runtime:
  128. shared connection/learning fields use the last assignment (including empty), while
  129. caller-overridable execution flags use the first nonempty saved assignment.
  130. Legacy connection fallback treats the endpoint and API key as a pair. If the
  131. current settings contain either assignment, even empty, setup does not borrow
  132. the other from `~/.reflexio/.env`. An incomplete managed connection needs its own
  133. key. Legacy read-only and other runtime preferences still migrate independently.
  134. Setup, Codex hooks, the dashboard, and the shell/Python readers all accept plain
  135. assignments and `export` followed by spaces or tabs.
  136. Explicit caller and setup choices retain their existing precedence. Reading or
  137. cancelling setup does not rewrite the file or prepare a settings publisher.
  138. Legacy migration preserves the selected original value text, including Windows
  139. path quoting; only the assignment prefix is normalized.
  140. Confirmation uses the same native lock and private atomic settings owner as the
  141. dashboard and dependency repair. One captured preview drives the save; concurrent
  142. edits require a fresh preview. Setup prepares a small temporary Python writer from
  143. locked dependencies before changing settings. A preparation failure leaves settings
  144. unchanged. Confirmed settings remain available if a later integration install fails.
  145. Publisher child processes, including UV installation, have a two-minute deadline.
  146. On timeout, setup stops their owned process trees.
  147. If publication cannot be confirmed, setup stops before installing integrations;
  148. reload settings before retrying.
  149. Migration completion is recorded as a fixed first-line comment in that same atomic
  150. settings write, after an optional UTF-8 BOM. Matching text inside a value is not
  151. migration metadata. Existing
  152. migration sidecars are still recognized without rewriting them. Later setup runs
  153. do not reimport deleted legacy preferences after migration has completed.
  154. The confirmed guide owns connection, learning, sharing, and read-only choices.
  155. Host workers consume those saved choices; installing or removing another agent
  156. does not rewrite a shared learning host. Each prepared runtime uses the same
  157. Python repair owner to supply only missing local defaults, with native locking
  158. and private atomic publication. Existing values, including zero and explicit
  159. empty values, are preserved. Ordinary standalone self-repair remains supported.
  160. Dashboard saves use the prepared Python settings owner too. They share the
  161. repair lock and publish privately with one atomic file replacement. An explicit
  162. empty value stays present; omitted settings stay unchanged. If relevant settings
  163. change while a save is being prepared, reload and retry rather than overwriting
  164. the newer choices. A busy repair also leaves the file unchanged. Saving requires
  165. the dashboard's prepared sibling `.venv`; run `npx claude-smart update` if that
  166. runtime needs repair. Existing unrelated assignments and comments are retained.
  167. Literal values use quotes only when needed to preserve the same value across
  168. the readers; backslashes are never rewritten as escapes. Expansion, line/control
  169. separators and quote combinations without a shared literal form are refused
  170. before publication.
  171. Legacy saved HOST fallback is preserved as explicit learning intent at confirmation,
  172. also when switching to managed storage with a native optimizer. Existing HOST
  173. text remains available to the pinned SDK; this does not retire its compatibility
  174. input or grant a new optimizer capability. A private worker without confirmed
  175. connection settings refuses with the public setup command. Confirmation saves a
  176. validated local endpoint in its normalized loopback spelling, so accepted numeric
  177. or uppercase hostnames retain local mode. Reading an existing file does not
  178. normalize it. Uninstall still completes with broken settings and skips speculative
  179. shared-service refresh.
  180. ### Activate each integration
  181. Run `/reload-plugins` in your existing Claude Code session, or use the update in your next session.
  182. Start a new Codex session to load the update; you can finish your existing session first. If hook trust needs review, use `/hooks`.
  183. Then restart OpenCode in your project so it loads the plugin. The installer writes a loader into the selected scope's `plugins` directory — the project's `.opencode/plugins/` for a project install — and both OpenCode lines load the plugin from there: OpenCode 1.x auto-loads the plugins directory, and OpenCode V2 rejects the old `file://` config-entry shape. Any legacy `opencode.json` entry is removed so the package loads exactly once. `--global` installs for all OpenCode projects on this machine instead, writing the loader under your user config directory.
  184. Install and update use the same tracked service lifecycle for every coding agent.
  185. Validation of the platform, settings, and OpenCode loader/config happens before
  186. services stop. If preparation fails before commit, the previous packages and
  187. install metadata are restored before restarting only services that were running.
  188. If an installed service reports that stopping failed, installation aborts before
  189. replacing its runtime. Resolve the shutdown failure and retry; only services
  190. whose stop succeeded are eligible for automatic restart.
  191. A failed first install leaves no candidate runtime selected. Incomplete recovery
  192. keeps backups and warns rather than starting an unverified runtime.
  193. Codex stages its marketplace under `CODEX_HOME/claude-smart/marketplace` (default
  194. `~/.codex/claude-smart/marketplace`), separate from Claude's legacy marketplace.
  195. Installing or removing Codex leaves that legacy runtime intact.
  196. Codex commits its prepared runtime and hook cache before asking Codex to trust the
  197. hooks. A later trust failure keeps that new runtime; follow the reported `/hooks`
  198. recovery instructions. Registration, account configuration, and trust changes are
  199. not an all-or-nothing transaction.
  200. ### Check an update
  201. ```bash
  202. npx claude-smart status
  203. npx claude-smart status --host codex
  204. ```
  205. Shows the installed version and the version each recent session last used in a hook. Historical observations do not confirm that a session is still active. Codex uses `CODEX_HOME` when set; run installation and status with the same account home as your session. `status --host codex` also warns when a claude-smart hook is disabled in Codex's `config.toml` and says how to re-enable it; it never edits that file.
  206. ### Uninstall
  207. ```bash
  208. npx claude-smart uninstall # Choose integrations interactively
  209. npx claude-smart uninstall --host claude-code,codex # Remove multiple integrations
  210. npx claude-smart uninstall --host claude-code # Claude Code
  211. npx claude-smart uninstall --host codex # Codex
  212. npx claude-smart uninstall --host opencode # OpenCode
  213. ```
  214. Afterward, use `/reload-plugins` in Claude Code, start a new Codex session, or restart OpenCode. 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.
  215. Uninstall keeps saved configuration and the chosen background learning provider.
  216. Removing an integration does not uninstall its agent CLI. Remaining integrations
  217. can continue using the same learning provider. OpenCode removal applies to the
  218. current project config, or its global config with `--global`.
  219. If removing an integration breaks the shared command link, it is repaired from
  220. the remaining runtimes, including registered Claude Code caches and local source
  221. installs. A declared local source takes precedence over its older cache path;
  222. discovery does not modify or delete that source.
  223. For per-host details — what the installers and uninstallers touch, OpenCode config resolution and model/env overrides, and Windows notes — see [Host install notes](./DEVELOPER.md#host-install-notes) in DEVELOPER.md. Developing the plugin itself? See [Developing locally](./DEVELOPER.md#developing-locally).
  224. > **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.
  225. ---
  226. ## Why Learning, Not Memory
  227. Most memory tools just record. Claude remembers what happened, but doesn't change what it does next.
  228. `claude-smart` focuses on learning instead.
  229. Four things this changes:
  230. - 💡 **Stop repeating the same mistakes:** Produces actionable skills Claude can follow next time; memory only records what happened.
  231. > *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.<br>
  232. > **Memory:** “deploy broke after prisma bump; user rolled back”<br>
  233. > **Learning:** “treat major-version bumps of ORMs/DB drivers as breaking — verify with integration tests, not just unit tests”
  234. - 🚀 **Start from the optimized path:** Records and optimizes the steps that worked so Claude can reuse them, instead of re-exploring each session.
  235. > *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`.<br>
  236. > **Memory:** “user mentioned that `npm run dev` did not work”<br>
  237. > **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”
  238. Instead of re-exploring, Claude Code starts from the proven path—reducing planning steps, latency, and token usage.
  239. - 🌐 **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.
  240. - 🪶 **Better context without prompt bloat:** Distilled, deduplicated skills stay in dozens of tokens—not thousands—even as the project grows.
  241. ---
  242. ## Demo
  243. https://github.com/user-attachments/assets/ed84d73a-d5b7-4a0d-ab2c-f2c060c3f276
  244. ---
  245. ## Key Features
  246. - 🧠 **Learn, don't just remember** — Corrections become structured, deduplicated rules, not transcript replays.
  247. - ⚡ **Fully automatic learning** — Every user turn, tool call, and assistant response is captured via lifecycle hooks and extracted into rules without you running anything.
  248. - 📈 **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.
  249. > *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.
  250. - 🔌 **Local or managed storage** — in local mode, semantic search runs on an in-process ONNX embedder (all-MiniLM-L6-v2) and memories stay on this machine. Managed mode stores and processes memories on the configured cloud backend; device interaction buffers remain local.
  251. - 🔎 **Hybrid search** — Skills and preferences are indexed with vector + BM25 search for fast, robust retrieval.
  252. - 🧪 **Offline resilience** — If the reflexio backend is down, hooks buffer to disk; the next successful publish drains them.
  253. - 🧰 **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.
  254. ---
  255. ## Dashboard
  256. A web UI for browsing session histories, inspecting preferences, and editing project-specific and shared skills. The local backend binds to `127.0.0.1:8071` by default. The dashboard auto-starts in both local and managed mode at **http://localhost:3001**. Its data-source selector defaults to your saved runtime mode; managed mode reads cloud totals without starting a local backend. 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`.
  257. <p align="center">
  258. <img src="assets/preferences_dashboard.png" alt="Preferences dashboard" width="49%">
  259. <img src="assets/skills_dashboard.png" alt="Skills dashboard" width="49%">
  260. </p>
  261. ---
  262. ## How It Works
  263. claude-smart builds three artifacts as you work and injects the relevant ones into Claude Code, Codex, or OpenCode:
  264. - **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."
  265. - **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."
  266. - **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."
  267. Skills clean themselves up: correct the same thing twice and they merge; change your mind and the old one is archived.
  268. 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](https://github.com/ReflexioAI/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, as a short index: one line per hit saying when it applies. The agent loads the full text of any hit that applies with `bash ~/.reflexio/plugin-root/scripts/cli.sh load --session <session-id> <id> [<id> ...]` (the injected header gives the exact command). Run `/claude-smart:show` or the equivalent CLI command to audit the current learned state. Everything runs on your machine.
  269. **Citations.** At the end of a reply, the assistant may append a short marker:
  270. ```
  271. ✨ 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)
  272. ```
  273. That signals a preference or skill materially shaped the reply.
  274. Open the session's detail page in the [dashboard](http://localhost:3001) to see the exact cited item.
  275. See [ARCHITECTURE.md](./ARCHITECTURE.md) for hooks, data flow, and reflexio details.
  276. ---
  277. ## Commands
  278. Claude Code installs these as plugin slash commands. Codex does not currently
  279. support plugin-provided slash commands, so claude-smart ships a Codex skill that
  280. maps requests like "claude-smart show" or "run claude-smart learn" to the
  281. equivalent action.
  282. | Claude Code | Codex request | What it does |
  283. | --- | --- | --- |
  284. | `/claude-smart:dashboard` | `open claude-smart dashboard` | Open the dashboard in your browser, auto-starting the reflexio backend and dashboard services if they aren't already running. |
  285. | `/claude-smart:show` | `claude-smart show` | Print current project-specific skills, shared skills, and the current project's preferences so you can audit learned state manually. |
  286. | `/claude-smart:learn [note]` | `claude-smart learn with note "optional note"` | Flag the most recent turn as a correction (for cases the automatic heuristic missed) and force reflexio to run extraction *now* on the session's unpublished interactions. The optional note becomes the correction description the extractor sees. |
  287. | `/claude-smart:restart` | `restart claude-smart` | Restart the reflexio backend and dashboard to pick up new changes (e.g. after upgrading the plugin or editing local reflexio code). |
  288. | `/claude-smart:clear-all` | `clear all claude-smart learnings` | **Destructive.** Delete *all* reflexio interactions, preferences, and skills. Use when you want to wipe learned state and start fresh. |
  289. ---
  290. ## Configuration
  291. Advanced users can tune claude-smart via environment variables — see [DEVELOPER.md](./DEVELOPER.md#environment-variables) for the full list.
  292. ### Where data lives
  293. | Path | What |
  294. | --- | --- |
  295. | `~/.reflexio/data/reflexio.db` | Source of truth for learned preferences, skills, interactions, full-text indexes, and embedding tables (plus `.db-shm` / `.db-wal` WAL sidecars). Inspect with `sqlite3`. |
  296. | `~/.claude-smart/.env` | claude-smart config read by the hooks, backend, installer, and `npx claude-smart setup` — connection and learning policy (`REFLEXIO_URL` / `REFLEXIO_API_KEY`, `CLAUDE_SMART_LEARNING_PROVIDER` / `CLAUDE_SMART_LEARNING_MODEL`), plus execution overrides. Existing `CLAUDE_SMART_HOST` rows remain legacy fallback; installers no longer default or rewrite them. |
  297. | `~/.claude-smart/claude-code/claude-smart/` | Claude Code's stable local copy of the active npm package, registered as the `reflexioai` marketplace. Claude Code runs the plugin in place from its `plugin/` dir. |
  298. | `.claude/settings.local.json` or `~/.claude/settings.json` | Claude Code hook environment, such as `CLAUDE_SMART_CITATIONS`; use project-local settings for one repo or user settings for all projects. |
  299. | `~/.codex/config.toml` | Codex plugin state, hook feature flags, and per-hook trust entries after `claude-smart install --host codex`. |
  300. | `~/.codex/plugins/cache/reflexioai/claude-smart/<version>/` | Codex's cached install of the `claude-smart` plugin from the `ReflexioAI` marketplace. |
  301. | `~/.codex/claude-smart/runtime/plugin/` | Codex's prepared Python environment and dashboard. Hooks in the cache execute this runtime; generated dependencies stay outside the validated plugin package. Both Codex paths use `CODEX_HOME` when set. |
  302. | `opencode.json` / `opencode.jsonc`, or existing `.opencode/opencode.json*` | OpenCode local plugin config patched by `claude-smart install --host opencode`; the installer updates only the claude-smart entry in OpenCode's plugin list. |
  303. | `~/.claude-smart/opencode/claude-smart/` | OpenCode's stable local copy of the active npm package. OpenCode config points here with `file://` so restarts do not re-resolve `claude-smart` from npm. |
  304. | `~/.reflexio/plugin-root` | Self-healed symlink to the active plugin dir (managed by `ensure-plugin-root.sh` — written on install, refreshed each `SessionStart`). Claude Code slash commands and Codex shell-command helpers resolve through it, so don't delete it; if you do, the next session will recreate it. |
  305. | `~/.claude-smart/sessions/{session_id}.jsonl` | Private per-session buffer: turns, tools, frozen requests and publication watermarks. Unacknowledged data remains here; deleting the buffer can lose pending interactions. |
  306. | `~/.claude-smart/publish-outbox/` | Private Codex publication intents and shared worker locks. Contains destination fingerprints and completed-turn bounds; interaction content stays in session buffers. |
  307. | `~/.claude-smart/node/current/` | Private Node.js/npm runtime used by hooks and the dashboard after install. |
  308. | `~/.cache/chroma/onnx_models/all-MiniLM-L6-v2/` | Cached ONNX weights (~86 MB, downloaded once). Delete to force a re-download. |
  309. Backends that require publication admission select their database in the same
  310. atomic operation as a saved-configuration upgrade. If legacy work must drain,
  311. refusal preserves the original configuration so the old writer can still open
  312. it. Complete that work with the matching old backend before retrying; startup
  313. does not discard history, switch to an empty database, or acknowledge charges.
  314. Upgrading from `CLAUDE_SMART_USE_LOCAL_EMBEDDING` requires removing the retired
  315. assignment after preserving the effective model, endpoint and timeout policy.
  316. See the [embedding upgrade guide](https://github.com/ReflexioAI/claude-smart/blob/main/DEVELOPER.md#upgrade-from-the-old-embedding-flag), including the case where an old local default shadowed a written `off`.
  317. For troubleshooting, see [TROUBLESHOOTING.md](./TROUBLESHOOTING.md).
  318. ---
  319. ## Powered by Reflexio
  320. claude-smart is powered by [**Reflexio**](https://github.com/ReflexioAI/reflexio) ([reflexio.ai](https://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](https://github.com/ReflexioAI/reflexio)**.
  321. ---
  322. ## License
  323. 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.
  324. See the [LICENSE](LICENSE) file for details.
  325. ---
  326. ## Support
  327. - **Discord**: join the community at [discord.gg/7fnCxahase](https://discord.gg/7fnCxahase).
  328. - **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`.
  329. ---
  330. **Powered by** [Reflexio](https://github.com/ReflexioAI/reflexio) · **Runs on** [Claude Code](https://claude.com/claude-code), Codex, and OpenCode · **Written in** Python 3.12+
  331. Search hooks reserve a durable request identity in the session buffer before
  332. retrieval. The corresponding response is published with that same identity;
  333. retries keep it, and searches after a frozen publish belong to a later response.
  334. Older buffered publishes keep their existing retry IDs. Cancelled turns do not
  335. attach their retrieved-playbook references to a later prompt's answer. Search
  336. alone does not supply a conversation or an outcome for offline tuning: the
  337. response still needs to be published. Buffer writes and identity reservations
  338. share a cross-process file lock on Linux, macOS, and native Windows.
  339. ### Short sessions and completion
  340. Automatic session completion keeps Reflexio's usefulness judge enabled. Claude
  341. Code's SessionEnd publishes an unsaved tail, then sends a completion hint even if
  342. Stop already saved every message. Acceptance does not mean extraction has finished.
  343. Explicit `/learn` remains a manual force operation.
  344. With the updated Reflexio backend, publish-only integrations (including Codex,
  345. OpenCode, and direct clients) evaluate short sessions after six hours without a new
  346. publication in the same session. The operator can configure
  347. `extraction_idle_timeout_seconds` (`21600` by default, `0` disables for new
  348. publications). This fallback is a low-urgency policy, not proof a session ended.
  349. Normal full-window and stride extraction still runs promptly. A negative judge
  350. result produces no learning and is recorded as examined.
  351. Optimizer policy is also owned by the Reflexio server. SessionStart no longer
  352. turns optimization on or rewrites its budgets, adoption permissions or assistant
  353. backend. Existing server settings are preserved; fresh servers keep their own
  354. (disabled) optimizer default until explicitly configured. The old
  355. `CLAUDE_SMART_ENABLE_OPTIMIZER` hook flag is no longer read. Removing or setting
  356. that flag does not disable an optimizer already enabled on the server; change
  357. `playbook_optimizer_config` on the server to do that.
  358. The separately installed `claude-smart-optimizer-assistant` helper remains
  359. available for explicitly configured local optimization. See the
  360. [backend binding notes](./DEVELOPER.md#optimizer-backend-binding) before assigning
  361. an executable path, especially when the server is remote.
  362. Extraction cadence is owned by the Reflexio server: configure `window_size` and
  363. `stride_size` there. Starting a client session preserves those settings. The
  364. former hook overrides `CLAUDE_SMART_WINDOW_SIZE` and `CLAUDE_SMART_STRIDE_SIZE`
  365. are no longer read; remove them from launchers and set the server configuration
  366. explicitly when a benchmark needs a different cadence. Existing persisted values
  367. are preserved; fresh servers use their own defaults.
  368. Managed mode requires a server update; changing the plugin alone cannot update a
  369. cloud server. An older server retains saved messages and logs that completion is
  370. unsupported; the plugin does not republish or force extraction. Idle fallback
  371. starts with new publications after backend upgrade; old saved sessions can be
  372. explicitly finalized on the updated backend.
  373. ### Publish-time playbook evidence
  374. User-playbook search receipts travel with the injected learning references in the
  375. on-disk buffer and are sent unchanged on publish. Distinct receipts for one
  376. playbook are retained, so a later revision cannot overwrite an earlier injection.
  377. Reflexio stores exposure evidence with the interaction rather than writing it on
  378. search. ID-only references remain supported but have unverified served versions.
  379. Update the SDK/server together to receive this metadata; older search response
  380. models may omit receipts. The server stores only a receipt digest in the
  381. interaction, and client recovery uses it to compare the original submission.
  382. Normal installs require `reflexio-ai>=0.2.32`; `plugin/uv.lock` resolves the
  383. published SDK from PyPI. Keep the SDK/server upgrade coordinated: older SDK
  384. response models can omit receipts, and older servers retain their existing
  385. exposure behavior. ID-only publication remains compatible.
plugin/scripts/smart-install.sh · Bundled script · 734 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. # Prepare the plugin Python runtime, repair only missing local defaults,
  3. # then verify and start the selected services. Connection selection belongs
  4. # to the npm installer; dependency repair never retargets saved endpoints.
  5. #
  6. # On failure, writes the reason to ~/.claude-smart/install-failed so
  7. # hook_entry.sh can short-circuit and surface a user-visible message
  8. # instead of silently no-op'ing every session.
  9. set -eu
  10. HERE="$(cd "$(dirname "$0")" && pwd)"
  11. # shellcheck source=_lib.sh
  12. . "$HERE/_lib.sh"
  13. claude_smart_source_login_path
  14. claude_smart_prepend_astral_bins
  15. claude_smart_prepend_node_bins
  16. PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
  17. claude_smart_reexec_stable_plugin_root_if_needed "$PLUGIN_ROOT" "smart-install.sh" "$@"
  18. REPO_ROOT="$(cd "$HERE/../.." && pwd)"
  19. MARKER_DIR="$HOME/.claude-smart"
  20. FAILURE_MARKER="$MARKER_DIR/install-failed"
  21. SUCCESS_MARKER="$MARKER_DIR/install-complete"
  22. INSTALL_LOCK="$MARKER_DIR/install.lock"
  23. INSTALL_REAP_LOCK="$MARKER_DIR/install.lock.reap"
  24. mkdir -p "$MARKER_DIR"
  25. remove_stale_install_lock() {
  26. local expected current
  27. expected="$1"
  28. if ! mkdir "$INSTALL_REAP_LOCK" 2>/dev/null; then
  29. sleep 1
  30. return 0
  31. fi
  32. current="$(cat "$INSTALL_LOCK" 2>/dev/null || true)"
  33. if [ "$current" = "$expected" ]; then
  34. rm -f "$INSTALL_LOCK"
  35. fi
  36. rmdir "$INSTALL_REAP_LOCK" 2>/dev/null || true
  37. }
  38. acquire_install_lock() {
  39. local lock_pid
  40. if command -v flock >/dev/null 2>&1; then
  41. exec 9>"$INSTALL_LOCK"
  42. if ! flock 9; then
  43. echo "[claude-smart] install lock failed; continuing without serialization" >&2
  44. claude_smart_emit_continue
  45. exit 0
  46. fi
  47. return 0
  48. fi
  49. while ! ( set -C; printf '%s\n' "$$" > "$INSTALL_LOCK" ) 2>/dev/null; do
  50. lock_pid="$(cat "$INSTALL_LOCK" 2>/dev/null || true)"
  51. case "$lock_pid" in
  52. ''|*[!0-9]*)
  53. remove_stale_install_lock "$lock_pid"
  54. ;;
  55. *)
  56. if kill -0 "$lock_pid" 2>/dev/null; then
  57. sleep 1
  58. else
  59. remove_stale_install_lock "$lock_pid"
  60. fi
  61. ;;
  62. esac
  63. done
  64. trap '[ "$(cat "$INSTALL_LOCK" 2>/dev/null || true)" = "$$" ] && rm -f "$INSTALL_LOCK" || true' EXIT
  65. }
  66. # Serialize concurrent installer runs (SessionStart hook + slash-command
  67. # self-heal can both invoke this script). Wait for the active installer
  68. # rather than returning early, otherwise callers can re-check uv before
  69. # the first install has finished and report a false missing-dependency error.
  70. acquire_install_lock
  71. rm -f "$FAILURE_MARKER"
  72. write_failure() {
  73. local reason fp_hash
  74. reason="$1"
  75. fp_hash="$(claude_smart_install_fingerprint_hash "$PLUGIN_ROOT" "$HERE" 2>/dev/null || true)"
  76. # bin/claude-smart.js reads this marker too: first line is the user-facing
  77. # failure reason, and fingerprint=... marks which install attempt produced it.
  78. {
  79. printf '%s\n' "$reason"
  80. if [ -n "$fp_hash" ]; then
  81. printf 'fingerprint=%s\n' "$fp_hash"
  82. fi
  83. } > "$FAILURE_MARKER"
  84. rm -f "$SUCCESS_MARKER"
  85. echo "[claude-smart] install failed: $reason" >&2
  86. claude_smart_emit_continue
  87. exit 0
  88. }
  89. verify_windows_local_embedding_runtime() {
  90. claude_smart_is_windows || return 0
  91. local ownership
  92. if claude_smart_reflexio_url_is_remote || claude_smart_reflexio_url_is_custom_local; then
  93. return 0
  94. fi
  95. claude_smart_prepare_backend_import_context "$PLUGIN_ROOT"
  96. if ! ownership="$(cd "$PLUGIN_ROOT" && PYTHONPATH="$backend_pythonpath" \
  97. REFLEXIO_ENV_FILE="$HOME/.claude-smart/.env" \
  98. "$backend_python" "$HERE/backend-inference-owner.py")"; then
  99. write_failure "Unable to determine inference ownership; resolve the SDK startup error before retrying."
  100. fi
  101. ownership="${ownership%$'\r'}"
  102. case "$ownership" in
  103. attached) return 0 ;;
  104. colocated) ;;
  105. *) write_failure "Invalid inference ownership result; repair the selected runtime before retrying." ;;
  106. esac
  107. if claude_smart_python_imports "$PLUGIN_ROOT" onnxruntime; then
  108. return 0
  109. fi
  110. write_failure "Windows local embedding requires Microsoft Visual C++ Redistributable for onnxruntime; install the x64 redistributable from https://aka.ms/vs/17/release/vc_redist.x64.exe and rerun claude-smart install."
    • Dismissed after review: Links to a Windows program from code, which is how droppers fetch their payload
    • Line 122 on GitHub
  111. }
  112. if [ "${1:-}" = "verify-windows-embedding" ]; then
  113. # Node bootstrap runs this after uv sync so install-failed markers stay
  114. # consistent with the shell installer path.
  115. claude_smart_source_reflexio_env
  116. verify_windows_local_embedding_runtime
  117. exit 0
  118. fi
  119. install_fingerprint() {
  120. claude_smart_install_fingerprint "$PLUGIN_ROOT" "$HERE"
  121. }
  122. install_complete() {
  123. [ -f "$SUCCESS_MARKER" ] || return 1
  124. [ "$(cat "$SUCCESS_MARKER" 2>/dev/null || true)" = "$(install_fingerprint)" ] || return 1
  125. command -v uv >/dev/null 2>&1 || return 1
  126. [ -d "$PLUGIN_ROOT/.venv" ] || return 1
  127. claude_smart_python_imports "$PLUGIN_ROOT" claude_smart.hook || return 1
  128. if ! claude_smart_reflexio_url_is_remote; then
  129. [ -f "$HOME/.claude-smart/.env" ] || return 1
  130. grep -qE '^[[:space:]]*(export[[:space:]]+)?CLAUDE_SMART_USE_LOCAL_CLI[[:space:]]*=' "$HOME/.claude-smart/.env" || return 1
  131. grep -qE '^[[:space:]]*(export[[:space:]]+)?CLAUDE_SMART_READ_ONLY[[:space:]]*=' "$HOME/.claude-smart/.env" || return 1
  132. grep -qE '^[[:space:]]*(export[[:space:]]+)?REFLEXIO_ROW_LIMIT_INTERACTIONS[[:space:]]*=' "$HOME/.claude-smart/.env" || return 1
  133. fi
  134. if [ -d "$PLUGIN_ROOT/dashboard" ]; then
  135. [ -d "$PLUGIN_ROOT/dashboard/.next" ] || [ -f "$MARKER_DIR/dashboard-build.pid" ] || [ -f "$(claude_smart_dashboard_unavailable_marker)" ] || return 1
  136. fi
  137. return 0
  138. }
  139. # The npx installer sets CLAUDE_SMART_DEFER_SERVICES=1 while it prepares a
  140. # copy it may still roll back; it starts the backend and the dashboard build
  141. # itself once the install has committed.
  142. start_backend_service() {
  143. [ "${CLAUDE_SMART_DEFER_SERVICES:-}" = "1" ] && return 0
  144. if [ -x "$HERE/backend-service.sh" ]; then
  145. # backend-service.sh decides whether a bundled backend runs at all
  146. # (managed mode, a custom local server, and autostart=0 skip it).
  147. echo "[claude-smart] requested a backend start (see backend-service.sh status)" >&2
  148. bash "$HERE/backend-service.sh" start >/dev/null 2>&1 || true
  149. fi
  150. }
  151. install_vendored_reflexio() {
  152. local VENDORED_REFLEXIO PLUGIN_PYTHON
  153. VENDORED_REFLEXIO="$PLUGIN_ROOT/vendor/reflexio"
  154. if [ ! -f "$VENDORED_REFLEXIO/pyproject.toml" ]; then
  155. # A host plugin cache (~/.claude/plugins/cache/..., ~/.codex/plugins/cache/...)
  156. # is only ever populated from the npm package, which always carries the
  157. # vendored runtime. Missing it there means the plugin was installed straight
  158. # from the GitHub marketplace, where the bundle is gitignored — the backend
  159. # could never start. Fail here, at Setup, rather than at first session.
  160. case "$PLUGIN_ROOT" in
  161. */plugins/cache/*)
  162. write_failure "bundled Reflexio runtime is missing from $VENDORED_REFLEXIO. This happens when claude-smart is installed from the GitHub marketplace, which does not carry the generated runtime. Install with: npx claude-smart install"
  163. ;;
  164. esac
  165. # A source checkout legitimately has no vendor bundle (it is generated at
  166. # pack time); reflexio comes from the plugin venv instead.
  167. return 0
  168. fi
  169. if claude_smart_is_windows; then
  170. PLUGIN_PYTHON="$PLUGIN_ROOT/.venv/Scripts/python.exe"
  171. else
  172. PLUGIN_PYTHON="$PLUGIN_ROOT/.venv/bin/python"
  173. fi
  174. if [ ! -x "$PLUGIN_PYTHON" ]; then
  175. write_failure "plugin Python was not created by uv sync: $PLUGIN_PYTHON"
  176. fi
  177. echo "[claude-smart] installing bundled Reflexio source from $VENDORED_REFLEXIO" >&2
  178. if ! uv pip install --project "$PLUGIN_ROOT" --python "$PLUGIN_PYTHON" --quiet --reinstall --no-deps "$VENDORED_REFLEXIO" >&2; then
  179. echo "[claude-smart] warning: quiet vendored Reflexio install failed in $PLUGIN_ROOT; retrying with full output." >&2
  180. if ! uv pip install --project "$PLUGIN_ROOT" --python "$PLUGIN_PYTHON" --reinstall --no-deps "$VENDORED_REFLEXIO" >&2; then
  181. write_failure "vendored Reflexio install failed in $PLUGIN_ROOT"
  182. fi
  183. fi
  184. verify_vendored_reflexio_requirements "$PLUGIN_PYTHON"
  185. }
  186. # --no-deps skips the bundled Reflexio's own requirements, so a requirement
  187. # plugin/uv.lock does not install would otherwise surface only as an import
  188. # error in the backend. Fail the install instead, naming the missing package.
  189. verify_vendored_reflexio_requirements() {
  190. local python_bin report problems
  191. python_bin="$1"
  192. if report="$(uv pip check --python "$python_bin" 2>&1)"; then
  193. return 0
  194. fi
  195. printf '%s\n' "$report" >&2
  196. problems="$(printf '%s\n' "$report" | grep -E '^The package' | tr '\n' ';' | sed 's/;$//' || true)"
  197. write_failure "bundled Reflexio dependency check failed in $PLUGIN_ROOT/.venv: ${problems:-uv pip check failed} — this claude-smart package is missing a dependency of its bundled Reflexio; update with 'npx claude-smart update' or report it at https://github.com/ReflexioAI/claude-smart/issues"
  198. }
  199. write_success_marker() {
  200. install_fingerprint > "$SUCCESS_MARKER"
  201. }
  202. preflight_supported_runtime_platform() {
  203. local os_name machine darwin_major
  204. os_name="$(uname -s 2>/dev/null || echo unknown)"
  205. machine="$(uname -m 2>/dev/null || echo unknown)"
  206. case "$os_name" in
  207. Darwin*)
  208. if [ "$machine" != "arm64" ]; then
  209. write_failure "claude-smart currently supports Apple Silicon macOS 14+ only; Intel Mac is not supported because native ML wheels are unavailable."
  210. fi
  211. darwin_major="$(uname -r 2>/dev/null | awk -F. '{print $1}')"
  212. case "$darwin_major" in
  213. ''|*[!0-9]*)
  214. write_failure "claude-smart could not determine the macOS version; Apple Silicon macOS 14+ is required."
  215. ;;
  216. esac
  217. if [ "$darwin_major" -lt 23 ]; then
  218. write_failure "claude-smart currently supports macOS 14+ on Apple Silicon; macOS 13 and older are not supported because native ML wheels are unavailable."
  219. fi
  220. ;;
  221. MINGW*|MSYS*|CYGWIN*)
  222. case "$machine" in
  223. x86_64|amd64) : ;;
  224. *)
  225. write_failure "claude-smart currently supports Windows x64 only; Windows ARM is not supported because native ML wheels are unavailable."
  226. ;;
  227. esac
  228. ;;
  229. Linux*)
  230. : # Existing Linux installs remain supported when package wheels are available.
  231. ;;
  232. *)
  233. write_failure "claude-smart currently supports Apple Silicon macOS 14+, Windows x64, and Linux for vanilla installs."
  234. ;;
  235. esac
  236. }
  237. install_private_node() {
  238. local NODE_MIN_MAJOR NODE_MIN_MINOR NODE_LTS_MAJOR
  239. local node_os archive_ext reason node_arch node_platform base_url node_root
  240. local tmp_dir shasums_path archive_name ext_re install_dir archive_path
  241. local expected_hash actual_hash archive_win dest_win candidate_path next_link old_current
  242. NODE_MIN_MAJOR=20
  243. NODE_MIN_MINOR=9
  244. NODE_LTS_MAJOR="${CLAUDE_SMART_NODE_LTS_MAJOR:-26}"
  245. if claude_smart_node_satisfies "$NODE_MIN_MAJOR" "$NODE_MIN_MINOR" \
  246. && claude_smart_npm_available; then
  247. claude_smart_clear_dashboard_unavailable
  248. return 0
  249. fi
  250. case "$(uname -s 2>/dev/null)" in
  251. Darwin*) node_os="darwin"; archive_ext="tar.gz" ;;
  252. Linux*) node_os="linux"; archive_ext="tar.gz" ;;
  253. MINGW*|MSYS*|CYGWIN*)
  254. node_os="win"
  255. archive_ext="zip"
  256. if ! command -v powershell >/dev/null 2>&1; then
  257. reason="PowerShell is not on PATH, so claude-smart could not extract private Node.js on Windows."
  258. echo "[claude-smart] WARNING: $reason" >&2
  259. claude_smart_write_dashboard_unavailable "$reason"
  260. return 1
  261. fi
  262. ;;
  263. *)
  264. reason="unsupported OS for private Node.js install: $(uname -s 2>/dev/null || echo unknown)"
  265. echo "[claude-smart] WARNING: $reason" >&2
  266. claude_smart_write_dashboard_unavailable "$reason"
  267. return 1
  268. ;;
  269. esac
  270. case "$(uname -m 2>/dev/null)" in
  271. x86_64|amd64) node_arch="x64" ;;
  272. arm64|aarch64) node_arch="arm64" ;;
  273. *)
  274. reason="unsupported CPU for private Node.js install: $(uname -m 2>/dev/null || echo unknown)"
  275. echo "[claude-smart] WARNING: $reason" >&2
  276. claude_smart_write_dashboard_unavailable "$reason"
  277. return 1
  278. ;;
  279. esac
  280. node_platform="$node_os-$node_arch"
  281. base_url="${CLAUDE_SMART_NODE_BASE_URL:-https://nodejs.org/dist/latest-v${NODE_LTS_MAJOR}.x}"
  282. echo "[claude-smart] Node.js >=20.9 with npm not found — installing private Node.js from nodejs.org..." >&2
  283. node_root="$HOME/.claude-smart/node"
  284. mkdir -p "$node_root"
  285. tmp_dir=$(mktemp -d "$node_root/tmp.XXXXXX") || {
  286. reason="could not create temporary directory under $node_root"
  287. echo "[claude-smart] WARNING: $reason" >&2
  288. claude_smart_write_dashboard_unavailable "$reason"
  289. return 1
  290. }
  291. shasums_path="$tmp_dir/SHASUMS256.txt"
  292. if ! claude_smart_download "$base_url/SHASUMS256.txt" "$shasums_path"; then
  293. rm -rf "$tmp_dir"
  294. reason="could not download Node.js checksums from $base_url/SHASUMS256.txt"
  295. echo "[claude-smart] WARNING: $reason" >&2
  296. claude_smart_write_dashboard_unavailable "$reason"
  297. return 1
  298. fi
  299. ext_re=$(printf '%s' "$archive_ext" | sed 's/\./\\./g')
  300. archive_name=$(
  301. awk -v platform="$node_platform" -v ext="$ext_re" \
  302. '$2 ~ ("^node-v[0-9][^ ]*-" platform "\\." ext "$") { print $2; exit }' \
  303. "$shasums_path"
  304. ) || archive_name=""
  305. if [ -z "$archive_name" ]; then
  306. rm -rf "$tmp_dir"
  307. reason="could not resolve Node.js archive for $node_platform from $base_url"
  308. echo "[claude-smart] WARNING: $reason" >&2
  309. claude_smart_write_dashboard_unavailable "$reason"
  310. return 1
  311. fi
  312. install_dir="$node_root/${archive_name%.$archive_ext}"
  313. archive_path="$tmp_dir/$archive_name"
  314. expected_hash=$(awk -v name="$archive_name" '$2 == name { print $1; exit }' "$shasums_path")
  315. if [ -z "$expected_hash" ]; then
  316. rm -rf "$tmp_dir"
  317. reason="Node.js checksums did not include $archive_name"
  318. echo "[claude-smart] WARNING: $reason" >&2
  319. claude_smart_write_dashboard_unavailable "$reason"
  320. return 1
  321. fi
  322. if ! claude_smart_download "$base_url/$archive_name" "$archive_path"; then
  323. rm -rf "$tmp_dir"
  324. reason="Node.js download failed from $base_url/$archive_name"
  325. echo "[claude-smart] WARNING: $reason" >&2
  326. claude_smart_write_dashboard_unavailable "$reason"
  327. return 1
  328. fi
  329. actual_hash=$(claude_smart_sha256_file "$archive_path" || true)
  330. if [ -z "$actual_hash" ] || [ "$actual_hash" != "$expected_hash" ]; then
  331. rm -rf "$tmp_dir"
  332. reason="Node.js checksum verification failed for $archive_name"
  333. echo "[claude-smart] WARNING: $reason" >&2
  334. claude_smart_write_dashboard_unavailable "$reason"
  335. return 1
  336. fi
  337. rm -rf "$install_dir" "$node_root/current.next"
  338. if [ "$archive_ext" = "zip" ]; then
  339. archive_win="$archive_path"
  340. dest_win="$node_root"
  341. if command -v cygpath >/dev/null 2>&1; then
  342. archive_win=$(cygpath -w "$archive_path")
  343. dest_win=$(cygpath -w "$node_root")
  344. fi
  345. if ! ARCHIVE_PATH="$archive_win" DEST_DIR="$dest_win" powershell -NoProfile -ExecutionPolicy Bypass -Command \
  346. '$ProgressPreference="SilentlyContinue"; Expand-Archive -LiteralPath $env:ARCHIVE_PATH -DestinationPath $env:DEST_DIR -Force' >&2; then
  347. rm -rf "$tmp_dir" "$install_dir"
  348. reason="Node.js archive extraction failed for $archive_name"
  349. echo "[claude-smart] WARNING: $reason" >&2
  350. claude_smart_write_dashboard_unavailable "$reason"
  351. return 1
  352. fi
  353. elif ! tar -xzf "$archive_path" -C "$node_root"; then
  354. rm -rf "$tmp_dir" "$install_dir"
  355. reason="Node.js archive extraction failed for $archive_name"
  356. echo "[claude-smart] WARNING: $reason" >&2
  357. claude_smart_write_dashboard_unavailable "$reason"
  358. return 1
  359. fi
  360. if [ ! -d "$install_dir" ]; then
  361. rm -rf "$tmp_dir"
  362. reason="Node.js archive extracted without expected directory $install_dir"
  363. echo "[claude-smart] WARNING: $reason" >&2
  364. claude_smart_write_dashboard_unavailable "$reason"
  365. return 1
  366. fi
  367. if [ -x "$install_dir/bin/node" ]; then
  368. candidate_path="$install_dir/bin:$PATH"
  369. elif [ -x "$install_dir/node.exe" ] || [ -x "$install_dir/node" ]; then
  370. candidate_path="$install_dir:$PATH"
  371. else
  372. rm -rf "$tmp_dir"
  373. reason="Node.js archive extracted without a node executable"
  374. echo "[claude-smart] WARNING: $reason" >&2
  375. claude_smart_write_dashboard_unavailable "$reason"
  376. return 1
  377. fi
  378. if claude_smart_node_satisfies "$NODE_MIN_MAJOR" "$NODE_MIN_MINOR" \
  379. && claude_smart_npm_available; then
  380. : # existing PATH unexpectedly became suitable; keep going
  381. elif PATH="$candidate_path" claude_smart_node_satisfies "$NODE_MIN_MAJOR" "$NODE_MIN_MINOR" \
  382. && PATH="$candidate_path" claude_smart_npm_available; then
  383. : # candidate install is suitable
  384. else
  385. rm -rf "$tmp_dir"
  386. reason="private Node.js install completed but node/npm are still not usable"
  387. echo "[claude-smart] WARNING: $reason" >&2
  388. claude_smart_write_dashboard_unavailable "$reason"
  389. return 1
  390. fi
  391. if claude_smart_is_windows; then
  392. # Windows cannot rely on the POSIX symlink swap path; keep current recoverable.
  393. old_current="$node_root/current.old.$$"
  394. rm -rf "$old_current" 2>/dev/null || true
  395. if [ -e "$node_root/current" ] || [ -L "$node_root/current" ]; then
  396. if ! mv "$node_root/current" "$old_current"; then
  397. rm -rf "$tmp_dir" "$install_dir"
  398. reason="could not stage existing private Node.js install for replacement"
  399. echo "[claude-smart] WARNING: $reason" >&2
  400. claude_smart_write_dashboard_unavailable "$reason"
  401. return 1
  402. fi
  403. fi
  404. if mv "$install_dir" "$node_root/current"; then
  405. rm -rf "$old_current" 2>/dev/null || true
  406. else
  407. reason="could not activate private Node.js install at $node_root/current"
  408. if [ -e "$node_root/current" ] || [ -L "$node_root/current" ]; then
  409. if ! rm -rf "$node_root/current"; then
  410. reason="could not remove failed private Node.js install at $node_root/current; previous install remains at $old_current for manual recovery"
  411. rm -rf "$tmp_dir" "$install_dir"
  412. echo "[claude-smart] WARNING: $reason" >&2
  413. claude_smart_write_dashboard_unavailable "$reason"
  414. return 1
  415. fi
  416. fi
  417. if [ -e "$old_current" ] || [ -L "$old_current" ]; then
  418. if ! mv "$old_current" "$node_root/current"; then
  419. reason="could not restore previous private Node.js install from $old_current after activation failure; previous install remains at $old_current for manual recovery"
  420. fi
  421. fi
  422. rm -rf "$tmp_dir" "$install_dir"
  423. echo "[claude-smart] WARNING: $reason" >&2
  424. claude_smart_write_dashboard_unavailable "$reason"
  425. return 1
  426. fi
  427. else
  428. next_link="$node_root/current.next.$$"
  429. if ln -s "$install_dir" "$next_link" 2>/dev/null; then
  430. if mv -Tf "$next_link" "$node_root/current" 2>/dev/null; then
  431. :
  432. elif mv -hf "$next_link" "$node_root/current" 2>/dev/null; then
  433. :
  434. else
  435. rm -rf "$node_root/current"
  436. mv "$next_link" "$node_root/current"
  437. fi
  438. else
  439. rm -rf "$next_link" "$node_root/current"
  440. mv "$install_dir" "$node_root/current"
  441. fi
  442. fi
  443. rm -rf "$tmp_dir"
  444. claude_smart_prepend_node_bins
  445. if claude_smart_node_satisfies "$NODE_MIN_MAJOR" "$NODE_MIN_MINOR" \
  446. && claude_smart_npm_available; then
  447. claude_smart_clear_dashboard_unavailable
  448. echo "[claude-smart] installed private $(node -v) at $node_root/current" >&2
  449. return 0
  450. fi
  451. reason="private Node.js install completed but current node/npm are still not usable"
  452. echo "[claude-smart] WARNING: $reason" >&2
  453. claude_smart_write_dashboard_unavailable "$reason"
  454. return 1
  455. }
  456. if [ "${CLAUDE_SMART_INSTALL_PRIVATE_NODE_ONLY:-}" = "1" ]; then
  457. claude_smart_source_reflexio_env
  458. install_private_node
  459. exit $?
  460. fi
  461. preflight_supported_runtime_platform
  462. if (claude_smart_source_reflexio_env; install_complete); then
  463. claude_smart_source_reflexio_env
  464. verify_windows_local_embedding_runtime
  465. start_backend_service
  466. claude_smart_emit_continue
  467. exit 0
  468. fi
  469. if ! command -v uv >/dev/null 2>&1; then
  470. echo "[claude-smart] uv not found — installing from astral.sh..." >&2
  471. # The astral.sh bash installer downloads a zip and unzips it. On
  472. # Windows-flavoured bash (Git Bash / MSYS) the bundled `unzip` corrupts
  473. # the Windows uv binary (bad CRC on the inflated uv.exe), leaving the
  474. # install half-finished. Use the official PowerShell installer
  475. # (install.ps1) on Windows, which writes uv.exe to ~/.local/bin
  476. # natively — same destination the bash installer targets on POSIX, so
  477. # claude_smart_prepend_astral_bins picks it up uniformly afterwards.
  478. if claude_smart_is_windows; then
  479. if ! command -v powershell >/dev/null 2>&1; then
  480. write_failure "uv install needs PowerShell on Windows but powershell is not on PATH — install uv manually from https://docs.astral.sh/uv/"
  481. fi
  482. if ! powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://astral.sh/uv/install.ps1 | iex" >&2; then
  483. write_failure "uv install via PowerShell failed — install manually from https://docs.astral.sh/uv/"
  484. fi
  485. else
  486. UV_INSTALLER="$MARKER_DIR/uv-install.sh"
  487. if ! claude_smart_download https://astral.sh/uv/install.sh "$UV_INSTALLER"; then
  488. write_failure "uv installer download failed — install manually from https://docs.astral.sh/uv/"
  489. fi
  490. if ! sh "$UV_INSTALLER" >&2; then
  491. write_failure "uv install failed — install manually from https://docs.astral.sh/uv/"
  492. fi
  493. fi
  494. claude_smart_prepend_astral_bins
  495. if ! command -v uv >/dev/null 2>&1; then
  496. UV_FOUND=""
  497. for candidate in "$HOME/.local/bin/uv" "$HOME/.local/bin/uv.exe" "$HOME/.cargo/bin/uv" "$HOME/bin/uv"; do
  498. if [ -x "$candidate" ]; then
  499. UV_FOUND="$candidate"
  500. break
  501. fi
  502. done
  503. if [ -n "$UV_FOUND" ]; then
  504. write_failure "uv installed at $UV_FOUND — add its parent directory to PATH in your shell rc"
  505. else
  506. write_failure "uv install reported success but binary not found — install manually from https://docs.astral.sh/uv/"
  507. fi
  508. fi
  509. fi
  510. cd "$PLUGIN_ROOT"
  511. # Claude Code copies the plugin directory into ~/.claude/plugins/cache on every
  512. # install/update, yet runs it in place, so an in-place .venv (~1 GB) became an
  513. # unused duplicate per version. For the managed Claude Code copy, keep the env
  514. # outside the plugin directory and link it from .venv: Claude Code skips the
  515. # symlink when copying, and every "$PLUGIN_ROOT/.venv/bin/python" path still
  516. # resolves. One directory per install, so the package an update keeps aside for
  517. # rollback still owns its own env. Successful updates keep older envs for
  518. # sessions using cached hooks; explicit uninstall removes them.
  519. # Windows keeps the in-place .venv (symlinks need Developer Mode there).
  520. CLAUDE_SMART_VENVS_DIR="$HOME/.claude-smart/venvs"
  521. plugin_root_is_managed_claude_code_copy() {
  522. local managed
  523. claude_smart_is_windows && return 1
  524. managed="$(claude_smart_canonical_dir "$HOME/.claude-smart/claude-code/claude-smart/plugin" 2>/dev/null)" || return 1
  525. [ "$(pwd -P)" = "$managed" ]
  526. }
  527. plugin_venv_target() {
  528. [ -L "$PLUGIN_ROOT/.venv" ] || return 1
  529. readlink "$PLUGIN_ROOT/.venv"
  530. }
  531. if plugin_root_is_managed_claude_code_copy; then
  532. if [ -L "$PLUGIN_ROOT/.venv" ] && [ ! -d "$PLUGIN_ROOT/.venv" ]; then
  533. rm -f "$PLUGIN_ROOT/.venv"
  534. fi
  535. if [ ! -e "$PLUGIN_ROOT/.venv" ]; then
  536. mkdir -p "$CLAUDE_SMART_VENVS_DIR"
  537. venv_dir="$CLAUDE_SMART_VENVS_DIR/claude-code-$(date +%s)-$$"
  538. mkdir "$venv_dir"
  539. ln -s "$venv_dir" "$PLUGIN_ROOT/.venv"
  540. venv_freshly_linked=1
  541. fi
  542. fi
  543. # Self-heal a corrupt .venv before uv sync. uv refuses to reuse a venv that
  544. # exists but has no python executable (e.g. partial cleanup of an npm/npx
  545. # tree, an interrupted earlier install, or the underlying interpreter being
  546. # uninstalled) — it errors with "not a valid Python environment" instead of
  547. # rebuilding. Pre-clearing lets uv recreate it cleanly.
  548. if [ -d "$PLUGIN_ROOT/.venv" ] && [ -z "${venv_freshly_linked:-}" ]; then
  549. if claude_smart_is_windows; then
  550. plugin_python_path="$PLUGIN_ROOT/.venv/Scripts/python.exe"
  551. else
  552. plugin_python_path="$PLUGIN_ROOT/.venv/bin/python"
  553. fi
  554. if [ ! -x "$plugin_python_path" ]; then
  555. echo "[claude-smart] .venv at $PLUGIN_ROOT/.venv has no python executable; recreating" >&2
  556. if venv_target="$(plugin_venv_target)"; then
  557. # Clear the linked env in place; removing only the link would leak it.
  558. find "$venv_target" -mindepth 1 -maxdepth 1 -exec rm -rf {} +
  559. else
  560. rm -rf "$PLUGIN_ROOT/.venv"
  561. fi
  562. fi
  563. fi
  564. echo "[claude-smart] running uv sync..." >&2
  565. if ! uv sync --locked --python 3.12 --quiet >&2; then
  566. if uv lock --check --python 3.12 >/dev/null 2>&1; then
  567. write_failure "uv sync failed in $PLUGIN_ROOT — run 'uv sync --locked --python 3.12' there to diagnose"
  568. fi
  569. echo "[claude-smart] plugin/uv.lock is out of sync; refreshing local lockfile and retrying uv sync" >&2
  570. if ! uv lock --python 3.12 >&2 || ! uv sync --python 3.12 --quiet >&2; then
  571. write_failure "uv sync failed in $PLUGIN_ROOT after refreshing plugin/uv.lock — run 'uv lock --python 3.12 && uv sync --python 3.12' there to diagnose"
  572. fi
  573. fi
  574. # Defend against a stale lockfile silently dropping the project install.
  575. # When plugin/uv.lock pins a different claude-smart version than pyproject.toml,
  576. # `uv sync --locked` exits 0 but does NOT install the claude_smart package, so
  577. # every hook fails later with `ModuleNotFoundError: No module named 'claude_smart'`.
  578. # Catch that here with a clear, user-visible install-failed marker.
  579. if ! claude_smart_python_imports "$PLUGIN_ROOT" claude_smart.hook; then
  580. write_failure "uv sync left claude_smart uninstalled in $PLUGIN_ROOT/.venv — plugin/uv.lock is likely out of sync with pyproject.toml (regenerate with 'uv lock --project plugin' and reinstall the plugin)"
  581. fi
  582. install_vendored_reflexio
  583. if ! claude_smart_python_imports "$PLUGIN_ROOT" claude_smart.hook; then
  584. write_failure "claude-smart package is not importable after vendored Reflexio install in $PLUGIN_ROOT/.venv"
  585. fi
  586. # Dependency preparation does not choose or rewrite the user's connection.
  587. # The prepared runtime supplies missing defaults under its native settings lock.
  588. # Discard metadata stdout so the hook emits only its own continuation payload.
  589. PLUGIN_PYTHON="$(claude_smart_plugin_python "$PLUGIN_ROOT")"
  590. if "$PLUGIN_PYTHON" -I -m claude_smart.env_config bootstrap-repair >/dev/null; then
  591. :
  592. else
  593. repair_status=$?
  594. if [ "$repair_status" -eq 75 ]; then
  595. echo "[claude-smart] settings are busy; retry setup after the active save" >&2
  596. claude_smart_emit_continue
  597. exit "$repair_status"
  598. fi
  599. write_failure "Unable to repair startup settings; check the settings error above before retrying."
  600. fi
  601. claude_smart_source_reflexio_env
  602. verify_windows_local_embedding_runtime
  603. case "${CLAUDE_SMART_HOST:-claude-code}" in
  604. opencode)
  605. if [ -z "${CLAUDE_SMART_OPENCODE_PATH:-}" ] && ! command -v opencode >/dev/null 2>&1; then
  606. echo "[claude-smart] WARNING: 'opencode' CLI not on PATH and CLAUDE_SMART_OPENCODE_PATH is not set — reflexio extractors will have no LLM until OpenCode is installed" >&2
  607. fi
  608. ;;
  609. codex)
  610. if ! command -v codex >/dev/null 2>&1; then
  611. echo "[claude-smart] WARNING: 'codex' CLI not on PATH — reflexio extractors will have no LLM until Codex is installed" >&2
  612. fi
  613. ;;
  614. *)
  615. if ! command -v claude >/dev/null 2>&1; then
  616. echo "[claude-smart] WARNING: 'claude' CLI not on PATH — reflexio extractors will have no LLM until Claude Code is installed" >&2
  617. fi
  618. ;;
  619. esac
  620. LEGACY_CS_CITE="$HOME/.claude-smart/bin/cs-cite"
  621. if [ -e "$LEGACY_CS_CITE" ]; then
  622. rm -f "$LEGACY_CS_CITE"
  623. echo "[claude-smart] removed legacy cs-cite helper at $LEGACY_CS_CITE" >&2
  624. fi
  625. CLAUDE_SETTINGS="$HOME/.claude/settings.json"
  626. if [ -f "$CLAUDE_SETTINGS" ] && command -v node >/dev/null 2>&1; then
  627. node - "$CLAUDE_SETTINGS" <<'JS' >&2 || true
  628. const fs = require("fs");
  629. const path = process.argv[2];
  630. const entry = "Bash(cs-cite:*)";
  631. let data;
  632. try {
  633. data = JSON.parse(fs.readFileSync(path, "utf8") || "{}");
  634. } catch {
  635. process.exit(0);
  636. }
  637. const allow = data?.permissions?.allow;
  638. if (!Array.isArray(allow)) process.exit(0);
  639. const next = allow.filter((item) => item !== entry);
  640. if (next.length === allow.length) process.exit(0);
  641. data.permissions.allow = next;
  642. fs.writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`);
  643. console.error(`[claude-smart] removed legacy ${entry} permission from ${path}`);
  644. JS
  645. fi
  646. # Spawn the dashboard build detached so install returns immediately and
  647. # Claude Code's install-hook timeout never kills a half-finished
  648. # `next build` (which would force the user into a manual /claude-smart:restart
  649. # recovery). dashboard-service.sh will also re-spawn this on SessionStart
  650. # if .next is still missing, and dashboard-open.sh detects the build-pid
  651. # file to surface a "still building" message instead of a generic error.
  652. DASHBOARD_DIR="$PLUGIN_ROOT/dashboard"
  653. if [ -d "$DASHBOARD_DIR" ]; then
  654. install_private_node || true
  655. fi
  656. if [ "${CLAUDE_SMART_DEFER_SERVICES:-}" = "1" ]; then
  657. :
  658. elif [ -d "$DASHBOARD_DIR" ] && claude_smart_npm_available; then
  659. echo "[claude-smart] starting dashboard build in background (~1-2 min on first install)" >&2
  660. claude_smart_spawn_detached bash "$HERE/dashboard-build.sh" >/dev/null 2>&1
  661. elif [ -d "$DASHBOARD_DIR" ]; then
  662. reason="npm is not on PATH after private Node.js bootstrap"
  663. echo "[claude-smart] WARNING: $reason" >&2
  664. [ -f "$(claude_smart_dashboard_unavailable_marker)" ] || claude_smart_write_dashboard_unavailable "$reason"
  665. fi
  666. # Point ~/.reflexio/plugin-root at this install so slash commands can
  667. # reference one stable short path regardless of which install loaded us.
  668. if ! bash "$HERE/ensure-plugin-root.sh" "$PLUGIN_ROOT"; then
  669. echo "[claude-smart] WARNING: failed to set ~/.reflexio/plugin-root symlink — slash commands may not resolve" >&2
  670. fi
  671. start_backend_service
  672. write_success_marker
  673. if [ "${CLAUDE_SMART_DEFER_SERVICES:-}" = "1" ]; then
  674. echo "[claude-smart] install complete; the installer starts and reports services once the plugin is registered." >&2
  675. else
  676. echo "[claude-smart] install complete. Services start on session start when this setup uses them; see backend-service.sh status." >&2
  677. fi
  678. claude_smart_emit_continue

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.