xmux-bridge 1.0.40 → 1.2.0

package/README.md

@@ -24,11 +24,6 @@ brew tap DwvN-Lee/xmux
 brew install xmux
 ```
 
-Homebrew owns the stable runtime under `$(brew --prefix)/opt/xmux/libexec`.
-The installed `xmux` command exports that path as `XMUX_INSTALL_DIR` and then
-execs the runtime wrapper in `libexec/bin/xmux`. Ad hoc local directories, npx
-caches, and zsh plugin directories are not part of the normal runtime path.
-
 Configure Codex integration explicitly:
 
 ```bash
@@ -36,21 +31,8 @@ xmux setup-codex
 xmux doctor-codex
 ```
 
-Homebrew installs the XMux CLI/runtime only. `xmux setup-codex` is the command
-that mutates `~/.codex`: it registers the `xmux_lead` MCP server through the
-versioned npm package, points that MCP runtime back at Homebrew with
-`XMUX_INSTALL_DIR`, adds the installed `xmux` path to Codex shell policy,
-installs the scoped XMux command rule, and refreshes available XMux skills
-under `~/.codex/skills`. Runtime-only installs do not include skill source
-files, so pass an external skill source when refreshing skills:
-
-```bash
-xmux setup-codex --skills-dir /path/to/xmux-skills
-```
-
-`XMUX_CODEX_SKILLS_DIR` provides the same source path for automation. Without
-`--skills-dir` or `XMUX_CODEX_SKILLS_DIR`, `setup-codex` skips skill refresh
-and leaves existing user-owned skills untouched.
+`xmux setup-codex` registers XMux with Codex, and `xmux doctor-codex` checks
+that the integration is ready.
 
 Start the Codex lead from the target project directory:
 
@@ -148,7 +130,7 @@ Runtime state is project-local:
 Runtime path environment names are now split by responsibility:
 
 ```text
-XMUX_INSTALL_DIR  # XMux source/install directory
+XMUX_INSTALL_DIR  # XMux install root
 XMUX_PROJECT_DIR  # project root where Codex is working
 XMUX_STATE_DIR    # project-local runtime state, usually $XMUX_PROJECT_DIR/.codex/xmux
 ```
@@ -156,36 +138,26 @@ XMUX_STATE_DIR    # project-local runtime state, usually $XMUX_PROJECT_DIR/.code
 Codex uses the normal user runtime under `~/.codex`. XMux does not create an
 isolated Codex home for a team, and Codex teammate mode is unsupported.
 
-Agent automation uses `xmux` from the Codex shell policy PATH that
-`xmux setup-codex` writes to `~/.codex/config.toml`. If that wrapper is
-unavailable, it falls back to the explicit XMux executable. The user-facing
-bootstrap command remains `xmux -n <session>` after setup; ad hoc local paths
-and shell-loading details are not part of the agent contract.
+Agent automation uses the installed `xmux` command that `xmux setup-codex`
+makes available to Codex. The user-facing bootstrap command remains
+`xmux -n <session>` after setup.
 
 The Codex lead MCP server is `xmux_lead`. `xmux setup-codex` configures it so
 Codex can route requests, wait for teammate responses, read events, and inspect
 team status.
-The global MCP config is install-scoped: the MCP command is a versioned npm
-entrypoint launched with a project-neutral `npx --prefix`, while
-`XMUX_INSTALL_DIR` points at the Homebrew runtime that owns wrapper scripts,
-state discovery, and lifecycle. It does not pin
-`XMUX_PROJECT_DIR`/`XMUX_STATE_DIR`; those values come from the active
-`xmux -n <session>` lead runtime.
-
-Provider teammates write responses through `bridge-mcp-server.js`, using the
-team runtime environment prepared by XMux. The bridge and mailbox paths are
-implementation details behind Codex-led teammate orchestration.
-
-The explicit Codex setup installs available XMux skills under
-`~/.codex/skills` only from `--skills-dir` or `XMUX_CODEX_SKILLS_DIR`.
-Homebrew does not install Codex skills or repo-local plugin files; normal
-runtime operation depends on the installed `xmux` command and
-`XMUX_INSTALL_DIR`, not a checkout path.
-
-The plugin skill source of truth is `plugins/xmux/skills`; the top-level
-`skills/` directory is a mirrored distribution copy for explicit skill refresh
-workflows. Users explicitly invoke Codex skills with `$`, for example
-`$xmux-teams`. The official XMux skills cover agent-facing orchestration flows:
+The installed `xmux` command owns the tmux runtime. The `xmux_lead` MCP server
+is delivered as a versioned npm entrypoint, and Codex skills are optional
+shortcuts for orchestrating that runtime. The MCP command is install-scoped and
+does not pin `XMUX_PROJECT_DIR`/`XMUX_STATE_DIR`; those values come from the
+active `xmux -n <session>` lead runtime.
+
+Provider teammates write responses through the versioned npm `xmux-bridge`
+entrypoint, using the team runtime environment prepared by XMux. MCP and
+mailbox paths are implementation details behind Codex-led teammate
+orchestration.
+
+Users can ask for teammate work in natural language. When XMux skills are
+available in Codex, the official skill shortcuts are:
 
 ```text
 $xmux-teams
