claude-smart 0.2.37 → 0.2.40

package/README.md

@@ -13,7 +13,7 @@
     <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License">
   </a>
   <a href="plugin/pyproject.toml">
-    <img src="https://img.shields.io/badge/version-0.2.37-green.svg" alt="Version">
+    <img src="https://img.shields.io/badge/version-0.2.40-green.svg" alt="Version">
   </a>
   <a href="plugin/pyproject.toml">
     <img src="https://img.shields.io/badge/python-%3E%3D3.12-brightgreen.svg" alt="Python">
@@ -46,33 +46,6 @@
 
 ---
 
-## 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.<br>
-  > **Memory:** “deploy broke after prisma bump; user rolled back”<br>
-  > **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`.<br>
-  > **Memory:** “user mentioned that `npm run dev` did not work”<br>
-  > **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.
-
----
-
 ## Quick Start
 
 ### Claude Code
@@ -126,18 +99,38 @@ Developing the plugin itself? See [DEVELOPER.md](./DEVELOPER.md#developing-local
 
 > **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
+---
+
+## Why Learning, Not Memory
 
-| 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. |
+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.<br>
+  > **Memory:** “deploy broke after prisma bump; user rolled back”<br>
+  > **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`.<br>
+  > **Memory:** “user mentioned that `npm run dev` did not work”<br>
+  > **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
 
