claude-smart 0.2.42 → 0.2.44

package/.claude-plugin/marketplace.json

@@ -4,14 +4,14 @@
     "name": "Yi Lu"
   },
   "metadata": {
-    "description": "claude-smart — self-improving Claude Code plugin via reflexio"
+    "description": "claude-smart — self-improving Claude Code and Codex plugin via reflexio"
   },
   "plugins": [
     {
       "name": "claude-smart",
-      "version": "0.2.42",
+      "version": "0.2.44",
       "source": "./plugin",
-      "description": "Learns user corrections and project playbooks via reflexio — uses Claude Code itself as the LLM backend (no external API key required)"
+      "description": "Turns user corrections into project-specific and shared skills via reflexio — uses Claude Code or Codex as the LLM backend (no external API key required)"
     }
   ]
 }

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.42-green.svg" alt="Version">
+    <img src="https://img.shields.io/badge/version-0.2.44-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">

package/bin/claude-smart.js

@@ -905,7 +905,7 @@ async function installVendoredReflexio(pluginRoot, uv, env) {
   process.stdout.write(`Installing bundled Reflexio source from ${vendorRoot}...\n`);
   let code = await runChecked(
     uv,
-    ["pip", "install", "--project", pluginRoot, "--python", pythonPath, "--quiet", "-e", vendorRoot],
+    ["pip", "install", "--project", pluginRoot, "--python", pythonPath, "--quiet", "--reinstall", "--no-deps", vendorRoot],
     { cwd: pluginRoot, env },
   );
   if (code !== 0) {
@@ -914,7 +914,7 @@ async function installVendoredReflexio(pluginRoot, uv, env) {
     );
     code = await runChecked(
       uv,
-      ["pip", "install", "--project", pluginRoot, "--python", pythonPath, "-e", vendorRoot],
+      ["pip", "install", "--project", pluginRoot, "--python", pythonPath, "--reinstall", "--no-deps", vendorRoot],
       { cwd: pluginRoot, env },
     );
   }

package/package.json

@@ -1,14 +1,20 @@
 {
   "name": "claude-smart",
-  "version": "0.2.42",
-  "description": "Self-improving Claude Code plugin — learns from corrections via reflexio",
+  "version": "0.2.44",
+  "description": "Self-improving Claude Code and Codex plugin — turns corrections into durable skills via reflexio",
   "keywords": [
     "claude",
     "claude-code",
+    "claude-code-plugin",
+    "codex",
+    "codex-plugin",
+    "memory",
+    "agent-memory",
     "plugin",
     "reflexio",
     "self-improvement",
-    "playbook",
+    "self-improving-agents",
+    "skills",
     "learning"
   ],
   "homepage": "https://github.com/ReflexioAI/claude-smart#readme",

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

@@ -1,17 +1,23 @@
 {
   "name": "claude-smart",
-  "version": "0.2.42",
-  "description": "Self-improving Claude Code plugin — learns from corrections across sessions via reflexio",
+  "version": "0.2.44",
+  "description": "Self-improving Claude Code and Codex plugin — turns corrections into durable skills via reflexio",
   "author": {
     "name": "Yi Lu"
   },
   "keywords": [
     "claude",
     "claude-code",
+    "claude-code-plugin",
+    "codex",
+    "codex-plugin",
+    "memory",
+    "agent-memory",
     "plugin",
     "reflexio",
     "self-improvement",
-    "playbook",
+    "self-improving-agents",
+    "skills",
     "learning"
   ]
 }

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

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

package/plugin/README.md

@@ -1,11 +1,13 @@
 # claude-smart
 
-Self-improving [Claude Code](https://claude.com/claude-code) plugin — turns your corrections into durable rules that Claude Code follows in future sessions, via [reflexio](https://github.com/ReflexioAI/reflexio).
+Self-improving [Claude Code](https://claude.com/claude-code) and Codex plugin — turns your corrections into durable skills that future sessions follow, via [reflexio](https://github.com/ReflexioAI/reflexio).
 
-This directory is the published Python package (`claude-smart` on PyPI) and the Claude Code plugin payload shipped through the marketplace. For the project overview, install instructions, benchmarks, and feature walkthrough, see the [top-level README](https://github.com/ReflexioAI/claude-smart#readme).
+This directory is the published Python package (`claude-smart` on PyPI) and the Claude Code/Codex plugin payload shipped through the marketplace. For the project overview, install instructions, benchmarks, and feature walkthrough, see the [top-level README](https://github.com/ReflexioAI/claude-smart#readme).
 
 ## Install
 
+### Claude Code
+
 ```bash
 claude plugin marketplace add ReflexioAI/claude-smart
 claude plugin install claude-smart@reflexioai
@@ -25,8 +27,19 @@ embedding/ML dependency stack does not provide a complete native wheel set.
 
 Then restart Claude Code.
 
+### Codex
+
+```bash
+npx claude-smart install --host codex
+```
+
+Then fully quit and reopen Codex so hooks reload. Codex installs reuse the same
+local Preferences, Project-specific skills, and Shared skills as Claude Code.
+
 ## Uninstall
 
+### Claude Code
+
 ```bash
 claude plugin uninstall claude-smart@reflexioai
 ```
@@ -37,7 +50,14 @@ Or, if Node.js or uv is already installed:
 npx claude-smart uninstall   # or: uvx claude-smart uninstall
 ```
 
-Local data under `~/.reflexio/` and `~/.claude-smart/` is left in place — remove manually if desired.
+### Codex
+
+```bash
+npx claude-smart uninstall --host codex
+```
+
+Restart Codex after uninstalling. Local data under `~/.reflexio/` and
+`~/.claude-smart/` is left in place for both hosts — remove manually if desired.
 
 ## License
 

package/plugin/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "claude-smart"
-version = "0.2.42"
-description = "Self-improving Claude Code plugin — learns from corrections via reflexio"
+version = "0.2.44"
+description = "Self-improving Claude Code and Codex plugin — turns corrections into durable skills via reflexio"
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
@@ -9,7 +9,7 @@ dependencies = [
     # 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",
+    "reflexio-ai>=0.2.25",
     # 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.

package/plugin/scripts/_lib.sh

@@ -220,6 +220,97 @@ importlib.import_module(sys.argv[1])
 PY
 }
 
+claude_smart_canonical_dir() {
+  local dir
+  dir="$1"
+  [ -d "$dir" ] || return 1
+  (cd "$dir" 2>/dev/null && pwd -P)
+}
+
+# True when $1 canonicalizes to a plugin directory that physically lives
+# *inside* ~/.reflexio. claude-smart's real install never places the live
+# plugin tree there: the only entry under ~/.reflexio is the `plugin-root`
+# symlink, whose `pwd -P` resolves to a cache dir *outside* ~/.reflexio
+# (~/.claude, ~/.codex, or the npm global). So any plugin root that resolves
+# to a descendant of ~/.reflexio is a stray host-made copy — e.g. the Windows
+# cwd-derived `CUsers...` directories from issue #65 — that we must not
+# bootstrap a heavy .venv/node_modules into.
+#
+# Detection is structural (descendant-of-~/.reflexio + plugin markers) rather
+# than name-based on purpose: the host mangles the cwd differently per drive
+# and user dir (C:\Users -> CUsers..., D:\repos -> Drepos..., varying case),
+# so matching a fixed prefix like `Cu*` misses most real copies.
+claude_smart_is_reflexio_session_copy() {
+  local plugin_root reflexio_root
+  plugin_root="$(claude_smart_canonical_dir "$1" 2>/dev/null || true)"
+  [ -n "$plugin_root" ] || return 1
+  # Must look like a plugin root — not ~/.reflexio/data, /configs, or .env.
+  [ -f "$plugin_root/pyproject.toml" ] || return 1
+  [ -d "$plugin_root/scripts" ] || return 1
+  reflexio_root="$(claude_smart_canonical_dir "$HOME/.reflexio" 2>/dev/null || true)"
+  [ -n "$reflexio_root" ] || return 1
+  # Descendant of ~/.reflexio. The trailing slash on the subject plus the
+  # "/" before * pins the boundary so a sibling like ~/.reflexio-bak/plugin
+  # does not match.
+  case "$plugin_root/" in
+    "$reflexio_root"/*) return 0 ;;
+  esac
+  return 1
+}
+
+claude_smart_stable_plugin_root_for_session_copy() {
+  local current candidate current_real candidate_real glob
+  current="$1"
+  if ! claude_smart_is_reflexio_session_copy "$current"; then
+    return 1
+  fi
+  current_real="$(claude_smart_canonical_dir "$current" 2>/dev/null || true)"
+
+  for candidate in \
+    "$HOME/.reflexio/plugin-root" \
+    "$HOME/.claude/plugins/marketplaces/reflexioai/plugin" \
+    "$HOME/.codex/plugins/cache/reflexioai/claude-smart/current"
+  do
+    [ -f "$candidate/pyproject.toml" ] || continue
+    candidate_real="$(claude_smart_canonical_dir "$candidate" 2>/dev/null || true)"
+    [ -n "$candidate_real" ] || continue
+    [ "$candidate_real" != "$current_real" ] || continue
+    if claude_smart_is_reflexio_session_copy "$candidate_real"; then
+      continue
+    fi
+    printf '%s\n' "$candidate_real"
+    return 0
+  done
+
+  for glob in "$HOME/.claude/plugins/cache/reflexioai/claude-smart"/* "$HOME/.codex/plugins/cache/reflexioai/claude-smart"/*; do
+    [ -f "$glob/pyproject.toml" ] || continue
+    candidate_real="$(claude_smart_canonical_dir "$glob" 2>/dev/null || true)"
+    [ -n "$candidate_real" ] || continue
+    [ "$candidate_real" != "$current_real" ] || continue
+    if claude_smart_is_reflexio_session_copy "$candidate_real"; then
+      continue
+    fi
+    printf '%s\n' "$candidate_real"
+    return 0
+  done
+  return 1
+}
+
+claude_smart_reexec_stable_plugin_root_if_needed() {
+  local plugin_root script stable
+  plugin_root="$1"
+  script="$2"
+  stable="$(claude_smart_stable_plugin_root_for_session_copy "$plugin_root" 2>/dev/null || true)"
+  [ -n "$stable" ] || return 0
+  # `-f` not `-x`: we re-run via `exec bash <script>`, which does not need the
+  # executable bit. Cached copies on Windows/NTFS often lack +x, so requiring
+  # -x would no-op the guard on the very platform issue #65 affects.
+  [ -f "$stable/scripts/$script" ] || return 0
+  echo "[claude-smart] redirecting stray plugin copy under ~/.reflexio ($plugin_root) to stable root $stable" >&2
+  shift 2
+  exec bash "$stable/scripts/$script" "$@"
+}
+
 claude_smart_download() {
   local url dest src _CS_PY
   url="$1"

package/plugin/scripts/backend-service.sh

@@ -5,8 +5,8 @@
 #
 # Subcommands:
 #   start         probe /health; if nothing we recognize is on the port,
-#                 spawn `uv run reflexio services start --only backend
-#                 --no-reload` detached. Polls /health briefly so first
+#                 spawn the prepared venv's `reflexio services start --only
+#                 backend --no-reload` detached. Polls /health briefly so first
 #                 use after session start lands on a warm server, then
 #                 returns a continue payload regardless.
 #   stop          SIGTERM the recorded process group, escalating to
@@ -45,6 +45,7 @@ fi
 # 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.
 PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
+claude_smart_reexec_stable_plugin_root_if_needed "$PLUGIN_ROOT" "backend-service.sh" "$@"
 
 if [ -z "${CLAUDE_SMART_CLI_PATH:-}" ]; then
   if [ "${CLAUDE_SMART_HOST:-claude-code}" = "codex" ]; then
@@ -182,6 +183,35 @@ port_holder() {
     | awk 'NR==2 {print $1" (pid "$2")"; exit}'
 }
 
+ensure_vendored_reflexio_active() {
+  vendor="$PLUGIN_ROOT/vendor/reflexio"
+  [ -f "$vendor/pyproject.toml" ] || return 0
+  plugin_python="$(claude_smart_plugin_python "$PLUGIN_ROOT")"
+  [ -x "$plugin_python" ] || return 0
+  if "$plugin_python" - "$vendor/pyproject.toml" <<'PY' >/dev/null 2>&1; then
+import importlib.metadata
+import re
+import sys
+from pathlib import Path
+
+text = Path(sys.argv[1]).read_text(encoding="utf-8")
+match = re.search(r'^version\s*=\s*"([^"]+)"', text, re.MULTILINE)
+if not match:
+    raise SystemExit(1)
+expected = match.group(1)
+try:
+    installed = importlib.metadata.version("reflexio-ai")
+except importlib.metadata.PackageNotFoundError:
+    raise SystemExit(1)
+raise SystemExit(0 if installed == expected else 1)
+PY
+    return 0
+  fi
+  claude_smart_append_capped_log "$LOG_FILE" "$LOG_MAX_BYTES" \
+    "[claude-smart] backend: repairing vendored Reflexio install before start"
+  uv pip install --project "$PLUGIN_ROOT" --python "$plugin_python" --quiet --reinstall --no-deps "$vendor" >&2
+}
+
 # Full shutdown: kill the recorded process group (if any) then sweep
 # both the backend port and the embedding-service port for surviving
 # reflexio listeners. Used by both `stop` and the opt-in `session-end`
@@ -242,6 +272,7 @@ case "$CMD" in
       fi
     fi
     cd "$PLUGIN_ROOT"
+    ensure_vendored_reflexio_active
 
     # Cap local interaction history to keep the SQLite store small for
     # claude-smart users. Reflexio's library defaults are much higher
@@ -265,6 +296,21 @@ case "$CMD" in
     # without touching the file on disk.
     export REFLEXIO_STORAGE="sqlite"
 
+    backend_pythonpath="${PYTHONPATH:-}"
+    if [ -d "$PLUGIN_ROOT/vendor/reflexio/reflexio" ]; then
+      vendor_pythonpath="$PLUGIN_ROOT/vendor/reflexio"
+      pythonpath_sep=":"
+      if claude_smart_is_windows; then
+        # Native Windows Python expects ;-separated Windows-style paths in
+        # PYTHONPATH; MSYS does not auto-convert arbitrary env vars.
+        pythonpath_sep=";"
+        if command -v cygpath >/dev/null 2>&1; then
+          vendor_pythonpath="$(cygpath -w "$vendor_pythonpath")"
+        fi
+      fi
+      backend_pythonpath="$vendor_pythonpath${backend_pythonpath:+$pythonpath_sep$backend_pythonpath}"
+    fi
+
     # (nohup; no process groups). backend-log-runner.sh owns stdout/stderr
     # capture so process output cannot grow backend.log past its cap.
     #
@@ -276,11 +322,12 @@ case "$CMD" in
     # CLAUDE_SMART_BACKEND_WORKERS for power users running concurrent
     # Claude Code sessions or wanting zero-downtime recycling.
     workers="${CLAUDE_SMART_BACKEND_WORKERS:-1}"
+    backend_python="$(claude_smart_plugin_python "$PLUGIN_ROOT")"
     claude_smart_spawn_detached bash "$HERE/backend-log-runner.sh" \
       "$LOG_FILE" "$LOG_MAX_BYTES" -- \
       env PYTHONIOENCODING="${PYTHONIOENCODING:-utf-8}" \
-      uv run --project "$PLUGIN_ROOT" --no-sync --quiet \
-      reflexio services start --only backend --no-reload --workers "$workers"
+      PYTHONPATH="$backend_pythonpath" \
+      "$backend_python" -m reflexio.cli 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

@@ -18,6 +18,7 @@ claude_smart_prepend_node_bins
 claude_smart_source_reflexio_env
 
 PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
+claude_smart_reexec_stable_plugin_root_if_needed "$PLUGIN_ROOT" "cli.sh" "$@"
 
 # If the Setup hook recorded an install failure, surface that reason
 # instead of falling through to a generic "uv not found" — mirrors the
@@ -90,4 +91,5 @@ if ! claude_smart_python_imports "$PLUGIN_ROOT" claude_smart.cli; then
   fi
 fi
 
-exec uv run --project "$PLUGIN_ROOT" --no-sync --quiet python -m claude_smart.cli "$@"
+PLUGIN_PYTHON="$(claude_smart_plugin_python "$PLUGIN_ROOT")"
+exec "$PLUGIN_PYTHON" -m claude_smart.cli "$@"

package/plugin/scripts/codex-hook.js

@@ -89,14 +89,82 @@ function appendLog(name, line) {
   trimLog(file);
 }
 
+function realDir(dir) {
+  try {
+    if (!fs.statSync(dir).isDirectory()) return null;
+    return fs.realpathSync(dir);
+  } catch {
+    return null;
+  }
+}
+
+function isInsideDir(parent, child) {
+  const rel = path.relative(parent, child);
+  return rel && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+function isPluginLikeRoot(root) {
+  return fs.existsSync(path.join(root, "pyproject.toml")) && fs.existsSync(path.join(root, "scripts"));
+}
+
+function isReflexioStrayPluginCopy(root) {
+  if (!isPluginLikeRoot(root)) return false;
+  const rootReal = realDir(root);
+  const reflexioReal = realDir(REFLEXIO_DIR);
+  if (!rootReal || !reflexioReal) return false;
+  return isInsideDir(reflexioReal, rootReal);
+}
+
+function stablePluginRootForStrayCopy(root) {
+  if (!isReflexioStrayPluginCopy(root)) return null;
+  const rootReal = realDir(root);
+  const candidates = [
+    path.join(REFLEXIO_DIR, "plugin-root"),
+    path.join(HOME, ".claude", "plugins", "marketplaces", "reflexioai", "plugin"),
+    path.join(HOME, ".codex", "plugins", "cache", "reflexioai", "claude-smart", "current"),
+  ];
+  for (const cacheRoot of [
+    path.join(HOME, ".claude", "plugins", "cache", "reflexioai", "claude-smart"),
+    path.join(HOME, ".codex", "plugins", "cache", "reflexioai", "claude-smart"),
+  ]) {
+    try {
+      const versions = fs
+        .readdirSync(cacheRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => path.join(cacheRoot, entry.name))
+        .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+      candidates.push(...versions);
+    } catch {
+      // Missing cache roots are fine; try the next candidate family.
+    }
+  }
+  for (const candidate of candidates) {
+    if (!isPluginLikeRoot(candidate)) continue;
+    const candidateReal = realDir(candidate);
+    if (!candidateReal || candidateReal === rootReal) continue;
+    if (isReflexioStrayPluginCopy(candidateReal)) continue;
+    return candidateReal;
+  }
+  return null;
+}
+
+function stablePluginRoot(root) {
+  const stable = stablePluginRootForStrayCopy(root);
+  if (stable) {
+    appendLog("backend.log", `[claude-smart] redirecting stray plugin copy under ~/.reflexio (${root}) to stable root ${stable}`);
+    return stable;
+  }
+  return root;
+}
+
 function pluginRoot() {
   for (const value of [process.env.CLAUDE_PLUGIN_ROOT, process.env.PLUGIN_ROOT]) {
     if (value && fs.existsSync(path.join(value, "pyproject.toml"))) {
-      return path.resolve(value);
+      return stablePluginRoot(path.resolve(value));
     }
   }
   const fromScript = path.resolve(__dirname, "..");
-  if (fs.existsSync(path.join(fromScript, "pyproject.toml"))) return fromScript;
+  if (fs.existsSync(path.join(fromScript, "pyproject.toml"))) return stablePluginRoot(fromScript);
   const cacheRoot = path.join(HOME, ".codex", "plugins", "cache", "reflexioai", "claude-smart");
   try {
     const versions = fs
@@ -105,12 +173,12 @@ function pluginRoot() {
       .map((entry) => path.join(cacheRoot, entry.name))
       .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
     for (const candidate of versions) {
-      if (fs.existsSync(path.join(candidate, "pyproject.toml"))) return candidate;
+      if (fs.existsSync(path.join(candidate, "pyproject.toml"))) return stablePluginRoot(candidate);
     }
   } catch {
     // Fall through to the stable plugin-root link.
   }
-  return path.join(REFLEXIO_DIR, "plugin-root");
+  return stablePluginRoot(path.join(REFLEXIO_DIR, "plugin-root"));
 }
 
 function prependRuntimePath() {

package/plugin/scripts/dashboard-build.sh

@@ -27,6 +27,7 @@ claude_smart_source_login_path
 claude_smart_prepend_node_bins
 
 PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
+claude_smart_reexec_stable_plugin_root_if_needed "$PLUGIN_ROOT" "dashboard-build.sh" "$@"
 DASHBOARD_DIR="$PLUGIN_ROOT/dashboard"
 
 STATE_DIR="$HOME/.claude-smart"

package/plugin/scripts/dashboard-service.sh

@@ -29,6 +29,7 @@ CMD="${1:-start}"
 PORT=3001
 
 PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
+claude_smart_reexec_stable_plugin_root_if_needed "$PLUGIN_ROOT" "dashboard-service.sh" "$@"
 DASHBOARD_DIR="$PLUGIN_ROOT/dashboard"
 WORKSPACE_CWD="${PWD:-}"
 

package/plugin/scripts/ensure-plugin-root.sh

@@ -20,6 +20,7 @@ if [ ! -f "$TARGET/pyproject.toml" ]; then
     echo "[claude-smart] ensure-plugin-root: $TARGET is not a plugin dir (no pyproject.toml)" >&2
     exit 1
 fi
+TARGET="$(cd "$TARGET" && pwd -P)"
 
 LINK="$HOME/.reflexio/plugin-root"
 mkdir -p "$(dirname "$LINK")"

package/plugin/scripts/hook_entry.sh

@@ -3,8 +3,9 @@
 # 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 --no-sync` so the prepared env is used without
-# undoing editable Reflexio installs from local development.
+# We invoke the prepared venv Python directly so hooks use the dependency set
+# produced by smart-install.sh, including the vendored Reflexio snapshot it
+# installs non-editably (--reinstall --no-deps).
 #
 # If the Setup hook recorded an install failure at
 # ~/.claude-smart/install-failed, short-circuit with a user-visible
@@ -46,6 +47,7 @@ claude_smart_prepend_astral_bins
 claude_smart_source_reflexio_env
 
 PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
+claude_smart_reexec_stable_plugin_root_if_needed "$PLUGIN_ROOT" "hook_entry.sh" "$@"
 
 FAILURE_MARKER="$HOME/.claude-smart/install-failed"
 STATE_DIR="$HOME/.claude-smart"
@@ -134,4 +136,5 @@ if ! ensure_hook_package_importable; then
 fi
 
 # Stdin is the hook payload JSON — stream it through to the Python CLI.
-exec uv run --project "$PLUGIN_ROOT" --no-sync --quiet python -m claude_smart.hook "$HOST" "$EVENT"
+PLUGIN_PYTHON="$(claude_smart_plugin_python "$PLUGIN_ROOT")"
+exec "$PLUGIN_PYTHON" -m claude_smart.hook "$HOST" "$EVENT"

package/plugin/scripts/smart-install.sh

@@ -17,6 +17,7 @@ claude_smart_prepend_node_bins
 claude_smart_source_reflexio_env
 
 PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
+claude_smart_reexec_stable_plugin_root_if_needed "$PLUGIN_ROOT" "smart-install.sh" "$@"
 REPO_ROOT="$(cd "$HERE/../.." && pwd)"
 
 MARKER_DIR="$HOME/.claude-smart"
@@ -141,12 +142,12 @@ install_vendored_reflexio() {
   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
+  if uv pip install --project "$PLUGIN_ROOT" --python "$PLUGIN_PYTHON" --quiet --reinstall --no-deps "$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
+  if ! uv pip install --project "$PLUGIN_ROOT" --python "$PLUGIN_PYTHON" --reinstall --no-deps "$VENDORED_REFLEXIO" >&2; then
     write_failure "vendored Reflexio install failed in $PLUGIN_ROOT"
   fi
 }

package/plugin/src/README.md

@@ -0,0 +1,57 @@
+# claude_smart (plugin/src)
+Description: Python package powering the claude-smart plugin — hook handlers that buffer Claude Code / Codex session activity, publish it to a local Reflexio backend, and inject the learned skills/preferences back into future sessions.
+
+> User-facing install/usage docs live in [`../README.md`](../README.md). This is the code map for the `claude_smart` package.
+
+## Main Entry Points
+
+| File | Purpose |
+|------|---------|
+| `hook.py` | Hook dispatcher. Parses the stdin JSON payload and routes each event (Setup, SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) to its handler in `events/`. |
+| `cli.py` | `claude-smart` CLI: `install`, `uninstall`, `show`, `learn`, `restart`, `dashboard`, `clear-all`. |
+| `state.py` | Per-session JSONL buffer at `~/.claude-smart/sessions/{session_id}.jsonl`; high-water mark for idempotent publish retries. |
+| `publish.py` | Drains the session buffer, calls the Reflexio adapter, and stamps the watermark. Used by Stop, SessionEnd, and `learn`. |
+| `reflexio_adapter.py` | Thin wrapper over `reflexio.ReflexioClient` — isolates import failures, 5s HTTP timeout, injects/queries learnings, degrades gracefully when the backend is down. |
+
+## Event Handlers (`events/`)
+
+| Handler | Hook | Role |
+|---------|------|------|
+| `session_start.py` | SessionStart | Apply extraction defaults, render stall banner, push optimizer context. |
+| `user_prompt.py` | UserPromptSubmit | Inject learned playbooks/preferences into context. |
+| `pre_tool.py` | PreToolUse (Edit/Write/Bash/NotebookEdit) | Inject project-specific context before tool execution. |
+| `post_tool.py` | PostToolUse | Buffer the tool invocation (name, input, response, duration) into session state. |
+| `stop.py` | Stop | Publish unpublished interactions (force extraction if configured). |
+| `session_end.py` | SessionEnd | Final publish + aggregation; optional backend/dashboard shutdown. |
+
+## Supporting Modules
+
+| File | Purpose |
+|------|---------|
+| `env_config.py` | Parses `~/.reflexio/.env` (`REFLEXIO_URL`, `REFLEXIO_API_KEY`, `CLAUDE_SMART_READ_ONLY`, local embedding/CLI flags). |
+| `runtime.py` | Host detection (Claude Code vs Codex); shared agent version. |
+| `ids.py` | Session / project ID generation and resolution. |
+| `context_inject.py`, `context_format.py`, `query_compose.py`, `cs_cite.py` | Build search queries, format learned skills as markdown, inject into context, format citations. |
+| `stall_banner.py` | User-facing message when the Reflexio provider hits an auth/billing stall. |
+| `optimizer_assistant.py` | Claude-code CLI agent that extracts Reflexio optimization hints. |
+| `hook_log.py`, `internal_call.py` | Structured JSON logging to `~/.claude-smart/hook.log`; detect internal/test invocations to skip learning. |
+
+## Architecture
+
+```
+SessionStart -> bootstrap Reflexio backend (8071) + Next.js dashboard (3001)
+PostToolUse  -> state.py buffers each tool call to ~/.claude-smart/sessions/{id}.jsonl
+Stop/SessionEnd -> publish.py -> reflexio_adapter -> Reflexio extracts playbooks + preferences
+UserPromptSubmit / PreToolUse -> context_inject pulls relevant learnings back into context
+```
+
+- **Dual-host** — the same package runs under Claude Code (native slash commands) and Codex (shell-script fallbacks in `../scripts/`); host shape is normalized in `runtime.py`.
+- **Offline-resilient** — if Reflexio is unreachable, interactions stay buffered and drain on the next successful publish.
+- **Hooks registered** in `../hooks/hooks.json` (Claude Code) and `../hooks/codex-hooks.json` (Codex), dispatched through `../scripts/hook_entry.sh`.
+
+## Requirements / Problems to Avoid
+
+- **All learned state is external to the repo** — sessions buffer under `~/.claude-smart/`, Reflexio state under `~/.reflexio/`. Don't write generated runtime artifacts inside the plugin root.
+- **Backend lives at `http://localhost:8071`**, dashboard at `http://localhost:3001`; both are long-lived across sessions (no hard shutdown on SessionEnd by default).
+- **`CLAUDE_SMART_READ_ONLY`** skips publishing entirely — respect it in any new publish path.
+- **Keep handlers fast** — tool-use hooks run on a 10–15s timeout; heavy work belongs in the backend, not the hook.