claude-smart 0.2.29 → 0.2.31

package/README.md

@@ -6,14 +6,14 @@
   claude-smart
 </h1>
 
-<h4 align="center">A local learning plugin for <a href="https://claude.com/claude-code" target="_blank">Claude Code</a> and Codex that turns corrections into durable rules your coding assistant follows in future sessions.</h4>
+<h4 align="center">A self-improvement plugin for <a href="https://claude.com/claude-code" target="_blank">Claude Code</a> and Codex that turns interactions into durable skills they follow in future sessions.</h4>
 
 <p align="center">
   <a href="LICENSE">
     <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.29-green.svg" alt="Version">
+    <img src="https://img.shields.io/badge/version-0.2.31-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">
@@ -24,9 +24,6 @@
   <a href="#quick-start">
     <img src="https://img.shields.io/badge/hosts-Claude%20Code%20%2B%20Codex-purple.svg" alt="Hosts">
   </a>
-  <a href="https://discord.gg/Jbft3jPn">
-    <img src="https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white" alt="Discord">
-  </a>
 </p>
 
 <p align="center">
@@ -40,22 +37,22 @@
 </p>
 
 <p align="center">
-  It learns both corrections and successful execution patterns—so your coding assistant avoids repeating mistakes and reuses what works. Project-specific skills capture repo-local rules, and shared skills roll up durable patterns for reuse across projects.
+  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.
 </p>
 
 <p align="center">
-  <b>vs <code>claude-mem</code>:</b> ~3× better at turning your corrections into rules Claude follows, ~50% more of what you tell Claude sticks. <a href="EXPERIMENT.md"><b>Read the benchmark →</b></a>
+  <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>
 </p>
 
 ---
 
 ## Why Learning, Not Memory
 
-Most memory solutions are still mostly informative—Claude remembers what happened, without necessarily changing what it does next.
+Most memory tools just record. Claude remembers what happened, but doesn't change what it does next.
 
 `claude-smart` focuses on learning instead.
 
-Four ways this changes what your coding assistant can do for you:
+Four things this changes:
 
 - 💡 **Stop repeating the same mistakes:** Produces actionable skills Claude can follow next time; memory only records what happened.
 
@@ -63,12 +60,12 @@ Four ways this changes what your coding assistant can do for you:
   > **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:** Preserves and optimizes execution paths so Claude can reuse what already works.
+- 🚀 **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 starts from the proven path—reducing planning steps, latency, and token usage.
+  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.
 
@@ -95,12 +92,6 @@ claude plugin marketplace add ReflexioAI/claude-smart
 claude plugin install claude-smart@reflexioai
 ```
 
-The plugin Setup hook installs its own `uv`, Python 3.12 environment, and
-private Node.js/npm runtime under `~/.claude-smart/` when they are missing, so
-you do not need to install Python or Node globally for the plugin/dashboard.
-On native Windows, Claude Code hooks still need a Git Bash-compatible `bash`
-until Claude Code exposes a single cross-platform hook command shape.
-
 To uninstall:
 
 ```bash
@@ -123,11 +114,6 @@ Then fully quit and reopen Codex so hooks reload.
 
 Requires the `codex` CLI on `PATH` and Node.js (for `npx`).
 
