feat(claude): prefer workspace runtimes and poetry envs before global launchers

Author: orenlab

CHANGELOG.md

@@ -11,8 +11,11 @@
   projections.
 - Make baseline mismatch handling more explicit in MCP and the VS Code client by surfacing baseline/runtime python tags
   and whether comparison is proceeding without a valid baseline.
-- Make the Codex plugin prefer workspace-local launchers before `PATH`, with Poetry environment fallback for
+- Make the Claude Desktop bundle and Codex plugin prefer workspace-local launchers before `PATH`, with Poetry environment fallback for
   python-tag-safe MCP startup.
+- Add `workspace_root` user-config field to the Claude Desktop bundle: setting it to the project directory forces the
+  launcher to prefer `.venv` inside that path even when Claude Desktop starts with a different working directory
+  (fixes python-tag mismatch caused by system-wide interpreter fallback).
 - Refresh branch metadata and client docs for the `2.0.0b5` line.
 - Update the README repository health badge to `87 (B)`.
 

docs/book/22-claude-desktop-bundle.md

@@ -57,13 +57,14 @@ The wrapper:
 5. proxies stdio until shutdown
 
 The wrapper may auto-discover a few common global install locations, but it is
-primarily designed for:
+now prefers:
 
-- `codeclone-mcp` on `PATH`
+- a workspace-local `.venv`
+- the active Poetry environment for the current workspace
+- user-local install locations and `PATH`
 - or an explicit launcher command in bundle settings
 
-Repository-local virtual environments are intentionally outside the default
-bundle contract.
+This keeps the launcher closer to the active project Python when possible.
 
 ## Design rules
 

docs/claude-desktop-bundle.md

@@ -10,16 +10,30 @@ production-first structural review.
 
 ## Install
 
+The bundle prefers the current workspace launcher first:
+
+1. `./.venv/bin/codeclone-mcp`
+2. the current Poetry environment launcher
+3. user-local install paths and `PATH`
+
+```bash
+uv venv
+uv pip install --python .venv/bin/python "codeclone[mcp]>=2.0.0b4"
+.venv/bin/codeclone-mcp --help
+```
+
+Global fallback:
+
 ```bash
-uv tool install --pre "codeclone[mcp]"    # or: uv pip install --pre "codeclone[mcp]"
-codeclone-mcp --help                # verify
+uv tool install "codeclone[mcp]>=2.0.0b4"
+codeclone-mcp --help
 ```
 
 ## Bundle workflow
 
 1. Build: `cd extensions/claude-desktop-codeclone && node scripts/build-mcpb.mjs`
 2. Claude Desktop: **Settings → Extensions → Install Extension** → select `.mcpb`
-3. If `codeclone-mcp` is not on `PATH`, set **CodeClone launcher command** in
+3. If you want to bypass auto-discovery, set **CodeClone launcher command** in
    the bundle settings to an absolute path.
 
 ## Settings
@@ -31,9 +45,9 @@ codeclone-mcp --help                # verify
 
 ## Runtime model
 
-Node wrapper launches `codeclone-mcp` via local `stdio`. Auto-discovers the
-launcher in `~/.local/bin`, macOS `~/Library/Python/*/bin`, or Windows Python
-paths. Falls back to `PATH`.
+Node wrapper launches `codeclone-mcp` via local `stdio`. It prefers a
+workspace-local `.venv`, then a Poetry environment, then user-local install
+paths, then `PATH`.
 
 ## Privacy
 
@@ -42,7 +56,8 @@ See [Privacy Policy](privacy-policy.md).
 
 ## Current limits
 
-- expects a global or explicitly configured launcher
+- expects either a workspace launcher, a user-local/global launcher, or an
+  explicitly configured absolute launcher path
 - local install surface, not a hosted service layer
 
 For the underlying MCP contract, see:

extensions/claude-desktop-codeclone/README.md

@@ -8,15 +8,25 @@ Read-only, baseline-aware, local stdio only.
 
 ## Install
 
+The bundle prefers the current workspace launcher first:
+
+1. `./.venv/bin/codeclone-mcp`
+2. the current Poetry environment launcher
+3. user-local install paths and `PATH`
+
+Recommended workspace-local setup:
+
 ```bash
-uv tool install --pre "codeclone[mcp]"
-codeclone-mcp --help                       # verify launcher
+uv venv
+uv pip install --python .venv/bin/python "codeclone[mcp]>=2.0.0b4"
+.venv/bin/codeclone-mcp --help
 ```
 
-If you want to keep the launcher inside an existing environment instead, use:
+Global fallback:
 
 ```bash
-uv pip install --pre "codeclone[mcp]"
+uv tool install "codeclone[mcp]>=2.0.0b4"
+codeclone-mcp --help
 ```
 
 Build and install the bundle:
@@ -29,8 +39,8 @@ node scripts/build-mcpb.mjs
 Then in Claude Desktop: **Settings → Extensions → Install Extension** → select
 the `.mcpb` from `dist/`.
 
-If `codeclone-mcp` is not on `PATH`, set **CodeClone launcher command** in the
-extension settings to an absolute path.
+If you want to bypass auto-discovery entirely, set **CodeClone launcher
+command** in the extension settings to an absolute path.
 
 ## Configuration
 

extensions/claude-desktop-codeclone/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "codeclone",
   "display_name": "CodeClone",
-  "version": "2.0.0-b5.0",
+  "version": "2.0.0-b5.1",
   "description": "Baseline-aware structural review for Claude Desktop through a local CodeClone MCP launcher.",
   "long_description": "CodeClone for Claude Desktop wraps the local codeclone-mcp launcher as an MCP bundle. It keeps Claude on the same canonical MCP surface used by the CLI, HTML report, VS Code extension, and Codex plugin — read-only, baseline-aware, local stdio only.",
   "author": {
@@ -98,15 +98,22 @@
       ],
       "env": {
         "CODECLONE_MCP_COMMAND": "${user_config.launcher_command}",
-        "CODECLONE_MCP_ARGS_JSON": "${user_config.launcher_args_json}"
+        "CODECLONE_MCP_ARGS_JSON": "${user_config.launcher_args_json}",
+        "CODECLONE_WORKSPACE_ROOT": "${user_config.workspace_root}"
       }
     }
   },
   "user_config": {
+    "workspace_root": {
+      "type": "string",
+      "title": "Workspace root path",
+      "description": "Optional absolute path to the Python project root (the directory that contains .venv or venv). When set, the launcher prefers that virtual environment over user-local or system-wide installs. Useful when Claude Desktop starts outside the project directory.",
+      "required": false
+    },
     "launcher_command": {
       "type": "string",
       "title": "CodeClone launcher command",
-      "description": "Optional absolute path or bare command name for codeclone-mcp. Leave empty to use auto-discovery and PATH.",
+      "description": "Optional absolute path or bare command name for codeclone-mcp. Leave empty to prefer workspace launchers, then user-local paths, then PATH.",
       "required": false
     },
     "launcher_args_json": {

extensions/claude-desktop-codeclone/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@orenlab/codeclone-claude-desktop",
-  "version": "2.0.0-b5.0",
+  "version": "2.0.0-b5.1",
   "private": true,
   "description": "Claude Desktop MCP bundle wrapper for the local CodeClone MCP launcher.",
   "license": "MPL-2.0",