@jrwoodcock/modelmux 2.0.0 → 2.0.1

package/README.md

@@ -59,10 +59,20 @@ The installer will:
 1. Check for Node.js 18+
 2. Prompt you for API keys and save them to `~/.zshrc`
 3. Register modelmux with Claude Code and Codex automatically
-4. Run a connectivity test against each API
+4. Add a Codex tool-routing rule (see [Codex: "ask Claude" opens an app](#codex-ask-claude-opens-an-app-instead-of-calling-modelmux))
+5. Run a connectivity test against each API
 
 Then restart Claude Code and/or Codex to pick up the new MCP server.
 
+> **Using the Claude or Codex Desktop app?** Both work, with two caveats the
+> installer handles automatically: there's no `claude`/`codex` command on your
+> PATH (the installer finds each app's bundled binary instead), and the apps
+> can't read API keys from `~/.zshrc` (so the keys are baked into the server's
+> config at registration). After installing, **fully quit the app with Cmd+Q** —
+> not just closing the window — then reopen it. In Claude, modelmux appears under
+> **Settings → MCP** as a *user* server (available in every project). See
+> [Troubleshooting](#troubleshooting) if it doesn't show up.
+
 ### Install from npm
 
 The server is also published to npm. This gives you the `modelmux` command
@@ -93,18 +103,55 @@ bash install.sh
 
 ### Manual registration (if the installer skipped a tool)
 
-If Claude Code or Codex wasn't found during install, register manually after installing them:
+If Claude Code or Codex wasn't found during install, register manually after installing them.
+
+**Claude Code (CLI):** register at user scope and pass your keys as `-e` values, so the server has them no matter how the host is launched. The server name (`modelmux`) must come **before** the `-e` flags — `-e` is variadic and would otherwise consume the name:
+```bash
+claude mcp add -s user modelmux \
+  -e ANTHROPIC_API_KEY="sk-ant-..." \
+  -e OPENAI_API_KEY="sk-..." \
+  -e PERPLEXITY_API_KEY="pplx-..." \
+  -- node ~/.modelmux/src/server.js
+```
+
+**Claude Desktop app (no `claude` on PATH):** the app bundles the CLI — call it directly with the same arguments:
+```bash
+"$HOME/Library/Application Support/Claude/claude-code/"*/claude.app/Contents/MacOS/claude \
+  mcp add -s user modelmux -e ANTHROPIC_API_KEY="sk-ant-..." -e OPENAI_API_KEY="sk-..." \
+  -e PERPLEXITY_API_KEY="pplx-..." -- node ~/.modelmux/src/server.js
+```
+
+> **Why embed the keys?** A Desktop app is launched from the Dock, so it does
+> **not** load `~/.zshrc` — a server it spawns can't see API keys exported there.
+> Passing the keys at registration (`-e` for Claude, `--env` for Codex) stores
+> them in the MCP config so they're always found. Trade-off: if you later rotate
+> a key in `~/.zshrc`, re-run the registration (or edit the entry) so the stored
+> copy is updated too. The CLI tools inherit keys from your shell, but embedding
+> them is harmless and keeps both paths identical.
 
-**Claude Code:**
+**Codex (CLI):** Codex uses `--env` (not `-e`):
 ```bash
-claude mcp add modelmux -- node ~/.modelmux/src/server.js
+codex mcp add \
+  --env ANTHROPIC_API_KEY="sk-ant-..." \
+  --env OPENAI_API_KEY="sk-..." \
+  --env PERPLEXITY_API_KEY="pplx-..." \
+  modelmux -- node ~/.modelmux/src/server.js
 ```
 
-**Codex:**
+**Codex Desktop app (no `codex` on PATH):** the app bundles the CLI — call it directly:
 ```bash
-codex mcp add modelmux -- node ~/.modelmux/src/server.js
+~/.codex/plugins/.plugin-appserver/codex \
+  mcp add --env ANTHROPIC_API_KEY="sk-ant-..." --env OPENAI_API_KEY="sk-..." \
+  --env PERPLEXITY_API_KEY="pplx-..." modelmux -- node ~/.modelmux/src/server.js
 ```
 
+> **Tip:** if a Desktop app can't launch the server (it shows as failed/not
+> connected), use the **absolute path to node** instead of bare `node` — apps
+> launched from the Dock may not have your `node` on PATH (common with nvm).
+> Find it with `command -v node`, e.g. `/Users/you/.nvm/versions/node/vXX/bin/node`.
+
+After registering, **fully quit and reopen** the app (Cmd+Q, not just closing the window) so it loads the new server.
+
 ---
 
 ## API keys
@@ -122,6 +169,18 @@ Then `source ~/.zshrc` and restart Claude Code / Codex.
 
 You only need keys for the tools you plan to use. The `broker` tool's synthesis step uses Claude, so `ANTHROPIC_API_KEY` is the most important one.
 
+### Updating keys (Desktop apps)
+
+Because the Desktop apps embed your keys in their MCP config (they don't read `~/.zshrc`), changing a key in `~/.zshrc` is not enough — the embedded copy goes stale. After rotating a key, re-sync both apps in one command:
+
+```bash
+bash ~/.modelmux/update-keys.sh        # or ./update-keys.sh from the cloned repo
+```
+
+It reloads the keys from `~/.zshrc` and re-registers modelmux with Claude and Codex (whichever it finds). Restart the apps (Cmd+Q, then reopen) afterward. Terminal CLIs don't need this — they read `~/.zshrc` directly.
+
+The re-registration is safe: Codex is updated in place, and Claude (which must be removed before re-adding) is verified and retried, so a transient failure is reported loudly rather than silently leaving an app unregistered.
+
 ### Optional model overrides
 
 ```bash
@@ -291,6 +350,9 @@ You need a small amount of credit loaded on each API account — even $5 on each
 ```
 modelmux/
 ├── install.sh          ← run this on each Mac
+├── update-keys.sh      ← re-sync API keys into the Desktop apps after rotating
+├── lib/
+│   └── common.sh       ← shared shell helpers (host detection, key flags)
 ├── package.json
 ├── package-lock.json
 ├── README.md
@@ -310,10 +372,19 @@ modelmux/
 ## Troubleshooting
 
 **Tools don't appear in Claude Code or Codex**
-Restart the app after registration. MCP servers are loaded at startup.
+Restart the app after registration. MCP servers are loaded at startup — and for the Desktop app you must fully quit it (Cmd+Q), not just close the window.
+
+**Nothing shows up under MCP servers in the Claude or Codex Desktop app**
+The installer's auto-registration only runs if it can find a `claude`/`codex` command. The Desktop apps have neither on your PATH, so on older installs the step was skipped. Re-run `bash install.sh` (it now detects each app's bundled binary), or register manually using the **Desktop app** commands under [Manual registration](#manual-registration-if-the-installer-skipped-a-tool). In Claude it registers at **user** scope, so it appears as a *user* server (available everywhere), not a *local* one.
 
 **"X_API_KEY not set" error**
-Run `source ~/.zshrc` in your terminal before launching the AI tool, or add the export to your shell profile and open a fresh terminal.
+In a **terminal**-launched tool, run `source ~/.zshrc` first (or open a fresh terminal). In a **Desktop app** (Claude or Codex), exporting keys in `~/.zshrc` is not enough — the app doesn't read your shell profile. Register modelmux with the keys passed as env values (`-e` for Claude, `--env` for Codex; see [Manual registration](#manual-registration-if-the-installer-skipped-a-tool)); the installer does this for you.
+
+**Server shows as failed / won't launch in a Desktop app**
+The app may not have `node` on its PATH (common when node is managed by nvm). Re-register using the **absolute path to node** instead of bare `node` — find it with `command -v node`. The installer already does this automatically.
+
+**Codex: "ask Claude" opens an app instead of calling modelmux**
+Codex's Computer Use plugin can read "ask Claude" as "open the Claude app on screen" rather than calling modelmux's `ask_claude` tool. The installer adds a routing rule to `~/.codex/AGENTS.md` so "ask `<model>`" phrasing prefers the modelmux tools while leaving Computer Use untouched for everything else — **restart Codex** after install for it to take effect. The rule is fenced by a `<!-- modelmux:tool-routing -->` marker (added once, never overwrites your own notes); delete that marked block to undo. You can always force a tool explicitly: *"use the modelmux `ask_claude` tool to …"*.
 
 **Connectivity test fails**
 Check that the key is correct and that your API account has credit loaded. Perplexity requires a paid API plan (separate from Perplexity Pro).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrwoodcock/modelmux",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "MCP server that lets Claude Code, Codex, and Perplexity call each other as tools. Supports text, code, images, and PDFs passed by file path.",
   "author": "Jason R. Woodcock",
   "license": "Apache-2.0",

package/src/server.js

@@ -25,7 +25,7 @@
  * Node.js 18 or higher is needed for fetch support.
  *
  * @author  Jason R. Woodcock
- * @version 2.0.0
+ * @version 2.0.1
  * @license Apache-2.0 — see the LICENSE and NOTICE files.
  */
 
@@ -639,7 +639,7 @@ rl.on("line", async (line) => {
       id,
       result: {
         protocolVersion: "2024-11-05",
-        serverInfo: { name: "modelmux", version: "2.0.0" },
+        serverInfo: { name: "modelmux", version: "2.0.1" },
         capabilities: { tools: {} },
       },
     });

package/src/test.js

@@ -17,7 +17,7 @@
  *   FAIL  — the check ran but produced an unexpected result or error
  *
  * @author  Jason R. Woodcock
- * @version 2.0.0
+ * @version 2.0.1
  * @license Apache-2.0 — see the LICENSE and NOTICE files.
  */