modelmux

An MCP server that lets Claude Code, Codex, and Perplexity call each other as tools — directly from your terminal, mid-session, without switching windows. Supports text, code, images, and PDFs passed by file path.

Author: Jason R. Woodcock Version: 2.0.0 License: Apache-2.0 — see LICENSE

Instead of copy-pasting between AI tools, you can say things like:

Ask Codex to review this function and compare it to your approach

Use the broker to get Claude and Codex opinions on this architecture, then synthesize a recommendation

Ask Claude to review /Users/you/project/auth.php for security vulnerabilities

Use the broker to analyse /Users/you/docs/architecture.pdf and suggest improvements

Ask Perplexity what the current best practices are for WordPress REST API auth

How it works

modelmux is a small MCP (Model Context Protocol) server. Both Claude Code and Codex support MCP natively — when you register modelmux, it appears as a set of callable tools inside both agents. When you invoke one of those tools, modelmux makes a direct API call to the target AI and returns the response inline into your current session.

It runs on-demand only. The modelmux process starts when you open Claude Code or Codex, and stops when you close them. Nothing runs in the background.

It uses API keys, not subscription quota. Calls go through your Anthropic/OpenAI/Perplexity API accounts at pay-per-token rates — completely separate from your Claude Code or Codex subscription limits. Light use (a few cross-reviews per day) typically costs under $5/month across all three APIs.

Related MCP server: agent-roundtable

Prerequisites

• macOS (tested on MacBook Air and Mac Mini; Apple Silicon and Intel both work)

• Node.js v18 or higher

• Claude Code and/or Codex CLI installed