-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/`.
+https://github.com/user-attachments/assets/ed84d73a-d5b7-4a0d-ab2c-f2c060c3f276
 
 ---
 
@@ -231,7 +224,7 @@ For troubleshooting, see [TROUBLESHOOTING.md](./TROUBLESHOOTING.md).
 
 ## License
 
-This project is licensed under the **Apache License 2.0**. The bundled `reflexio/` submodule is also Apache 2.0. Claude Code is Anthropic's and not covered by this 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](LICENSE) file for details.
 

package/bin/claude-smart.js

@@ -16,6 +16,7 @@
 const { execSync, spawn, spawnSync } = require("child_process");
 const crypto = require("crypto");
 const {
+  chmodSync,
   cpSync,
   existsSync,
   lstatSync,
@@ -41,6 +42,8 @@ const REFLEXIO_ENV_PATH = join(homedir(), ".reflexio", ".env");
 const MANAGED_REFLEXIO_URL = "https://www.reflexio.ai/";
 const MANAGED_SETUP_ENV = "CLAUDE_SMART_MANAGED_SETUP";
 const CLAUDE_SMART_READ_ONLY_ENV = "CLAUDE_SMART_READ_ONLY";
+const CLAUDE_SMART_USE_LOCAL_CLI_ENV = "CLAUDE_SMART_USE_LOCAL_CLI";
+const CLAUDE_SMART_USE_LOCAL_EMBEDDING_ENV = "CLAUDE_SMART_USE_LOCAL_EMBEDDING";
 const REFLEXIO_USER_ID_ENV = "REFLEXIO_USER_ID";
 const REFLEXIO_DIR = join(homedir(), ".reflexio");
 const CLAUDE_SMART_STATE_DIR = join(homedir(), ".claude-smart");
@@ -90,6 +93,24 @@ const COPYTREE_IGNORE_NAMES = new Set([
   "node_modules",
   ".next",
 ]);
+const LOCAL_DEFAULT_ENV_ENTRIES = [
+  [
+    "# Route reflexio generation through the local Claude Code CLI",
+    CLAUDE_SMART_USE_LOCAL_CLI_ENV,
+    "1",
+  ],
+  [
+    "# Use the in-process ONNX embedder (chromadb) - no API key for semantic search",
+    CLAUDE_SMART_USE_LOCAL_EMBEDDING_ENV,
+    "1",
+  ],
+  [null, CLAUDE_SMART_READ_ONLY_ENV, "0"],
+];
+const LOCAL_MODE_PRUNE_KEYS = new Set([
+  "REFLEXIO_URL",
+  "REFLEXIO_API_KEY",
+  REFLEXIO_USER_ID_ENV,
+]);
 
 function shouldCopyPath(src) {
   const base = src.split(/[\\/]/).pop() || "";
@@ -216,6 +237,57 @@ function parseEnvLine(line) {
   return { key, value };
 }
 
+function escapeEnvValue(value) {
+  return String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+function ensureLocalReflexioEnv() {
+  mkdirSync(dirname(REFLEXIO_ENV_PATH), { recursive: true });
+  const existing = existsSync(REFLEXIO_ENV_PATH)
+    ? readFileSync(REFLEXIO_ENV_PATH, "utf8")
+    : "";
+  const present = new Set();
+  const keptLines = [];
+  let pruned = false;
+  for (const line of existing.split(/\r?\n/)) {
+    const parsed = parseEnvLine(line);
+    if (parsed) {
+      if (LOCAL_MODE_PRUNE_KEYS.has(parsed.key)) {
+        pruned = true;
+        continue;
+      }
+      present.add(parsed.key);
+    }
+    keptLines.push(line);
+  }
+
+  const additions = [];
+  const added = [];
+  for (const [comment, key, value] of LOCAL_DEFAULT_ENV_ENTRIES) {
+    if (present.has(key)) continue;
+    if (comment) additions.push(comment);
+    if (key === CLAUDE_SMART_READ_ONLY_ENV) {
+      additions.push(`${key}="${escapeEnvValue(value)}"`);
+    } else {
+      additions.push(`${key}=${escapeEnvValue(value)}`);
+    }
+    added.push(key);
+  }
+
+  if (additions.length > 0 || pruned) {
+    let content = keptLines.join("\n").replace(/\n*$/, "");
+    if (additions.length > 0) {
+      const prefix = content ? "\n" : "";
+      content = content + prefix + additions.join("\n");
+    }
+    writeFileSync(REFLEXIO_ENV_PATH, content ? `${content}\n` : "");
+  } else if (!existsSync(REFLEXIO_ENV_PATH)) {
+    writeFileSync(REFLEXIO_ENV_PATH, "");
+  }
+  chmodSync(REFLEXIO_ENV_PATH, 0o600);
+  return added;
+}
+
 function maskSecret(value) {
   if (!value) return "";
   if (value.length <= 8) return "*".repeat(value.length);
@@ -254,7 +326,12 @@ function loadReflexioSetupEnv() {
   } else {
     delete process.env.REFLEXIO_URL;
     delete process.env.REFLEXIO_API_KEY;
+    delete process.env[REFLEXIO_USER_ID_ENV];
     delete process.env[MANAGED_SETUP_ENV];
+    const added = ensureLocalReflexioEnv();
+    if (added.length > 0) {
+      process.stdout.write(`Seeded ${REFLEXIO_ENV_PATH} with ${added.join(", ")}.\n`);
+    }
   }
   const readOnly = ["1", "true", "yes", "on"].includes(
     String(readOnlyValue).trim().toLowerCase(),
@@ -795,6 +872,36 @@ function ensurePluginRoot(pluginRoot) {
   }
 }
 
+async function installVendoredReflexio(pluginRoot, uv, env) {
+  const vendorRoot = join(pluginRoot, "vendor", "reflexio");
+  if (!existsSync(join(vendorRoot, "pyproject.toml"))) return;
+
+  const pythonPath = isWindows()
+    ? join(pluginRoot, ".venv", "Scripts", "python.exe")
+    : join(pluginRoot, ".venv", "bin", "python");
+  if (!existsSync(pythonPath)) {
+    throw new Error(`plugin Python was not created by uv sync: ${pythonPath}`);
+  }
+
+  process.stdout.write(`Installing bundled Reflexio source from ${vendorRoot}...\n`);
+  let code = await runChecked(
+    uv,
+    ["pip", "install", "--project", pluginRoot, "--python", pythonPath, "--quiet", "-e", vendorRoot],
+    { cwd: pluginRoot, env },
+  );
+  if (code !== 0) {
+    process.stderr.write(
+      `warning: quiet vendored Reflexio install failed in ${pluginRoot}; retrying with full output.\n`,
+    );
+    code = await runChecked(
+      uv,
+      ["pip", "install", "--project", pluginRoot, "--python", pythonPath, "-e", vendorRoot],
+      { cwd: pluginRoot, env },
+    );
+  }
+  if (code !== 0) throw new Error(`vendored Reflexio install failed in ${pluginRoot}`);
+}
+
 async function bootstrapPluginRuntime(pluginRoot, options = {}) {
   assertSupportedRuntimePlatform();
   process.stdout.write("Preparing claude-smart runtime for hooks...\n");
@@ -830,6 +937,7 @@ async function bootstrapPluginRuntime(pluginRoot, options = {}) {
     );
   }
   if (code !== 0) throw new Error(`uv sync failed in ${pluginRoot}`);
+  await installVendoredReflexio(pluginRoot, uv, env);
 
   const dashboardDir = join(pluginRoot, "dashboard");
   if (existsSync(dashboardDir)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-smart",
-  "version": "0.2.37",
+  "version": "0.2.40",
   "description": "Self-improving Claude Code plugin — learns from corrections via reflexio",
   "keywords": [
     "claude",

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-smart",
-  "version": "0.2.37",
+  "version": "0.2.40",
   "description": "Self-improving Claude Code plugin — learns from corrections across sessions via reflexio",
   "author": {
     "name": "Yi Lu"

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-smart",
-  "version": "0.2.37",
+  "version": "0.2.40",
   "description": "Self-improving coding assistant plugin — learns from corrections across sessions via reflexio",
   "author": {
     "name": "Yi Lu"

package/plugin/pyproject.toml

@@ -1,16 +1,24 @@
 [project]
 name = "claude-smart"
-version = "0.2.37"
+version = "0.2.40"
 description = "Self-improving Claude Code plugin — learns from corrections via reflexio"
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
-    "reflexio-ai>=0.2.22",
-    # Used by reflexio's local embedding provider (ONNXMiniLM_L6_V2).
+    # Core Reflexio client/backend package. This is the PyPI baseline used by
+    # normal installs; vendor releases may override it after uv sync by
+    # installing plugin/vendor/reflexio. Keep in sync via
+    # scripts/sync-reflexio-dep.py.
+    "reflexio-ai>=0.2.23",
+    # Needed when Reflexio runs the local embedding provider (ONNXMiniLM_L6_V2).
     # Pulls in onnxruntime + tokenizers; the ~80 MB ONNX model itself is
     # downloaded on first use, not at install time.
     "chromadb>=0.5",
     "einops>=0.8.0",
+    # Native SQLite vector KNN for local storage. Reflexio can fall back to
+    # Python ranking without this, but installed claude-smart should include
+    # the accelerator by default.
+    "sqlite-vec>=0.1.6",
 ]
 
 [project.scripts]
@@ -18,14 +26,6 @@ claude-smart-hook = "claude_smart.hook:main"
 claude-smart = "claude_smart.cli:main"
 claude-smart-optimizer-assistant = "claude_smart.optimizer_assistant:main"
 
-# NOTE: LOCAL DEV ONLY — do not commit this block to main.
-# Published installs must resolve reflexio-ai from PyPI. This override
-# points at the vendored submodule so editable changes flow through.
-# `git update-index --skip-worktree plugin/pyproject.toml plugin/uv.lock`
-# hides the local divergence from `git status`.
-# [tool.uv.sources]
-# reflexio-ai = { path = "/Users/yilu/repos/claude-smart/reflexio", editable = true }
-
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

package/plugin/scripts/_lib.sh

@@ -196,6 +196,30 @@ claude_smart_resolve_python() {
   return 1
 }
 
+claude_smart_plugin_python() {
+  local plugin_root
+  plugin_root="$1"
+  if claude_smart_is_windows; then
+    printf '%s\n' "$plugin_root/.venv/Scripts/python.exe"
+  else
+    printf '%s\n' "$plugin_root/.venv/bin/python"
+  fi
+}
+
+claude_smart_python_imports() {
+  local plugin_root module python_bin
+  plugin_root="$1"
+  module="$2"
+  python_bin="$(claude_smart_plugin_python "$plugin_root")"
+  [ -x "$python_bin" ] || return 1
+  "$python_bin" - "$module" <<'PY' >/dev/null 2>&1
+import importlib
+import sys
+
+importlib.import_module(sys.argv[1])
+PY
+}
+
 claude_smart_download() {
   local url dest src _CS_PY
   url="$1"
@@ -298,6 +322,8 @@ claude_smart_install_fingerprint() {
   printf 'lib=%s\n' "$(claude_smart_fingerprint_file "$script_dir/_lib.sh")"
   printf 'pyproject=%s\n' "$(claude_smart_fingerprint_file "$plugin_root/pyproject.toml")"
   printf 'uv_lock=%s\n' "$(claude_smart_fingerprint_file "$plugin_root/uv.lock")"
+  printf 'vendor_reflexio_pyproject=%s\n' \
+    "$(claude_smart_fingerprint_file "$plugin_root/vendor/reflexio/pyproject.toml")"
   # Resolved python interpreter — catches a system upgrade (3.12.4 → 3.12.5)
   # that would otherwise let install_complete return true against a venv
   # built against a now-deleted interpreter.

package/plugin/scripts/backend-service.sh

@@ -220,6 +220,21 @@ case "$CMD" in
     export INTERACTION_CLEANUP_THRESHOLD="${INTERACTION_CLEANUP_THRESHOLD:-500}"
     export INTERACTION_CLEANUP_DELETE_COUNT="${INTERACTION_CLEANUP_DELETE_COUNT:-200}"
 
+    # Keep plugin runtime data in ~/.reflexio even when the backend imports
+    # Reflexio from an editable checkout inside a larger repo with its own
+    # .env. python-dotenv respects pre-existing env vars, so this prevents a
+    # parent REFLEXIO_LOG_DIR from sending claude-smart to enterprise configs.
+    export REFLEXIO_LOG_DIR="${REFLEXIO_LOG_DIR:-$HOME}"
+
+    # Force sqlite: the plugin venv ships only the open-source reflexio
+    # package, which doesn't register the Supabase/Postgres storage
+    # factories. If the user's ~/.reflexio/.env sets REFLEXIO_STORAGE to
+    # something else (common when sharing the file with reflexio_ext),
+    # the backend boots but crashes every request. load_dotenv() inside
+    # the CLI respects pre-existing env vars, so exporting here wins
+    # without touching the file on disk.
+    export REFLEXIO_STORAGE="sqlite"
+
     # (nohup; no process groups). backend-log-runner.sh owns stdout/stderr
     # capture so process output cannot grow backend.log past its cap.
     #
@@ -233,7 +248,8 @@ case "$CMD" in
     workers="${CLAUDE_SMART_BACKEND_WORKERS:-1}"
     claude_smart_spawn_detached bash "$HERE/backend-log-runner.sh" \
       "$LOG_FILE" "$LOG_MAX_BYTES" -- \
-      uv run --project "$PLUGIN_ROOT" --quiet \
+      env PYTHONIOENCODING="${PYTHONIOENCODING:-utf-8}" \
+      uv run --project "$PLUGIN_ROOT" --no-sync --quiet \
       reflexio services start --only backend --no-reload --workers "$workers"
     svc_pid=$!
     # Record the spawned pid, not a pgid sampled with ps. On POSIX,

package/plugin/scripts/cli.sh

@@ -63,4 +63,4 @@ if ! command -v uv >/dev/null 2>&1; then
   fi
 fi
 
-exec uv run --project "$PLUGIN_ROOT" --quiet python -m claude_smart.cli "$@"
+exec uv run --project "$PLUGIN_ROOT" --no-sync --quiet python -m claude_smart.cli "$@"

package/plugin/scripts/codex-hook.js

@@ -535,7 +535,7 @@ function runHook(root, event) {
         REFLEXIO_URL: readBackendUrl(),
         CLAUDE_SMART_HOST: "codex",
         CLAUDE_SMART_CLI_PATH: process.env.CLAUDE_SMART_CLI_PATH || codexCompatPath(root),
-        CLAUDE_SMART_CITATION_LINK_STYLE: process.env.CLAUDE_SMART_CITATION_LINK_STYLE || "osc8",
+        CLAUDE_SMART_CITATION_LINK_STYLE: process.env.CLAUDE_SMART_CITATION_LINK_STYLE || "markdown",
       },
       input,
       stdio: ["pipe", "pipe", "inherit"],

package/plugin/scripts/hook_entry.sh

@@ -3,7 +3,8 @@
 # CLAUDE_PLUGIN_ROOT points at the plugin dir (dev: <repo>/plugin;
 # installed: ~/.claude/plugins/cache/reflexioai/claude-smart/<version>),
 # which is also the Python project root with pyproject.toml + uv.lock.
-# We invoke via `uv run --project` so the pinned env from uv.lock is used.
+# We invoke via `uv run --project --no-sync` so the prepared env is used without
+# undoing editable Reflexio installs from local development.
 #
 # If the Setup hook recorded an install failure at
 # ~/.claude-smart/install-failed, short-circuit with a user-visible
@@ -20,7 +21,7 @@ case "$EVENT" in
 esac
 export CLAUDE_SMART_HOST="$HOST"
 if [ "$HOST" = "codex" ] && [ -z "${CLAUDE_SMART_CITATION_LINK_STYLE:-}" ]; then
-  export CLAUDE_SMART_CITATION_LINK_STYLE="osc8"
+  export CLAUDE_SMART_CITATION_LINK_STYLE="markdown"
 fi
 
 HERE="$(cd "$(dirname "$0")" && pwd)"
@@ -58,8 +59,9 @@ if [ -f "$FAILURE_MARKER" ]; then
   if [ -z "$stored_fp" ] || [ "$stored_fp" != "$current_fp" ]; then
     rm -f "$FAILURE_MARKER"
   else
-    if [ "$EVENT" = "session-start" ] && command -v python3 >/dev/null 2>&1; then
-      python3 - "$FAILURE_MARKER" <<'PY'
+    failure_py="$(claude_smart_resolve_python 2>/dev/null || true)"
+    if [ "$EVENT" = "session-start" ] && [ -n "$failure_py" ]; then
+      "$failure_py" - "$FAILURE_MARKER" <<'PY'
 import json, pathlib, sys
 first = pathlib.Path(sys.argv[1]).read_text().splitlines()
 msg = (first[0].strip() if first else "") or "unknown error"
@@ -113,5 +115,38 @@ if ! command -v uv >/dev/null 2>&1; then
   fi
 fi
 
+ensure_hook_package_importable() {
+  if claude_smart_python_imports "$PLUGIN_ROOT" claude_smart.hook; then
+    return 0
+  fi
+
+  if [ "${CLAUDE_SMART_BOOTSTRAPPING:-}" = "1" ]; then
+    return 1
+  fi
+  if [ ! -x "$PLUGIN_ROOT/scripts/smart-install.sh" ]; then
+    return 1
+  fi
+
+  mkdir -p "$STATE_DIR"
+  if [ "$EVENT" = "session-start" ]; then
+    CLAUDE_SMART_BOOTSTRAPPING=1 bash "$PLUGIN_ROOT/scripts/smart-install.sh" >&2
+  else
+    {
+      printf '%s\n' "[claude-smart] hook: claude_smart.hook is not importable; retrying install in background"
+      date 2>/dev/null || true
+    } >>"$STATE_DIR/install.log" 2>&1
+    claude_smart_spawn_detached env CLAUDE_SMART_BOOTSTRAPPING=1 \
+      bash "$PLUGIN_ROOT/scripts/smart-install.sh" \
+      >>"$STATE_DIR/install.log" 2>&1 || true
+  fi
+
+  claude_smart_python_imports "$PLUGIN_ROOT" claude_smart.hook
+}
+
+if ! ensure_hook_package_importable; then
+  claude_smart_emit_continue
+  exit 0
+fi
+
 # Stdin is the hook payload JSON — stream it through to the Python CLI.
-exec uv run --project "$PLUGIN_ROOT" --quiet python -m claude_smart.hook "$HOST" "$EVENT"
+exec uv run --project "$PLUGIN_ROOT" --no-sync --quiet python -m claude_smart.hook "$HOST" "$EVENT"

package/plugin/scripts/smart-install.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# Run once on plugin install. Pulls the reflexio submodule, syncs the
-# Python env, and flips on the claude-code LiteLLM provider in reflexio's
-# .env so extraction works with no external API key.
+# Run once on plugin install. Syncs the Python env and flips on the
+# claude-code LiteLLM provider in reflexio's .env so extraction works with no
+# external API key.
 #
 # On failure, writes the reason to ~/.claude-smart/install-failed so
 # hook_entry.sh can short-circuit and surface a user-visible message
@@ -105,12 +105,45 @@ install_complete() {
   [ "$(cat "$SUCCESS_MARKER" 2>/dev/null || true)" = "$(install_fingerprint)" ] || return 1
   command -v uv >/dev/null 2>&1 || return 1
   [ -d "$PLUGIN_ROOT/.venv" ] || return 1
+  claude_smart_python_imports "$PLUGIN_ROOT" claude_smart.hook || return 1
+  if [ -z "${REFLEXIO_API_KEY:-}" ]; then
+    [ -f "$HOME/.reflexio/.env" ] || return 1
+    grep -qE '^(export[[:space:]]+)?CLAUDE_SMART_USE_LOCAL_CLI=' "$HOME/.reflexio/.env" || return 1
+    grep -qE '^(export[[:space:]]+)?CLAUDE_SMART_USE_LOCAL_EMBEDDING=' "$HOME/.reflexio/.env" || return 1
+    grep -qE '^(export[[:space:]]+)?CLAUDE_SMART_READ_ONLY=' "$HOME/.reflexio/.env" || return 1
+  fi
   if [ -d "$PLUGIN_ROOT/dashboard" ]; then
     [ -d "$PLUGIN_ROOT/dashboard/.next" ] || [ -f "$MARKER_DIR/dashboard-build.pid" ] || [ -f "$(claude_smart_dashboard_unavailable_marker)" ] || return 1
   fi
   return 0
 }
 
+install_vendored_reflexio() {
+  local VENDORED_REFLEXIO PLUGIN_PYTHON
+
+  VENDORED_REFLEXIO="$PLUGIN_ROOT/vendor/reflexio"
+  [ -f "$VENDORED_REFLEXIO/pyproject.toml" ] || return 0
+
+  if claude_smart_is_windows; then
+    PLUGIN_PYTHON="$PLUGIN_ROOT/.venv/Scripts/python.exe"
+  else
+    PLUGIN_PYTHON="$PLUGIN_ROOT/.venv/bin/python"
+  fi
+  if [ ! -x "$PLUGIN_PYTHON" ]; then
+    write_failure "plugin Python was not created by uv sync: $PLUGIN_PYTHON"
+  fi
+
+  echo "[claude-smart] installing bundled Reflexio source from $VENDORED_REFLEXIO" >&2
+  if uv pip install --project "$PLUGIN_ROOT" --python "$PLUGIN_PYTHON" --quiet -e "$VENDORED_REFLEXIO" >&2; then
+    return 0
+  fi
+
+  echo "[claude-smart] warning: quiet vendored Reflexio install failed in $PLUGIN_ROOT; retrying with full output." >&2
+  if ! uv pip install --project "$PLUGIN_ROOT" --python "$PLUGIN_PYTHON" -e "$VENDORED_REFLEXIO" >&2; then
+    write_failure "vendored Reflexio install failed in $PLUGIN_ROOT"
+  fi
+}
+
 write_success_marker() {
   install_fingerprint > "$SUCCESS_MARKER"
 }
@@ -362,19 +395,6 @@ if install_complete; then
   exit 0
 fi
 
-# Dev-mode only: when running from a git checkout, pull the reflexio
-# submodule so tests/benchmarks can use its sources. In install mode the
-# plugin lives under ~/.claude/plugins/cache and reflexio-ai resolves
-# from PyPI instead. The guard checks for both `.git` and `.gitmodules`
-# at REPO_ROOT to distinguish a dev checkout from a marketplace cache
-# (where REPO_ROOT has neither).
-if [ -d "$REPO_ROOT/.git" ] && [ -f "$REPO_ROOT/.gitmodules" ]; then
-  echo "[claude-smart] initializing reflexio submodule..." >&2
-  if ! (cd "$REPO_ROOT" && git submodule update --init --recursive reflexio) >&2; then
-    echo "[claude-smart] WARNING: git submodule update failed; continuing with PyPI reflexio-ai" >&2
-  fi
-fi
-
 if ! command -v uv >/dev/null 2>&1; then
   echo "[claude-smart] uv not found — installing from astral.sh..." >&2
   # The astral.sh bash installer downloads a zip and unzips it. On
@@ -422,6 +442,18 @@ echo "[claude-smart] running uv sync..." >&2
 if ! uv sync --locked --python 3.12 --quiet >&2; then
   write_failure "uv sync failed in $PLUGIN_ROOT — run 'uv sync --locked --python 3.12' there to diagnose"
 fi
+# Defend against a stale lockfile silently dropping the project install.
+# When plugin/uv.lock pins a different claude-smart version than pyproject.toml,
+# `uv sync --locked` exits 0 but does NOT install the claude_smart package, so
+# every hook fails later with `ModuleNotFoundError: No module named 'claude_smart'`.
+# Catch that here with a clear, user-visible install-failed marker.
+if ! claude_smart_python_imports "$PLUGIN_ROOT" claude_smart.hook; then
+  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)"
+fi
+install_vendored_reflexio
+if ! claude_smart_python_imports "$PLUGIN_ROOT" claude_smart.hook; then
+  write_failure "claude-smart package is not importable after vendored Reflexio install in $PLUGIN_ROOT/.venv"
+fi
 
 # Reflexio's CLI reads ~/.reflexio/.env (see reflexio/cli/env_loader.py);
 # append our two opt-in flags there so `reflexio services start` picks
@@ -465,6 +497,63 @@ claude_smart_env_upsert() {
   fi
 }
 
+claude_smart_env_append_raw_if_missing() {
+  local key value
+  key="$1"
+  value="$2"
+  if ! grep -qE "^(export[[:space:]]+)?${key}=" "$REFLEXIO_ENV"; then
+    printf '%s=%s\n' "$key" "$value" >> "$REFLEXIO_ENV"
+  fi
+}
+
+claude_smart_prune_managed_env_keys_for_local() {
+  local tmp line raw_key key
+  [ -f "$REFLEXIO_ENV" ] || return 0
+  tmp="$(mktemp "${REFLEXIO_ENV}.tmp.XXXXXX")"
+  while IFS= read -r line || [ -n "$line" ]; do
+    raw_key="$line"
+    raw_key="${raw_key#"${raw_key%%[![:space:]]*}"}"
+    case "$raw_key" in
+      export\ *) raw_key="${raw_key#export }" ;;
+    esac
+    key="${raw_key%%=*}"
+    key="${key%"${key##*[![:space:]]}"}"
+    case "$key" in
+      REFLEXIO_URL|REFLEXIO_API_KEY|REFLEXIO_USER_ID)
+        continue
+        ;;
+    esac
+    printf '%s\n' "$line" >> "$tmp"
+  done < "$REFLEXIO_ENV"
+  mv "$tmp" "$REFLEXIO_ENV"
+}
+
+claude_smart_ensure_local_env_defaults() {
+  [ -z "${REFLEXIO_API_KEY:-}" ] || return 0
+  mkdir -p "$(dirname "$REFLEXIO_ENV")"
+  touch "$REFLEXIO_ENV"
+  chmod 600 "$REFLEXIO_ENV"
+  claude_smart_prune_managed_env_keys_for_local
+  unset REFLEXIO_URL REFLEXIO_API_KEY REFLEXIO_USER_ID CLAUDE_SMART_MANAGED_SETUP
+  if ! grep -qE '^(export[[:space:]]+)?CLAUDE_SMART_USE_LOCAL_CLI=' "$REFLEXIO_ENV"; then
+    printf '# Route reflexio generation through the local Claude Code CLI\n' >> "$REFLEXIO_ENV"
+    claude_smart_env_append_raw_if_missing CLAUDE_SMART_USE_LOCAL_CLI "1"
+    echo "[claude-smart] appended CLAUDE_SMART_USE_LOCAL_CLI=1 to $REFLEXIO_ENV" >&2
+  fi
+  if ! grep -qE '^(export[[:space:]]+)?CLAUDE_SMART_USE_LOCAL_EMBEDDING=' "$REFLEXIO_ENV"; then
+    printf '# Use the in-process ONNX embedder (chromadb) - no API key for semantic search\n' >> "$REFLEXIO_ENV"
+    claude_smart_env_append_raw_if_missing CLAUDE_SMART_USE_LOCAL_EMBEDDING "1"
+    echo "[claude-smart] appended CLAUDE_SMART_USE_LOCAL_EMBEDDING=1 to $REFLEXIO_ENV" >&2
+  fi
+  if ! grep -qE '^(export[[:space:]]+)?CLAUDE_SMART_READ_ONLY=' "$REFLEXIO_ENV"; then
+    claude_smart_env_upsert CLAUDE_SMART_READ_ONLY "0"
+    echo "[claude-smart] appended CLAUDE_SMART_READ_ONLY=0 to $REFLEXIO_ENV" >&2
+  fi
+  chmod 600 "$REFLEXIO_ENV"
+}
+
+claude_smart_ensure_local_env_defaults
+
 # Migrate stale REFLEXIO_URL from reflexio's library default (8081) to the
 # plugin backend port (8071). Matches the quoted and unquoted forms but
 # requires paired quotes, so malformed or deliberately different values