-The `npx` command needs Node.js only to launch the installer. The installed
-plugin uses a private Node.js/npm runtime and a `uv`-managed Python 3.12
-environment under `~/.claude-smart/`, so hooks and the dashboard do not depend
-on global Python, uv, Node, or npm after install.
-
 To uninstall:
 
 ```bash
@@ -170,7 +156,7 @@ the first local embedding model download. The ONNX model cache lives at
 
 ## Dashboard
 
-A web UI for browsing session histories, inspecting preferences, and editing project-specific and shared skills. The dashboard auto-starts alongside the backend, so you can open **http://localhost:3001** directly. Or run `/claude-smart:dashboard` in Claude Code to launch dashboard in browser. In Codex, run `bash ~/.reflexio/plugin-root/scripts/dashboard-open.sh`.
+A web UI for browsing session histories, inspecting preferences, and editing project-specific and shared skills. The dashboard auto-starts alongside the backend, so you can open **http://localhost:3001** directly. Or run `/claude-smart:dashboard` in Claude Code to open it in your browser. In Codex, run `bash ~/.reflexio/plugin-root/scripts/dashboard-open.sh`.
 
 <p align="center">
   <img src="assets/preferences_dashboard.png" alt="Preferences dashboard" width="49%">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-smart",
-  "version": "0.2.29",
+  "version": "0.2.31",
   "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.29",
+  "version": "0.2.31",
   "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.29",
+  "version": "0.2.31",
   "description": "Self-improving coding assistant plugin — learns from corrections across sessions via reflexio",
   "author": {
     "name": "Yi Lu"

package/plugin/hooks/codex-hooks.json

@@ -18,17 +18,17 @@
           {
             "type": "command",
             "command": "_R=\"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-}}\"; [ -z \"$_R\" ] && _R=$(ls -dt \"$HOME/.codex/plugins/cache/reflexioai/claude-smart\"/*/ 2>/dev/null | head -n 1); [ -n \"$_R\" ] && . \"${_R%/}/scripts/_codex_env.sh\" && bash \"$_R/scripts/backend-service.sh\" start",
-            "timeout": 30
+            "timeout": 300
           },
           {
             "type": "command",
             "command": "_R=\"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-}}\"; [ -z \"$_R\" ] && _R=$(ls -dt \"$HOME/.codex/plugins/cache/reflexioai/claude-smart\"/*/ 2>/dev/null | head -n 1); [ -n \"$_R\" ] && . \"${_R%/}/scripts/_codex_env.sh\" && bash \"$_R/scripts/dashboard-service.sh\" start",
-            "timeout": 10
+            "timeout": 300
           },
           {
             "type": "command",
             "command": "_R=\"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-}}\"; [ -z \"$_R\" ] && _R=$(ls -dt \"$HOME/.codex/plugins/cache/reflexioai/claude-smart\"/*/ 2>/dev/null | head -n 1); [ -n \"$_R\" ] && . \"${_R%/}/scripts/_codex_env.sh\" && bash \"$_R/scripts/hook_entry.sh\" codex session-start",
-            "timeout": 30,
+            "timeout": 300,
             "statusMessage": "Loading claude-smart context"
           }
         ]

package/plugin/hooks/hooks.json

@@ -35,17 +35,17 @@
           {
             "type": "command",
             "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/reflexioai/plugin\"; bash \"$_R/scripts/hook_entry.sh\" claude-code session-start",
-            "timeout": 30
+            "timeout": 300
           },
           {
             "type": "command",
             "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/reflexioai/plugin\"; bash \"$_R/scripts/backend-service.sh\" start",
-            "timeout": 30
+            "timeout": 300
           },
           {
             "type": "command",
             "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/reflexioai/plugin\"; bash \"$_R/scripts/dashboard-service.sh\" start",
-            "timeout": 10
+            "timeout": 300
           }
         ]
       }
@@ -102,7 +102,7 @@
           {
             "type": "command",
             "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/reflexioai/plugin\"; bash \"$_R/scripts/hook_entry.sh\" claude-code session-end",
-            "timeout": 60
+            "timeout": 300
           },
           {
             "type": "command",

package/plugin/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "claude-smart"
-version = "0.2.29"
+version = "0.2.31"
 description = "Self-improving Claude Code plugin — learns from corrections via reflexio"
 readme = "README.md"
 requires-python = ">=3.12"

package/plugin/scripts/_lib.sh

@@ -32,6 +32,16 @@ claude_smart_prepend_node_bins() {
   export PATH="$_CS_NODE_ROOT/bin:$_CS_NODE_ROOT:$PATH"
 }
 
+claude_smart_is_internal_invocation_env() {
+  if [ "${CLAUDE_SMART_INTERNAL:-}" = "1" ]; then
+    return 0
+  fi
+  if [ -n "${CLAUDE_CODE_ENTRYPOINT:-}" ] && [ "${CLAUDE_CODE_ENTRYPOINT:-}" != "cli" ]; then
+    return 0
+  fi
+  return 1
+}
+
 claude_smart_dashboard_unavailable_marker() {
   printf '%s\n' "$HOME/.claude-smart/dashboard-unavailable"
 }
@@ -196,6 +206,61 @@ PY
   return 1
 }
 
+# Print a short fingerprint line for a file ("<cksum>:<size>" or "missing").
+claude_smart_fingerprint_file() {
+  local path
+  path="$1"
+  if [ -f "$path" ]; then
+    cksum "$path" 2>/dev/null | awk '{print $1 ":" $2}'
+  else
+    printf 'missing\n'
+  fi
+}
+
+# Print a multi-line fingerprint covering every input that determines
+# whether smart-install.sh can succeed. Order is stable so the hash is
+# reproducible. Args: $1 = plugin_root, $2 = scripts_dir.
+claude_smart_install_fingerprint() {
+  local plugin_root script_dir
+  plugin_root="$1"
+  script_dir="$2"
+  printf 'plugin_root=%s\n' "$plugin_root"
+  printf 'smart_install=%s\n' "$(claude_smart_fingerprint_file "$script_dir/smart-install.sh")"
+  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")"
+  # 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.
+  if command -v uv >/dev/null 2>&1; then
+    printf 'python=%s\n' "$(uv python find 3.12 2>/dev/null || echo missing)"
+  else
+    printf 'python=no-uv\n'
+  fi
+  if [ -d "$plugin_root/dashboard" ]; then
+    printf 'dashboard_pkg=%s\n' "$(claude_smart_fingerprint_file "$plugin_root/dashboard/package.json")"
+    printf 'dashboard_lock=%s\n' "$(claude_smart_fingerprint_file "$plugin_root/dashboard/package-lock.json")"
+  else
+    printf 'dashboard_pkg=none\n'
+    printf 'dashboard_lock=none\n'
+  fi
+}
+
+# Hash the install fingerprint to a single short hex string. Used by the
+# install-failed marker so hook_entry.sh can detect when inputs change and
+# auto-clear a stale marker. Args: $1 = plugin_root, $2 = scripts_dir.
+claude_smart_install_fingerprint_hash() {
+  local plugin_root script_dir tmp rc
+  plugin_root="$1"
+  script_dir="$2"
+  tmp=$(mktemp 2>/dev/null) || return 1
+  claude_smart_install_fingerprint "$plugin_root" "$script_dir" > "$tmp"
+  claude_smart_sha256_file "$tmp"
+  rc=$?
+  rm -f "$tmp"
+  return $rc
+}
+
 # Return 0 if `node` exists and satisfies the minimum major/minor pair.
 # Patch versions are intentionally ignored because our requirement is a
 # floor, not an exact runtime pin.

package/plugin/scripts/backend-service.sh

@@ -25,15 +25,21 @@ claude_smart_prepend_astral_bins
 
 CMD="${1:-start}"
 PORT=8071
+EMBEDDING_PORT="${EMBEDDING_PORT:-8072}"
 # Pass through to `reflexio services start/stop` so the spawned backend
 # binds to PORT instead of reflexio's library default (8081).
 export BACKEND_PORT="$PORT"
+export EMBEDDING_PORT
 
 # Default: route extraction through the active host CLI + ONNX embedder
 # so claude-smart works without any LLM API key. Users can opt out by
 # pre-exporting these to 0.
 export CLAUDE_SMART_USE_LOCAL_CLI="${CLAUDE_SMART_USE_LOCAL_CLI:-1}"
 export CLAUDE_SMART_USE_LOCAL_EMBEDDING="${CLAUDE_SMART_USE_LOCAL_EMBEDDING:-1}"
+if [ "${CLAUDE_SMART_USE_LOCAL_EMBEDDING:-}" = "1" ]; then
+  export REFLEXIO_EMBEDDING_PROVIDER="${REFLEXIO_EMBEDDING_PROVIDER:-local_service}"
+  export REFLEXIO_EMBEDDING_SERVICE_URL="${REFLEXIO_EMBEDDING_SERVICE_URL:-http://127.0.0.1:$EMBEDDING_PORT}"
+fi
 # The backend can be spawned from contexts whose PATH lacks the host
 # CLI dir (commonly ~/.local/bin or /opt/homebrew/bin). Pin the CLI
 # explicitly if we can resolve it from our own (post-login-path) PATH.
@@ -173,6 +179,9 @@ full_stop() {
 
 case "$CMD" in
   start)
+    if claude_smart_is_internal_invocation_env; then
+      emit_ok; exit 0
+    fi
     # Opt-out: users who don't want the backend managed by the hook can
     # set CLAUDE_SMART_BACKEND_AUTOSTART=0.
     if [ "${CLAUDE_SMART_BACKEND_AUTOSTART:-1}" = "0" ]; then
@@ -186,8 +195,16 @@ case "$CMD" in
       emit_ok; exit 0
     fi
     if ! command -v uv >/dev/null 2>&1; then
-      claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" "[claude-smart] backend: uv not on PATH; skipping"
-      emit_ok; exit 0
+      if [ "${CLAUDE_SMART_BOOTSTRAPPING:-}" != "1" ] && [ -x "$PLUGIN_ROOT/scripts/smart-install.sh" ]; then
+        claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" "[claude-smart] backend: uv not on PATH; running installer"
+        CLAUDE_SMART_BOOTSTRAPPING=1 bash "$PLUGIN_ROOT/scripts/smart-install.sh" >>"$STATE_DIR/install.log" 2>&1 || true
+        claude_smart_source_login_path
+        claude_smart_prepend_astral_bins
+      fi
+      if ! command -v uv >/dev/null 2>&1; then
+        claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" "[claude-smart] backend: uv not on PATH after installer; skipping"
+        emit_ok; exit 0
+      fi
     fi
     cd "$PLUGIN_ROOT"
 
@@ -198,16 +215,21 @@ case "$CMD" in
     export INTERACTION_CLEANUP_THRESHOLD="${INTERACTION_CLEANUP_THRESHOLD:-500}"
     export INTERACTION_CLEANUP_DELETE_COUNT="${INTERACTION_CLEANUP_DELETE_COUNT:-200}"
 
-    # --no-reload: uvicorn's reloader forks a supervisor; makes
-    # bookkeeping harder and we don't need hot-reload for a user-facing
-    # service. Detach via claude_smart_spawn_detached so the same code
-    # path covers Linux (setsid), macOS (python3 os.setsid), and Windows
     # (nohup; no process groups). backend-log-runner.sh owns stdout/stderr
     # capture so process output cannot grow backend.log past its cap.
+    #
+    # --workers: reflexio defaults to 2 (zero-downtime worker recycling
+    # for server deployments). For a single-user Claude Code plugin
+    # that's pure overhead: ~1.1 GB extra RSS, periodic 5–10 s spawn
+    # hiccups during worker rotation, and SQLite can't accept concurrent
+    # writers anyway. Default to 1 here; opt in to N via
+    # CLAUDE_SMART_BACKEND_WORKERS for power users running concurrent
+    # Claude Code sessions or wanting zero-downtime recycling.
+    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 \
-      reflexio services start --only backend --no-reload
+      reflexio services start --only backend --no-reload --workers "$workers"
     svc_pid=$!
     # Record the spawned pid, not a pgid sampled with ps. On POSIX,
     # setsid/python os.setsid make this pid the new process group leader;

package/plugin/scripts/cli.sh

@@ -24,7 +24,7 @@ PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
 # on a broken install.
 FAILURE_MARKER="$HOME/.claude-smart/install-failed"
 if [ -f "$FAILURE_MARKER" ]; then
-  msg="$(cat "$FAILURE_MARKER" 2>/dev/null || echo "")"
+  msg="$(head -n 1 "$FAILURE_MARKER" 2>/dev/null || echo "")"
   [ -n "$msg" ] || msg="unknown error"
   echo "claude-smart is not installed correctly: $msg" >&2
   echo "Re-run the plugin's Setup (restart Claude Code) or fix the underlying issue and delete $FAILURE_MARKER to retry." >&2
@@ -50,7 +50,8 @@ if ! command -v uv >/dev/null 2>&1; then
   fi
   if ! command -v uv >/dev/null 2>&1; then
     if [ -f "$FAILURE_MARKER" ]; then
-      msg="$(cat "$FAILURE_MARKER" 2>/dev/null || echo "unknown error")"
+      msg="$(head -n 1 "$FAILURE_MARKER" 2>/dev/null || echo "")"
+      [ -n "$msg" ] || msg="unknown error"
       echo "claude-smart: install failed: $msg" >&2
       echo "Fix the underlying issue and delete $FAILURE_MARKER to retry." >&2
     else

package/plugin/scripts/codex-hook.js

@@ -104,6 +104,10 @@ function npmPath() {
   return commandPath(process.platform === "win32" ? ["npm.cmd", "npm.exe", "npm"] : ["npm"]);
 }
 
+function bashPath() {
+  return commandPath(process.platform === "win32" ? ["bash.exe", "bash"] : ["bash"]);
+}
+
 function stateFile(name) {
   return path.join(STATE_DIR, name);
 }
@@ -202,6 +206,49 @@ function detached(command, args, options = {}) {
   return child.pid;
 }
 
+function runInstaller(root, reason) {
+  if (process.env.CLAUDE_SMART_BOOTSTRAPPING === "1") return false;
+  const script = path.join(root, "scripts", "smart-install.sh");
+  if (!fs.existsSync(script)) return false;
+  const bash = bashPath();
+  if (!bash) return false;
+  appendLog("backend.log", `[claude-smart] ${reason}; running installer`);
+  const result = spawnSync(bash, [script], {
+    cwd: root,
+    env: {
+      ...process.env,
+      CLAUDE_SMART_BOOTSTRAPPING: "1",
+    },
+    encoding: "utf8",
+    maxBuffer: 20 * 1024 * 1024,
+    windowsHide: true,
+  });
+  const output = `${result.stdout || ""}${result.stderr || ""}`.trim();
+  if (output) {
+    ensureDir(STATE_DIR);
+    fs.appendFileSync(path.join(STATE_DIR, "install.log"), `${output}\n`);
+    trimLog(path.join(STATE_DIR, "install.log"));
+  }
+  prependRuntimePath();
+  return result.status === 0;
+}
+
+function startInstallerDetached(root, reason) {
+  if (process.env.CLAUDE_SMART_BOOTSTRAPPING === "1") return false;
+  const script = path.join(root, "scripts", "smart-install.sh");
+  const bash = bashPath();
+  if (!bash || !fs.existsSync(script)) return false;
+  appendLog("backend.log", `[claude-smart] ${reason}; starting installer in background`);
+  detached(bash, [script], {
+    cwd: root,
+    env: {
+      ...process.env,
+      CLAUDE_SMART_BOOTSTRAPPING: "1",
+    },
+  });
+  return true;
+}
+
 function readPid(file) {
   try {
     const value = fs.readFileSync(file, "utf8").trim();
@@ -262,7 +309,11 @@ async function startBackend(root) {
   }
   const uv = uvPath();
   if (!uv) {
-    appendLog("backend.log", "[claude-smart] backend: uv not on PATH; skipping");
+    runInstaller(root, "backend: uv not on PATH");
+  }
+  const readyUv = uvPath();
+  if (!readyUv) {
+    appendLog("backend.log", "[claude-smart] backend: uv not on PATH after installer; skipping");
     emitOk();
     return;
   }
@@ -284,7 +335,7 @@ async function startBackend(root) {
     INTERACTION_CLEANUP_DELETE_COUNT: process.env.INTERACTION_CLEANUP_DELETE_COUNT || "200",
   };
   const pid = detached(
-    uv,
+    readyUv,
     [
       "run",
       "--project",
@@ -326,14 +377,18 @@ async function startDashboard(root) {
   }
   const npm = npmPath();
   if (!npm) {
-    appendLog("dashboard.log", "[claude-smart] dashboard: npm not on PATH; skipping");
+    runInstaller(root, "dashboard: npm not on PATH");
+  }
+  const readyNpm = npmPath();
+  if (!readyNpm) {
+    appendLog("dashboard.log", "[claude-smart] dashboard: npm not on PATH after installer; skipping");
     emitOk();
     return;
   }
   if (!fs.existsSync(path.join(dashboard, ".next"))) {
     const buildPidFile = path.join(STATE_DIR, "dashboard-build.pid");
     if (!pidAlive(readPid(buildPidFile))) {
-      const pid = detached(npm, ["run", "build"], { cwd: dashboard });
+      const pid = detached(readyNpm, ["run", "build"], { cwd: dashboard });
       writePid(buildPidFile, pid);
       appendLog("dashboard.log", "[claude-smart] dashboard: .next missing; started background build");
     }
@@ -346,7 +401,7 @@ async function startDashboard(root) {
     REFLEXIO_URL: readBackendUrl(),
     CLAUDE_SMART_DASHBOARD_WORKSPACE: process.cwd(),
   };
-  const pid = detached(npm, ["run", "start"], { cwd: dashboard, env });
+  const pid = detached(readyNpm, ["run", "start"], { cwd: dashboard, env });
   writePid(pidFile, pid);
   await waitForHealth(DASHBOARD_PORT, "/api/health", "x-claude-smart-dashboard", 5);
   emitOk();
@@ -354,11 +409,19 @@ async function startDashboard(root) {
 
 function runHook(root, event) {
   trimLog(path.join(STATE_DIR, "backend.log"));
-  const uv = uvPath();
+  let uv = uvPath();
   if (!uv) {
-    appendLog("backend.log", "[claude-smart] hook: uv not on PATH; skipping");
-    emitOk();
-    return 0;
+    if (event === "session-start") {
+      runInstaller(root, "hook: uv not on PATH");
+      uv = uvPath();
+    } else {
+      startInstallerDetached(root, "hook: uv not on PATH");
+    }
+    if (!uv) {
+      appendLog("backend.log", "[claude-smart] hook: uv not on PATH after installer; skipping");
+      emitOk();
+      return 0;
+    }
   }
   const input = fs.readFileSync(0);
   const result = spawnSync(

package/plugin/scripts/dashboard-service.sh

@@ -87,6 +87,9 @@ port_occupied() {
 
 case "$CMD" in
   start)
+    if claude_smart_is_internal_invocation_env; then
+      emit_ok; exit 0
+    fi
     # Opt-out: users who don't want the dashboard long-lived can set
     # CLAUDE_SMART_DASHBOARD_AUTOSTART=0 in their environment.
     if [ "${CLAUDE_SMART_DASHBOARD_AUTOSTART:-1}" = "0" ]; then
@@ -100,10 +103,19 @@ case "$CMD" in
     fi
     NPM_BIN=$(claude_smart_resolve_npm || true)
     if [ -z "$NPM_BIN" ] || ! "$NPM_BIN" --version >/dev/null 2>&1; then
-      reason="npm is not on PATH; dashboard cannot start"
-      echo "[claude-smart] dashboard: $reason; skipping" >>"$LOG_FILE"
-      claude_smart_write_dashboard_unavailable "$reason"
-      emit_ok; exit 0
+      if [ "${CLAUDE_SMART_BOOTSTRAPPING:-}" != "1" ] && [ -x "$PLUGIN_ROOT/scripts/smart-install.sh" ]; then
+        echo "[claude-smart] dashboard: npm is not on PATH; running installer" >>"$LOG_FILE"
+        CLAUDE_SMART_BOOTSTRAPPING=1 bash "$PLUGIN_ROOT/scripts/smart-install.sh" >>"$STATE_DIR/install.log" 2>&1 || true
+        claude_smart_source_login_path
+        claude_smart_prepend_node_bins
+        NPM_BIN=$(claude_smart_resolve_npm || true)
+      fi
+      if [ -z "$NPM_BIN" ] || ! "$NPM_BIN" --version >/dev/null 2>&1; then
+        reason="npm is not on PATH after installer; dashboard cannot start"
+        echo "[claude-smart] dashboard: $reason; skipping" >>"$LOG_FILE"
+        claude_smart_write_dashboard_unavailable "$reason"
+        emit_ok; exit 0
+      fi
     fi
 
     # `npm run start` requires a prior `next build`. Do NOT build in the

package/plugin/scripts/hook_entry.sh

@@ -26,6 +26,10 @@ fi
 HERE="$(cd "$(dirname "$0")" && pwd)"
 # shellcheck source=_lib.sh
 . "$HERE/_lib.sh"
+if claude_smart_is_internal_invocation_env; then
+  echo '{"continue":true,"suppressOutput":true}'
+  exit 0
+fi
 # Pick up uv from the user's login-shell PATH (covers ~/.local/bin populated
 # by the astral.sh installer) so a fresh install works before the user
 # restarts their terminal. Matches the pattern used by smart-install.sh.
@@ -37,11 +41,22 @@ claude_smart_prepend_astral_bins
 PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
 
 FAILURE_MARKER="$HOME/.claude-smart/install-failed"
+STATE_DIR="$HOME/.claude-smart"
 if [ -f "$FAILURE_MARKER" ]; then
-  if [ "$EVENT" = "session-start" ] && command -v python3 >/dev/null 2>&1; then
-    python3 - "$FAILURE_MARKER" <<'PY'
+  # Auto-clear the marker when install inputs have changed since the
+  # failure was recorded (pyproject.toml / uv.lock / smart-install.sh /
+  # python interpreter etc.). Without this the plugin stays muted forever
+  # after a transient sync failure even when the user has fixed it.
+  stored_fp="$(awk -F= '$1=="fingerprint"{print $2; exit}' "$FAILURE_MARKER" 2>/dev/null || true)"
+  current_fp="$(claude_smart_install_fingerprint_hash "$PLUGIN_ROOT" "$HERE" 2>/dev/null || true)"
+  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'
 import json, pathlib, sys
-msg = pathlib.Path(sys.argv[1]).read_text().strip() or "unknown error"
+first = pathlib.Path(sys.argv[1]).read_text().splitlines()
+msg = (first[0].strip() if first else "") or "unknown error"
 print(json.dumps({
     "hookSpecificOutput": {
         "hookEventName": "SessionStart",
@@ -54,16 +69,42 @@ print(json.dumps({
     }
 }))
 PY
-  else
-    echo '{"continue":true,"suppressOutput":true}'
+    else
+      echo '{"continue":true,"suppressOutput":true}'
+    fi
+    exit 0
   fi
-  exit 0
 fi
 
 if ! command -v uv >/dev/null 2>&1; then
-  # uv missing post-install → don't crash the session, just no-op.
-  echo '{"continue":true,"suppressOutput":true}'
-  exit 0
+  # Self-heal from skipped Setup/SessionStart bootstrap. SessionStart can
+  # afford to wait because it has the install budget; prompt/tool hooks start
+  # the same installer detached so normal work is not blocked by first-run
+  # dependency setup.
+  if [ "${CLAUDE_SMART_BOOTSTRAPPING:-}" = "1" ]; then
+    echo '{"continue":true,"suppressOutput":true}'
+    exit 0
+  fi
+  if [ -x "$PLUGIN_ROOT/scripts/smart-install.sh" ]; then
+    mkdir -p "$STATE_DIR"
+    if [ "$EVENT" = "session-start" ]; then
+      CLAUDE_SMART_BOOTSTRAPPING=1 bash "$PLUGIN_ROOT/scripts/smart-install.sh" >&2
+      claude_smart_prepend_astral_bins
+      claude_smart_prepend_node_bins
+      if command -v uv >/dev/null 2>&1; then
+        bash "$HERE/backend-service.sh" start >/dev/null 2>&1 || true
+        bash "$HERE/dashboard-service.sh" start >/dev/null 2>&1 || true
+      fi
+    else
+      claude_smart_spawn_detached env CLAUDE_SMART_BOOTSTRAPPING=1 \
+        bash "$PLUGIN_ROOT/scripts/smart-install.sh" \
+        >>"$STATE_DIR/install.log" 2>&1 || true
+    fi
+  fi
+  if ! command -v uv >/dev/null 2>&1; then
+    echo '{"continue":true,"suppressOutput":true}'
+    exit 0
+  fi
 fi
 
 # Stdin is the hook payload JSON — stream it through to the Python CLI.