• API keys for the services you want to use (you can skip any you don't need)

Installation

Quick install

git clone https://github.com/JRWoodcock/modelmux.git
cd modelmux
bash install.sh

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. Add a Codex tool-routing rule (see Codex: "ask Claude" opens an app)

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 if it doesn't show up.

Install from npm

The server is also published to npm. This gives you the modelmux command without cloning, but does not set up API keys or register the server — run those steps yourself (see API keys and the registration commands below).

npm install -g @jrwoodcock/modelmux

# Register the installed command with each agent:
claude mcp add modelmux -- modelmux
codex mcp add modelmux -- modelmux

The package name is scoped (@jrwoodcock/modelmux), but the installed command is just modelmux.

Installing on multiple Macs

Same steps on each machine. The installer creates ~/.modelmux/ locally from the cloned repo. Your API keys are stored in ~/.zshrc on each machine separately — enter them fresh on each install (or sync your dotfiles if you already do that).

# On your second Mac:
git clone https://github.com/JRWoodcock/modelmux.git
cd modelmux
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.

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:

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:

"$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.

Codex (CLI): Codex uses --env (not -e):

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 Desktop app (no codex on PATH): the app bundles the CLI — call it directly:

~/.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

The installer prompts for these interactively. To set or update them manually:

# Add to ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-..."    # console.anthropic.com/settings/keys
export OPENAI_API_KEY="sk-..."           # platform.openai.com/api-keys
export PERPLEXITY_API_KEY="pplx-..."     # perplexity.ai/settings/api

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 ~/.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

export ANTHROPIC_MODEL="claude-sonnet-4-6"   # default
export OPENAI_MODEL="gpt-4o"                  # default
export PERPLEXITY_MODEL="sonar-pro"           # default

Tools

Once registered, both Claude Code and Codex can call these tools naturally during a conversation:

All tools accept:

• prompt — required, the question or instruction

• system — optional system prompt to set the AI's role (e.g. "You are a security expert reviewing code for vulnerabilities")

• file — optional absolute or relative path to a file on disk (see file support below)

The broker tool also accepts:

• targets — array of "claude", "codex", "perplexity" (default: ["claude", "codex"])

• synthesize — true (default) to get a synthesized summary, false for raw side-by-side responses

File support

Pass any local file by path and modelmux will read, encode, and send it to the target AI automatically.

When a broker call includes an image or PDF and Perplexity is a target, Perplexity receives a transparent note that a binary file was attached but not forwarded — it answers on the text prompt alone rather than silently failing.

Size limit: 20 MB per file. A clear error is returned if the limit is exceeded.

Usage examples

Use these prompts naturally inside Claude Code or Codex — the agent will call the appropriate tool automatically.

Cross-review (text prompt)

Ask Codex to review this function and tell me if it agrees with your approach:

function parseDate(str) {
  return new Date(str);
}

Cross-review (file path)

Ask Claude to review /Users/you/project/auth.php for security vulnerabilities

Ask Codex to refactor /Users/you/project/utils.js and suggest a cleaner approach

Image analysis

Ask Claude to describe the UI layout in /Users/you/Desktop/mockup.png and
suggest accessibility improvements

Use the broker to get both Claude and Codex opinions on the architecture
diagram at /Users/you/docs/system-diagram.png

PDF review

Ask Claude to summarise the key decisions in /Users/you/docs/proposal.pdf

Use the broker to analyse /Users/you/docs/architecture.pdf and identify
any risks, with Claude and Codex each giving their perspective

Parallel opinions with synthesis

Use the broker to get both Claude and Codex opinions on whether I should use
PostgreSQL or MongoDB for a WordPress plugin that stores form submissions.

Raw side-by-side (no synthesis)

Use the broker with synthesize=false to compare how Claude and Codex would
approach rate-limiting a REST API endpoint.

All three AIs

Use the broker with targets ["claude", "codex", "perplexity"] to research
the current best MCP servers for browser automation and give me a recommendation.

Web-grounded research

Ask Perplexity what the latest WordPress security patches cover and whether
any affect the WooCommerce REST API.

Role-scoped review

Ask Claude to review /Users/you/project/login.php as a security expert
looking specifically for SQL injection and authentication bypass vulnerabilities

Testing your setup

node ~/.modelmux/src/test.js

This checks:

• Connectivity to each configured API (Claude, OpenAI, Perplexity)

• Local file read/write access

Run it any time you want to verify your keys are working or after moving to a new machine.

Cost

modelmux calls bypass your Claude Code and Codex subscription quotas entirely. Each call is billed at standard API rates against your API accounts:

File calls cost more than text-only calls. Images and PDFs are base64-encoded before being sent, which significantly increases token count. A one-page PDF or a medium-resolution image can use 10–50x the tokens of a plain text prompt. Use file-based calls when you genuinely need the AI to see the file; paste code as text when that's sufficient.

The broker tool with synthesize=true makes two Claude calls per invocation (one for the query, one for synthesis). Use ask_claude or ask_codex individually when you only need one opinion.

You need a small amount of credit loaded on each API account — even $5 on each lasts a long time at light usage. These are separate from your claude.ai and ChatGPT subscriptions:

• Anthropic Console: console.anthropic.com

• OpenAI Platform: platform.openai.com

File layout

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
├── CLAUDE.md           ← guidance for AI coding agents working on the repo
├── LICENSE             ← Apache-2.0
├── NOTICE              ← attribution notice (Apache-2.0)
├── .gitignore
└── src/
    ├── server.js       ← the MCP server (stdio transport, no dependencies)
    └── test.js         ← API connectivity smoke test

server.js has no npm dependencies — it uses only Node.js built-ins and the native fetch API (available since Node 18). No npm install needed.

Troubleshooting

Tools don't appear in Claude Code or Codex 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. 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 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); 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).

Registered but getting no response Run claude mcp list or codex mcp list to confirm modelmux appears. If it does, try the test script to isolate which API is failing.

"File not found" error Use an absolute path (starting with /) rather than a relative path. In Claude Code or Codex sessions the working directory may not be where you expect. Example: /Users/you/project/auth.php rather than ./auth.php.

"File too large" error The 20 MB limit applies to the raw file size before base64 encoding. For large PDFs, consider splitting them or copying the relevant pages to a new file first.

Image or PDF not being understood by the AI Confirm the file extension is one of the supported types. If you're using a .jpeg extension it will work — both .jpg and .jpeg are recognised. For PDFs, very large or scanned-only documents (no embedded text layer) may produce poor results.

Perplexity says it can't see my image/PDF This is expected — Perplexity's API does not support vision or document inputs. The broker sends Perplexity a text note explaining the file was skipped. Use ask_claude or ask_codex directly for image and PDF analysis.

Want to unregister

claude mcp remove modelmux
codex mcp remove modelmux
rm -rf ~/.modelmux

Then remove the API key exports from ~/.zshrc if desired.

Contributing

Pull requests welcome. The server is intentionally minimal — a single file with no npm dependencies. Keep it that way if you can. Contributions are accepted under the Apache-2.0 license (per section 5 of the license).

If you add support for a new file type or AI provider, update the file support matrix in this README and add a test case to src/test.js.

Author

Jason R. Woodcock

License

Licensed under the Apache License, Version 2.0. Copyright © 2026 Jason R. Woodcock.

You are free to use, modify, and redistribute this software, including for commercial purposes. In return, the license requires that you:

• retain the copyright, license, and attribution notices (see NOTICE);

• state any significant changes you make to the files; and

• include a copy of the license with any redistribution.

It also includes an explicit patent grant from contributors. See the LICENSE and NOTICE files for the full terms.