fix(plugins): hooks fall back to uvx/uv when no CLI binary is on PATH

Codex flagged (review 4397232451) that the hooks locate the CLI via
`command -v basic-memory || command -v bm`, but our own README recommends
connecting the MCP server as `claude mcp add basic-memory -- uvx basic-memory mcp`
— an ephemeral uv run that leaves NO binary on PATH. In that (recommended) setup
both hooks exited before doing anything, so the bridge silently did nothing even
though the MCP server worked.

Both hooks now resolve the CLI invocation as: prefer a `basic-memory`/`bm` binary
(fast), else fall back to `uvx basic-memory`, else `uv tool run basic-memory`, else
silent no-op. The launcher may be multi-token, so the embedded Python splits it with
shlex and prepends it to each command list. The uv cache is already warm from
running the MCP server, so the fallback is cheap.

Verified: with no binary on PATH but uvx present, SessionStart now produces a brief
(previously a silent no-op). Updated the README requirement to note uvx-only works.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

plugins/claude-code/README.md

@@ -46,7 +46,10 @@ Plugin skills are namespaced under the plugin name:
 ## Requirements
 
 - [Basic Memory](https://github.com/basicmachines-co/basic-memory) `>= 0.19.0`
-  installed and configured as an MCP server (`uv tool install basic-memory`).
+  connected as an MCP server. `uv tool install basic-memory` is recommended (it puts
+  a `basic-memory` binary on PATH, which the hooks call directly). A `uvx
+  basic-memory mcp`-only setup also works — the hooks fall back to `uvx`/`uv` when no
+  binary is on PATH.
 - Claude Code.
 
 ## Installation

plugins/claude-code/hooks/pre-compact.sh

@@ -19,18 +19,33 @@ set -u
 
 input="$(cat 2>/dev/null || true)"
 
-BM="$(command -v basic-memory || command -v bm || true)"
-[ -z "$BM" ] && exit 0
+# Resolve how to invoke the Basic Memory CLI — prefer a binary on PATH, fall back to
+# uvx / uv so checkpointing still works when BM was connected only as an ephemeral
+# `uvx basic-memory mcp` server (no persistent CLI). Silent no-op if none available.
+if command -v basic-memory >/dev/null 2>&1; then
+    BM="basic-memory"
+elif command -v bm >/dev/null 2>&1; then
+    BM="bm"
+elif command -v uvx >/dev/null 2>&1; then
+    BM="uvx basic-memory"
+elif command -v uv >/dev/null 2>&1; then
+    BM="uv tool run basic-memory"
+else
+    exit 0
+fi
 
 BM_HOOK_INPUT="$input" BM_BIN="$BM" python3 <<'PY' 2>/dev/null || exit 0
 import json
 import os
 import re
+import shlex
 import subprocess
 import sys
 from datetime import datetime
 
-bm = os.environ.get("BM_BIN", "basic-memory")
+# May be a single binary ("basic-memory") or a multi-token launcher
+# ("uvx basic-memory"); split so it prepends cleanly onto the write command.
+bm_cmd = shlex.split(os.environ.get("BM_BIN") or "basic-memory")
 
 # A project ref can be a workspace-qualified name (route via --project) or an
 # external_id UUID (route via --project-id) — names collide across workspaces, so
@@ -200,7 +215,7 @@ project_flag = "--project-id" if UUID_RE.match(primary_project) else "--project"
 try:
     subprocess.run(
         [
-            bm, "tool", "write-note",
+            *bm_cmd, "tool", "write-note",
             "--title", title,
             "--folder", capture_folder,
             project_flag, primary_project,

plugins/claude-code/hooks/session-start.sh

@@ -22,13 +22,24 @@ set -u
 # stdin can only be consumed once; capture it before anything else touches it.
 input="$(cat 2>/dev/null || true)"
 
-# --- Locate the Basic Memory CLI ---
-# Trigger: bm not installed / not on PATH.
-# Why: the plugin is useful on its own merits to BM users; for everyone else it
-#      must be invisible. No binary → no brief, no error.
-# Outcome: silent no-op.
-BM="$(command -v basic-memory || command -v bm || true)"
-[ -z "$BM" ] && exit 0
+# --- Resolve how to invoke the Basic Memory CLI ---
+# Prefer a binary on PATH (fast — no per-call env resolution). Fall back to uvx / uv
+# so the hook still works when Basic Memory was connected only as an ephemeral
+# `uvx basic-memory mcp` server (the MCP setup our README recommends) with no
+# persistent CLI installed — the uv cache is already warm from running the server.
+# Trigger: none of basic-memory / bm / uvx / uv on PATH → BM isn't usable here.
+# Outcome: silent no-op (the plugin must be invisible to non-BM users).
+if command -v basic-memory >/dev/null 2>&1; then
+    BM="basic-memory"
+elif command -v bm >/dev/null 2>&1; then
+    BM="bm"
+elif command -v uvx >/dev/null 2>&1; then
+    BM="uvx basic-memory"
+elif command -v uv >/dev/null 2>&1; then
+    BM="uv tool run basic-memory"
+else
+    exit 0
+fi
 
 # Everything else runs in one Python pass: parse config, run the queries, format
 # the brief. Python is a guaranteed dependency (basic-memory requires it) and
@@ -38,11 +49,14 @@ BM_HOOK_INPUT="$input" BM_BIN="$BM" python3 <<'PY' 2>/dev/null || exit 0
 import json
 import os
 import re
+import shlex
 import subprocess
 import sys
 from concurrent.futures import ThreadPoolExecutor
 
-bm = os.environ.get("BM_BIN", "basic-memory")
+# May be a single binary ("basic-memory") or a multi-token launcher
+# ("uvx basic-memory"); split so it prepends cleanly onto each command list.
+bm_cmd = shlex.split(os.environ.get("BM_BIN") or "basic-memory")
 
 # Cloud project refs come in two unambiguous forms (names collide across
 # workspaces, so a bare name won't route): a workspace-qualified name like
@@ -119,7 +133,7 @@ shared_refs = shared_refs[:MAX_SHARED]
 # project_ref=None routes to the user's default project (zero-config usefulness).
 # A UUID ref routes via --project-id; a qualified name via --project.
 def search(filters, project_ref=None, timeout=10):
-    cmd = [bm, "tool", "search-notes", *filters, "--page-size", "5"]
+    cmd = [*bm_cmd, "tool", "search-notes", *filters, "--page-size", "5"]
     if project_ref:
         flag = "--project-id" if UUID_RE.match(project_ref) else "--project"
         cmd += [flag, project_ref]