@@ -196,22 +168,14 @@ $xmux-diagnosis
 $xmux-send-pane
 ```
 
-Development verification for agent/runtime changes:
-
-```bash
-zsh -n xmux.zsh
-zsh -n xmux-bridge.zsh
-node --check scripts/setup_xmux_codex_mcp.js
-git diff --check
-```
-
-Homebrew distribution notes live in [Homebrew distribution](docs/operations/homebrew.md).
+Homebrew installation details live in [Homebrew installation](docs/operations/homebrew.md).
 
 ## Docs
 
 - [Documentation index](docs/README.md)
+- [Repository layout](docs/runtime/repository-layout.md)
 - [Codex lead runtime](docs/runtime/codex-lead.md)
-- [Homebrew distribution](docs/operations/homebrew.md)
+- [Homebrew installation](docs/operations/homebrew.md)
 - [Wrapper-first debugging](docs/operations/debugging.md)
 - [Claude teammate](docs/teammates/claude.md)
 - [Gemini teammate](docs/teammates/gemini.md)

package/{bridge-mcp-server.js → mcp/servers/bridge.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * bridge-mcp-server.js
+ * mcp/servers/bridge.js
  * Minimal MCP server for xmux.
  * Exposes write_to_lead(text, summary?) so Claude, Gemini, and Copilot
  * teammates can write directly to the XMux lead inbox.
@@ -140,7 +140,11 @@ function trimToCap(msgs, cap) {
 function mailboxInstallBases() {
   const seen = new Set();
   const bases = [];
-  for (const candidate of [XMUX_INSTALL_DIR, __dirname]) {
+  const packageRoot = path.basename(__dirname) === 'servers'
+    && path.basename(path.dirname(__dirname)) === 'mcp'
+    ? path.dirname(path.dirname(__dirname))
+    : __dirname;
+  for (const candidate of [XMUX_INSTALL_DIR, packageRoot, __dirname]) {
     if (!candidate) continue;
     const resolved = path.resolve(candidate);
     if (seen.has(resolved)) continue;

package/{xmux-lead-mcp-server.js → mcp/servers/lead.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * xmux-lead-mcp-server.js
+ * mcp/servers/lead.js
  * Stdio-only MCP server exposing XMux lead/team mailbox tools.
  *
  * Mailbox persistence is delegated to the Node mailbox CLI.
@@ -138,7 +138,11 @@ function parseJsonOutput(stdout) {
 function mailboxInstallBases() {
   const seen = new Set();
   const bases = [];
-  for (const candidate of [XMUX_INSTALL_DIR, __dirname]) {
+  const packageRoot = path.basename(__dirname) === 'servers'
+    && path.basename(path.dirname(__dirname)) === 'mcp'
+    ? path.dirname(path.dirname(__dirname))
+    : __dirname;
+  for (const candidate of [XMUX_INSTALL_DIR, packageRoot, __dirname]) {
     if (!candidate) continue;
     const resolved = path.resolve(candidate);
     if (seen.has(resolved)) continue;

package/{scripts/setup_claude_mcp.js → mcp/setup/claude.js}

@@ -6,6 +6,8 @@ const os = require("node:os");
 const path = require("node:path");
 
 const SERVER_NAME = "xmux_bridge";
+const DEFAULT_NPM_PACKAGE = "xmux-bridge";
+const DEFAULT_NPX_PREFIX = path.join(os.homedir(), ".cache", "xmux", "npm-prefix");
 const LEGACY_NAMES = new Set([
   "xmux_bridge",
   "xmux-bridge",
@@ -28,7 +30,7 @@ function stableHomebrewXmuxInstallDir(installDir) {
 
   const prefix = resolved.split(marker, 1)[0];
   const candidate = path.join(prefix, "opt", "xmux", "libexec");
-  if (fs.existsSync(path.join(candidate, "xmux.zsh"))) {
+  if (fs.existsSync(path.join(candidate, "runtime", "shell", "xmux.zsh")) || fs.existsSync(path.join(candidate, "xmux.zsh"))) {
     return candidate;
   }
   return resolved;
@@ -36,13 +38,14 @@ function stableHomebrewXmuxInstallDir(installDir) {
 
 function stableHomebrewXmuxFilePath(filePath) {
   const resolved = absolute(filePath);
-  const installDir = path.dirname(resolved);
-  const stableInstallDir = stableHomebrewXmuxInstallDir(installDir);
-  if (stableInstallDir === installDir) {
-    return resolved;
-  }
-
-  const candidate = path.join(stableInstallDir, path.basename(resolved));
+  const marker = `${path.sep}Cellar${path.sep}xmux${path.sep}`;
+  const libexecSegment = `${path.sep}libexec${path.sep}`;
+  const libexecIndex = resolved.indexOf(libexecSegment);
+  if (!resolved.includes(marker) || libexecIndex < 0) return resolved;
+  const prefix = resolved.split(marker, 1)[0];
+  const optDir = path.join(prefix, "opt", "xmux", "libexec");
+  const relativePath = resolved.slice(libexecIndex + libexecSegment.length);
+  const candidate = path.join(optDir, relativePath);
   if (fs.existsSync(candidate)) {
     return candidate;
   }
@@ -72,7 +75,7 @@ function atomicWriteJson(filePath, data) {
 
 function usage() {
   process.stderr.write(
-    "usage: setup_claude_mcp.js <bridge_js> <project_dir> <outbox> <agent> <team> <state_dir> <install_dir>\n",
+    "usage: claude.js <bridge_js|npx> <project_dir> <outbox> <agent> <team> <state_dir> <install_dir>\n",
   );
 }
 
@@ -82,7 +85,8 @@ function main(argv = process.argv.slice(2)) {
     return 2;
   }
 
-  const bridgeJs = stableHomebrewXmuxFilePath(argv[0]);
+  const bridgeRef = argv[0];
+  const bridgeJs = bridgeRef === "npx" ? "" : stableHomebrewXmuxFilePath(bridgeRef);
   const projectDir = absolute(argv[1]);
   const outbox = absolute(argv[2]);
   const agent = argv[3];
@@ -115,20 +119,41 @@ function main(argv = process.argv.slice(2)) {
     delete servers[legacyName];
   }
 
-  servers[SERVER_NAME] = {
-    type: "stdio",
-    command: "node",
-    args: [bridgeJs, "--outbox", outbox, "--agent", agent, "--team", team],
-    env: {
-      XMUX_AGENT: agent,
-      XMUX_INSTALL_DIR: installDir,
-      XMUX_OUTBOX: outbox,
-      XMUX_PROJECT_DIR: projectDir,
-      XMUX_STATE_DIR: stateDir,
-      XMUX_TEAM: team,
-    },
+  const commonEnv = {
+    XMUX_AGENT: agent,
+    XMUX_INSTALL_DIR: installDir,
+    XMUX_OUTBOX: outbox,
+    XMUX_PROJECT_DIR: projectDir,
+    XMUX_STATE_DIR: stateDir,
+    XMUX_TEAM: team,
   };
 
+  if (bridgeRef === "npx") {
+    const packageSpec = process.env.XMUX_MCP_PACKAGE_SPEC || DEFAULT_NPM_PACKAGE;
+    const npxPrefix = process.env.XMUX_MCP_NPX_PREFIX || DEFAULT_NPX_PREFIX;
+    servers[SERVER_NAME] = {
+      type: "stdio",
+      command: "npx",
+      args: [
+        "--prefix", npxPrefix,
+        "-y",
+        "-p", packageSpec,
+        "xmux-bridge",
+        "--outbox", outbox,
+        "--agent", agent,
+        "--team", team,
+      ],
+      env: commonEnv,
+    };
+  } else {
+    servers[SERVER_NAME] = {
+      type: "stdio",
+      command: "node",
+      args: [bridgeJs, "--outbox", outbox, "--agent", agent, "--team", team],
+      env: commonEnv,
+    };
+  }
+
   atomicWriteJson(configPath, config);
   return 0;
 }

package/{scripts/setup_xmux_codex_mcp.js → mcp/setup/codex.js}

@@ -32,26 +32,39 @@ function abs(value) {
   return path.resolve(expandUser(value));
 }
 
+function xmux_runtime_shell_path(installDir) {
+  return path.join(abs(installDir), "runtime", "shell", "xmux.zsh");
+}
+
+function has_xmux_runtime(installDir) {
+  const root = abs(installDir);
+  return fs.existsSync(xmux_runtime_shell_path(root)) || fs.existsSync(path.join(root, "xmux.zsh"));
+}
+
 function stable_homebrew_xmux_install_dir(xmuxInstallDir) {
   const installDir = abs(xmuxInstallDir);
   const marker = `${path.sep}Cellar${path.sep}xmux${path.sep}`;
   if (!installDir.includes(marker) || !installDir.endsWith(`${path.sep}libexec`)) {
     return installDir;
   }
-  if (!fs.existsSync(path.join(installDir, "xmux.zsh"))) {
+  if (!has_xmux_runtime(installDir)) {
     return installDir;
   }
   const prefix = installDir.split(marker, 1)[0];
   const candidate = path.join(prefix, "opt", "xmux", "libexec");
-  return fs.existsSync(path.join(candidate, "xmux.zsh")) ? candidate : installDir;
+  return has_xmux_runtime(candidate) ? candidate : installDir;
 }
 
 function stable_homebrew_xmux_file_path(inputPath) {
   const resolved = abs(inputPath);
-  const installDir = path.dirname(resolved);
-  const stableInstallDir = stable_homebrew_xmux_install_dir(installDir);
-  if (stableInstallDir === installDir) return resolved;
-  const candidate = path.join(stableInstallDir, path.basename(resolved));
+  const marker = `${path.sep}Cellar${path.sep}xmux${path.sep}`;
+  const libexecSegment = `${path.sep}libexec${path.sep}`;
+  const libexecIndex = resolved.indexOf(libexecSegment);
+  if (!resolved.includes(marker) || libexecIndex < 0) return resolved;
+  const prefix = resolved.split(marker, 1)[0];
+  const optDir = path.join(prefix, "opt", "xmux", "libexec");
+  const relativePath = resolved.slice(libexecIndex + libexecSegment.length);
+  const candidate = path.join(optDir, relativePath);
   return fs.existsSync(candidate) ? candidate : resolved;
 }
 
@@ -138,15 +151,30 @@ function package_spec_has_version(packageSpec) {
   return text.includes("@");
 }
 
+function package_name_from_spec(packageSpec) {
+  const text = String(packageSpec || "");
+  if (text.startsWith("@")) {
+    const slash = text.indexOf("/");
+    if (slash < 0) return text;
+    const scope = text.slice(0, slash);
+    const rest = text.slice(slash + 1);
+    const versionIndex = rest.indexOf("@");
+    return `${scope}/${versionIndex < 0 ? rest : rest.slice(0, versionIndex)}`;
+  }
+  const versionIndex = text.indexOf("@");
+  return versionIndex < 0 ? text : text.slice(0, versionIndex);
+}
+
 function xmux_version_from_install_dir(xmuxInstallDir) {
-  const content = read_text(path.join(abs(xmuxInstallDir), "xmux.zsh"));
+  const root = abs(xmuxInstallDir);
+  const content = read_text(xmux_runtime_shell_path(root)) || read_text(path.join(root, "xmux.zsh"));
   const match = content.match(/^XMUX_VERSION=["']([^"']+)["']/m);
   return match ? match[1] : "";
 }
 
 function default_mcp_package_spec(xmuxInstallDir, packageName = "", packageVersion = "") {
   const installPackage = read_json(path.join(abs(xmuxInstallDir), "package.json")) || {};
-  const scriptPackage = read_json(path.join(path.dirname(path.dirname(abs(__filename))), "package.json")) || {};
+  const scriptPackage = read_json(path.join(path.dirname(path.dirname(path.dirname(abs(__filename)))), "package.json")) || {};
   const name = packageName
     || process.env.XMUX_MCP_NPM_PACKAGE
     || installPackage.name
@@ -232,6 +260,70 @@ function ensure_mcp_runtime_dirs(mcpConfig) {
   }
 }
 
+function cached_package_root(mcpConfig) {
+  if (!mcpConfig || !mcpConfig.npx_prefix || !mcpConfig.package_spec) return "";
+  return path.join(abs(mcpConfig.npx_prefix), "node_modules", package_name_from_spec(mcpConfig.package_spec));
+}
+
+function cached_mailbox_candidates(mcpConfig) {
+  const prefix = mcpConfig && mcpConfig.npx_prefix ? abs(mcpConfig.npx_prefix) : "";
+  const root = cached_package_root(mcpConfig);
+  return [
+    prefix ? path.join(prefix, "node_modules", ".bin", "xmux-mailbox") : "",
+    root ? path.join(root, "dist", "bin", "xmux-mailbox.js") : "",
+  ].filter(Boolean);
+}
+
+function mailbox_source(xmuxInstallDir, mcpConfig) {
+  const explicit = process.env.XMUX_MAILBOX_NODE_CLI ? abs(process.env.XMUX_MAILBOX_NODE_CLI) : "";
+  if (explicit && fs.existsSync(explicit)) return { ok: true, kind: "env", label: explicit };
+
+  for (const candidate of cached_mailbox_candidates(mcpConfig)) {
+    if (fs.existsSync(candidate)) return { ok: true, kind: "npm-cache", label: candidate };
+  }
+
+  const bundled = path.join(abs(xmuxInstallDir), "dist", "bin", "xmux-mailbox.js");
+  if (fs.existsSync(bundled)) return { ok: true, kind: "brew-bundled", label: bundled };
+
+  const npx = spawnSync("npx", ["--version"], { encoding: "utf8" });
+  if (npx.status === 0 && mcpConfig && mcpConfig.mode === "npx" && mcpConfig.package_spec) {
+    return { ok: true, kind: "npx", label: `${mcpConfig.package_spec} via ${mcpConfig.npx_prefix}` };
+  }
+
+  return { ok: false, kind: "missing", label: "no mailbox CLI source found" };
+}
+
+function ensure_mcp_package_cache(mcpConfig, enabled = true) {
+  if (!enabled || !mcpConfig || mcpConfig.mode !== "npx") {
+    return { status: "skipped", message: "disabled" };
+  }
+  if (!mcpConfig.npx_prefix || !mcpConfig.package_spec) {
+    return { status: "skipped", message: "missing npx package metadata" };
+  }
+  ensure_mcp_runtime_dirs(mcpConfig);
+
+  const root = cached_package_root(mcpConfig);
+  if (root && fs.existsSync(root)) {
+    return { status: "ok", message: `using existing cache at ${root}` };
+  }
+
+  const npm = spawnSync("npm", [
+    "install",
+    "--prefix",
+    abs(mcpConfig.npx_prefix),
+    "--no-save",
+    "--omit=dev",
+    mcpConfig.package_spec,
+  ], { encoding: "utf8" });
+
+  if (npm.status === 0) {
+    return { status: "ok", message: `installed ${mcpConfig.package_spec} under ${mcpConfig.npx_prefix}` };
+  }
+
+  const detail = (npm.stderr || npm.stdout || "").trim().split(/\r?\n/).slice(-2).join(" ");
+  return { status: "failed", message: detail || `npm install exited with ${npm.status}` };
+}
+
 function build_block(mcpConfigOrServerPath, xmuxInstallDir) {
   const mcpConfig = normalize_mcp_config(mcpConfigOrServerPath, xmuxInstallDir);
   const pathEnv = resolve_path_with_node();
@@ -272,7 +364,7 @@ function is_xmux_runtime_bin_path(candidatePath, currentXmuxBin) {
   if (expanded === abs(currentXmuxBin)) return true;
   if (path.basename(expanded) !== "bin") return false;
   const installDir = path.dirname(expanded);
-  if (fs.existsSync(path.join(installDir, "xmux.zsh")) && fs.existsSync(path.join(expanded, "xmux"))) {
+  if (has_xmux_runtime(installDir) && fs.existsSync(path.join(expanded, "xmux"))) {
     return true;
   }
   if (path.basename(installDir) !== "libexec") return false;
@@ -419,7 +511,7 @@ function install_xmux_command_rule(configPath) {
   let content = remove_marker_block(read_text(filePath), RULE_BEGIN, RULE_END);
   const block = [
     RULE_BEGIN,
-    "# Allow the scoped XMux wrapper command; XMux skills still control operation scope.",
+    "# Allow the scoped XMux wrapper command; user intent and XMux wrappers control operation scope.",
     'prefix_rule(pattern=["xmux"], decision="allow")',
     RULE_END,
   ].join("\n");
@@ -568,12 +660,12 @@ function _xmux_lead_mcp_processes_from_ps(psOutput) {
   const processes = [];
   for (const rawLine of String(psOutput || "").split(/\r?\n/)) {
     const stripped = rawLine.trim();
-    if (!stripped.includes("xmux-lead-mcp-server.js")) continue;
+    if (!stripped.includes("mcp/servers/lead.js") && !stripped.includes("xmux-lead-mcp-server.js")) continue;
     const match = stripped.match(/^(\d+)\s+(.*)$/);
     if (!match) continue;
     const [, pid, command] = match;
     const tokens = splitShellWords(command.trim());
-    const serverPath = tokens.find((token) => token.endsWith("xmux-lead-mcp-server.js")) || "";
+    const serverPath = tokens.find((token) => token.endsWith("mcp/servers/lead.js") || token.endsWith("xmux-lead-mcp-server.js")) || "";
     if (!serverPath) continue;
     processes.push({ pid, command: command.trim(), server_path: abs(serverPath) });
   }
@@ -591,7 +683,7 @@ function running_xmux_lead_mcp_processes() {
 
 function _is_homebrew_xmux_mcp_server(serverPath) {
   const normalized = abs(serverPath);
-  return normalized.endsWith("xmux-lead-mcp-server.js")
+  return (normalized.endsWith(`${path.sep}mcp${path.sep}servers${path.sep}lead.js`) || normalized.endsWith("xmux-lead-mcp-server.js"))
     && normalized.includes(`${path.sep}Cellar${path.sep}xmux${path.sep}`)
     && normalized.includes(`${path.sep}libexec${path.sep}`);
 }
@@ -636,7 +728,7 @@ function doctor_codex(configPath, xmuxInstallDir, mcpConfigOrServerPath, skillsD
   } else if (installedNames.size) {
     notes.push(["OK", `XMux Codex skills installed under ${skills_root(configPath)}`]);
   } else {
-    notes.push(["WARN", "no XMux skill source directory found; pass --skills-dir or set XMUX_CODEX_SKILLS_DIR"]);
+    notes.push(["OK", "optional XMux skills are not configured"]);
   }
 
   if (fs.existsSync(plugin_cache_path(configPath))) {
@@ -645,6 +737,10 @@ function doctor_codex(configPath, xmuxInstallDir, mcpConfigOrServerPath, skillsD
     notes.push(["OK", "legacy XMux plugin cache is absent"]);
   }
 
+  const mailbox = mailbox_source(xmuxInstallDir, mcpConfig);
+  if (mailbox.ok) notes.push(["OK", `mailbox source: ${mailbox.kind} (${mailbox.label})`]);
+  else issues.push(`mailbox source is unavailable: ${mailbox.label}`);
+
   const staleProcesses = stale_xmux_lead_mcp_processes(mcpConfig);
   for (const proc of staleProcesses.slice(0, 5)) {
     notes.push([
@@ -686,6 +782,7 @@ function parse_args(argv) {
     mcp_version: "",
     mcp_bin: DEFAULT_MCP_BIN,
     mcp_npx_prefix: "",
+    cache_mcp: true,
   };
   for (let i = 0; i < argv.length;) {
     const arg = argv[i];
@@ -697,6 +794,10 @@ function parse_args(argv) {
       opts.quiet = true; i += 1;
     } else if (arg === "--without-skills") {
       opts.install_skills = false; i += 1;
+    } else if (arg === "--cache-mcp") {
+      opts.cache_mcp = true; i += 1;
+    } else if (arg === "--no-cache-mcp") {
+      opts.cache_mcp = false; i += 1;
     } else if ([
       "--skills-dir",
       "--home",
@@ -748,7 +849,7 @@ function main(argv = process.argv.slice(2)) {
   const opts = parse_args(argv);
   const configPath = resolve_config_path(opts);
   opts.mcp_npx_prefix = abs(opts.mcp_npx_prefix || process.env.XMUX_MCP_NPX_PREFIX || default_mcp_npx_prefix(configPath));
-  const scriptInstallDir = path.dirname(path.dirname(abs(__filename)));
+  const scriptInstallDir = path.dirname(path.dirname(path.dirname(abs(__filename))));
   const rawInstallDir = abs(opts.xmux_install_dir || scriptInstallDir);
   const xmuxInstallDir = stable_homebrew_xmux_install_dir(rawInstallDir);
   const xmuxProjectDir = abs(opts.xmux_project_dir || default_xmux_project_dir());
@@ -760,6 +861,10 @@ function main(argv = process.argv.slice(2)) {
   }
 
   ensure_mcp_runtime_dirs(mcpConfig);
+  const cacheResult = ensure_mcp_package_cache(mcpConfig, opts.cache_mcp);
+  if (cacheResult.status === "failed") {
+    console.error(`[WARN] XMux MCP package cache failed: ${cacheResult.message}`);
+  }
 
   let content = remove_xmux_blocks(read_text(configPath));
   if (opts.remove) {
@@ -791,11 +896,15 @@ function main(argv = process.argv.slice(2)) {
 
   console.log(`[OK] Wrote ${SERVER_NAME} to ${configPath}`);
   console.log(`     mcp: ${mcpConfig.label}`);
+  if (cacheResult.status === "ok") console.log(`     mcp_cache: ${cacheResult.message}`);
+  else if (cacheResult.status === "skipped") console.log(`     mcp_cache: ${cacheResult.message}`);
   console.log(`     xmux_install_dir: ${xmuxInstallDir}`);
   console.log("     xmux_project_dir: inherited from xmux-launched Codex runtime");
   console.log("     xmux_state_dir: inherited from xmux-launched Codex runtime");
   if (installedSkills.length) console.log(`     skills: ${installedSkills.join(", ")}`);
-  else if (opts.install_skills) console.log("     skills: skipped; pass --skills-dir or set XMUX_CODEX_SKILLS_DIR");
+  else if (opts.install_skills && (opts.skills_dir || process.env.XMUX_CODEX_SKILLS_DIR)) {
+    console.log("     skills: no importable XMux skills found");
+  }
   console.log("     plugin_cache: disabled; stale XMux plugin cache removed if present");
   return 0;
 }
@@ -814,6 +923,7 @@ module.exports = {
   build_block,
   default_mcp_package_spec,
   default_mcp_npx_prefix,
+  mailbox_source,
   resolve_mcp_config,
   path_with_xmux_bin,
   ensure_codex_shell_environment,

package/{scripts/setup_copilot_mcp.js → mcp/setup/copilot.js}

@@ -6,6 +6,8 @@ const os = require("node:os");
 const path = require("node:path");
 
 const SERVER_NAME = "xmux_bridge";
+const DEFAULT_NPM_PACKAGE = "xmux-bridge";
+const DEFAULT_NPX_PREFIX = path.join(os.homedir(), ".cache", "xmux", "npm-prefix");
 const LEGACY_NAMES = new Set([
   "xmux_bridge",
   "xmux-bridge",
@@ -18,16 +20,15 @@ const TOOLS = ["write_to_lead"];
 
 function stableHomebrewXmuxFilePath(inputPath) {
   const resolved = path.resolve(inputPath.replace(/^~(?=$|\/)/, os.homedir()));
-  const installDir = path.dirname(resolved);
   const marker = `${path.sep}Cellar${path.sep}xmux${path.sep}`;
-  if (!installDir.includes(marker) || !installDir.endsWith(`${path.sep}libexec`)) {
-    return resolved;
-  }
-
-  const prefix = installDir.split(marker, 1)[0];
+  const libexecSegment = `${path.sep}libexec${path.sep}`;
+  const libexecIndex = resolved.indexOf(libexecSegment);
+  if (!resolved.includes(marker) || libexecIndex < 0) return resolved;
+  const prefix = resolved.split(marker, 1)[0];
   const optDir = path.join(prefix, "opt", "xmux", "libexec");
-  const candidate = path.join(optDir, path.basename(resolved));
-  if (fs.existsSync(path.join(optDir, "xmux.zsh")) && fs.existsSync(candidate)) {
+  const relativePath = resolved.slice(libexecIndex + libexecSegment.length);
+  const candidate = path.join(optDir, relativePath);
+  if ((fs.existsSync(path.join(optDir, "runtime", "shell", "xmux.zsh")) || fs.existsSync(path.join(optDir, "xmux.zsh"))) && fs.existsSync(candidate)) {
     return candidate;
   }
   return resolved;
@@ -58,7 +59,13 @@ function main(argv = process.argv.slice(2)) {
   if (cmd.startsWith("http")) {
     servers[SERVER_NAME] = { type: "sse", url: cmd, tools: TOOLS };
   } else if (cmd === "npx") {
-    servers[SERVER_NAME] = { command: "npx", args: ["-y", "xmux-bridge"], tools: TOOLS };
+    const packageSpec = process.env.XMUX_MCP_PACKAGE_SPEC || DEFAULT_NPM_PACKAGE;
+    const npxPrefix = process.env.XMUX_MCP_NPX_PREFIX || DEFAULT_NPX_PREFIX;
+    servers[SERVER_NAME] = {
+      command: "npx",
+      args: ["--prefix", npxPrefix, "-y", "-p", packageSpec, "xmux-bridge"],
+      tools: TOOLS,
+    };
   } else {
     servers[SERVER_NAME] = {
       command: "node",

package/{scripts/setup_gemini_mcp.js → mcp/setup/gemini.js}

@@ -14,20 +14,20 @@ const LEGACY_NAMES = new Set([
   "amux_bridge",
   "amux-bridge",
 ]);
-const NPM_PIN = "xmux-bridge@^1.3.0";
+const DEFAULT_NPM_PACKAGE = "xmux-bridge";
+const DEFAULT_NPX_PREFIX = path.join(os.homedir(), ".cache", "xmux", "npm-prefix");
 
 function stableHomebrewXmuxFilePath(inputPath) {
   const resolved = path.resolve(inputPath.replace(/^~(?=$|\/)/, os.homedir()));
-  const installDir = path.dirname(resolved);
   const marker = `${path.sep}Cellar${path.sep}xmux${path.sep}`;
-  if (!installDir.includes(marker) || !installDir.endsWith(`${path.sep}libexec`)) {
-    return resolved;
-  }
-
-  const prefix = installDir.split(marker, 1)[0];
+  const libexecSegment = `${path.sep}libexec${path.sep}`;
+  const libexecIndex = resolved.indexOf(libexecSegment);
+  if (!resolved.includes(marker) || libexecIndex < 0) return resolved;
+  const prefix = resolved.split(marker, 1)[0];
   const optDir = path.join(prefix, "opt", "xmux", "libexec");
-  const candidate = path.join(optDir, path.basename(resolved));
-  if (fs.existsSync(path.join(optDir, "xmux.zsh")) && fs.existsSync(candidate)) {
+  const relativePath = resolved.slice(libexecIndex + libexecSegment.length);
+  const candidate = path.join(optDir, relativePath);
+  if ((fs.existsSync(path.join(optDir, "runtime", "shell", "xmux.zsh")) || fs.existsSync(path.join(optDir, "xmux.zsh"))) && fs.existsSync(candidate)) {
     return candidate;
   }
   return resolved;
@@ -56,9 +56,11 @@ function main(argv = process.argv.slice(2)) {
   }
 
   if (cmd === "npx") {
+    const packageSpec = process.env.XMUX_MCP_PACKAGE_SPEC || DEFAULT_NPM_PACKAGE;
+    const npxPrefix = process.env.XMUX_MCP_NPX_PREFIX || DEFAULT_NPX_PREFIX;
     servers[SERVER_NAME] = {
       command: "npx",
-      args: ["-y", NPM_PIN],
+      args: ["--prefix", npxPrefix, "-y", "-p", packageSpec, "xmux-bridge"],
       trust: true,
     };
   } else {