Make claude-cli:// run cmux agent-teams instead ;-)

[braden-reap]

Claude's URL handler only has hard coded list of terminals allowed on Mac OS (linux you can just set TERMINAL env var and windows is hard coded)... but i asked claude and claude literally read its own soruce code and found this :

QrK() — the auto-rewrite routine that runs on every interactive claude startup. Reads process.env.TERM_PROGRAM, looks it up in a table called K_O, and clobbers ~/.claude.json#deepLinkTerminal if it doesn't match what the env says.

function QrK(){
  let H = process.env.TERM_PROGRAM;
  if(!H) return;
  let _ = K_O[H.toLowerCase()];
  if(!_) return;
  if(E_().deepLinkTerminal === _) return;
  e_((K) => ({...K, deepLinkTerminal: _}));
  N(`Stored deep link terminal preference: ${_}`)
}

K_O = {
  iterm: "iTerm",
  "iterm.app": "iTerm",
  ghostty: "Ghostty",
  kitty: "kitty",
  alacritty: "Alacritty",
  wezterm: "WezTerm",
  apple_terminal: "Terminal"
}

So I had claude write instruction prompt that will help set your claude up to use cmux ... read it over first!! Totally overkill for this but it is quite nice for runbooks and such!

I am sure there is some stupid simple method to do it :-P but I wanted to make sure it just reuses my c command that i use so i can edit the flags and command that i use when i run claude myself or when using the cli.

DO NOT JUST PASTE BLINDLY! I had claude aadd checks and make sure it doesnt do anything bad but dont do this if you don't understand what its doing!

• Example deeplink would be claude-cli://open?repo=manaflow-ai/cmux&q=hey (if you had cmux repo cloned somewhere on your system)
• Ideally they'd just let us use cmux AND/OR control the flags to send when opening from url...
• This will basically just pretend to be one of the supported apps and redirect to cmux when called -- im sure there is a cleaner way so lmk haha

---

The Prompt Content for Claude

Prompt to help make claude-cli:// deep links open in cmux (macOS)

Paste this whole file into Claude Code (/copy first, then paste). The agent will walk you through the setup with questions for the parts that are personal preference.

---

Goal (for the agent)

The user wants claude-cli:// deep links (clicked anywhere on macOS — from a browser, Slack, etc.) to open a new cmux workspace running an interactive claude session, instead of opening Ghostty or Terminal.app.

You'll set up four pieces:

1. A small ~/.local/bin/<name> shim that launches cmux's claude integration with the user's preferred flags. They can edit this file later to change flags — the deep-link path will pick those changes up automatically.
2. A wrapper app at /Applications/<HijackedName>.app that hijacks a slot in claude's hardcoded terminal-name list and re-routes incoming launches into cmux.
3. Two patches to ~/.claude.json: an env override (mandatory) and the deepLinkTerminal value.
4. A diagnostic log at /tmp/claude-handler-out.txt that the wrapper writes every time it's invoked — useful if the wiring later breaks.

---

Read this before touching anything

Claude's URL handler reads ~/.claude.json#deepLinkTerminal and looks the value up in a hardcoded list of six names: iTerm, Ghostty, kitty, Alacritty, WezTerm, Terminal. cmux is not in that list. Setting deepLinkTerminal: "cmux" does not work — claude falls back to a probe, and a background routine called QrK() reads TERM_PROGRAM on every interactive startup and overwrites the config back to whatever's installed.

Two consequences:

• We can't tell claude "use cmux" directly. We hijack one of the six slots by registering a tiny wrapper app with that CFBundleName. The wrapper is just an Info.plist + an executable script.
• TERM_PROGRAM would constantly clobber deepLinkTerminal. We disable that by setting TERM_PROGRAM to a value the lookup table doesn't recognize, in claude's own env block.

Also: cmux claude-teams invoked from outside an existing cmux daemon context just exec's claude inline. Under launchd (where the URL handler runs) there's no TTY, so claude auto-enables --print and errors with "Input must be provided either through stdin or as a prompt argument". The wrapper must use cmux new-workspace --command "..." so the new workspace owns a pty.

---

Confirm with the user via AskUserQuestion

Before writing any files, ask these four questions. Don't proceed with defaults — these are personal-preference values.

Q1: Which terminal slot should we hijack?
The hijacked slot must be in claude's hardcoded list AND not actually installed (otherwise launches go to the real app instead of the wrapper). Before showing the question, run:

for app in Alacritty kitty WezTerm; do
  printf "%s: " "$app"
  mdfind "kMDItemFSName == '${app}.app'" 2>/dev/null | head -1 || echo "(not installed)"
done

Recommend the first one that's not installed. Options to present:

• "Alacritty (recommended if not installed)"
• "kitty"
• "WezTerm"

(Ghostty and iTerm and Terminal are likely installed; avoid them unless the user explicitly wants to give them up.)

Q2: What should we name the shim command?
This is the script at ~/.local/bin/<name> that the user types in a shell to start a claude session. Default: c. Ask for a 1–3 character name; warn that something like c, cc, or initials is conventional. The wrapper will exec this same script, so any flag changes the user makes later flow through to the deep-link path too.

Q3: How should sessions launch?
Options:

• "Via cmux claude-teams (recommended — opens in a cmux workspace with claude's teams features)"
• "Via bare claude (simpler, no cmux integration)"

If they pick bare claude, the wrapper still routes through cmux (cmux new-workspace --command "claude ..."); we just skip the claude-teams subcommand.

Q4: Which flags should the shim use?
Options:

• "The recommended preset (--exclude-dynamic-system-prompt-sections)"
• "No extra flags — vanilla"
• "Let me write my own"

If they pick the preset, also ask Q4a: "Want to add --remote-control-session-name-prefix <prefix>? Pick a short prefix unique to this machine (e.g. hostname or initials). Skip if unsure." This is optional — the prefix shows up in cmux's session-list UI when remote-controlling sessions.

---

Prerequisites the agent should verify (don't install for them)

• /Applications/cmux.app exists (its CLI is at /Applications/cmux.app/Contents/Resources/bin/cmux)
• ~/Applications/Claude Code URL Handler.app exists — this is what registers the claude-cli:// scheme. If it's missing, Claude Code isn't installed or hasn't been launched yet.
• ~/.local/bin is on PATH (check echo $PATH). If not, the user needs to add it before the shim works from outside the wrapper.
• The hijacked-slot app from Q1 is genuinely not installed (re-check; if it appeared between Q1 and writing files, abort and switch slots).

---

Mandatory mechanics (do not change)

• CFBundleName of the wrapper MUST exactly match one of iTerm, Ghostty, kitty, Alacritty, WezTerm, Terminal. Mismatch breaks open -na <name> lookup.
• ~/.claude.json#env.TERM_PROGRAM MUST be a string not in {iterm, iterm.app, ghostty, kitty, alacritty, wezterm, apple_terminal}. Use "cmux".
• Pair with COLORTERM=truecolor so 24-bit color isn't lost when the spoofed TERM_PROGRAM skips the color-detection switch.
• The wrapper script MUST prepend /Applications/cmux.app/Contents/Resources/bin to PATH. cmux's bin dir is added only by cmux's own zsh integration, not by .pathrc.
• The wrapper MUST invoke cmux new-workspace --command "...". Do NOT call cmux claude-teams directly from the wrapper — it will exec claude inline and fail without a TTY.
• The wrapper must drop the -e <bin> pair from incoming argv when building the forwarded command. cmux runs its own claude.

---

Step-by-step

For the placeholders below: <HijackedName> = Q1 answer, <shimName> = Q2 answer, <launcher> = either cmux claude-teams or claude per Q3, <flags> = Q4 answer (may be empty).

1. ~/.local/bin/<shimName>

#!/usr/bin/env bash
# Launcher for an interactive claude session. The claude-cli:// deep-link
# handler also invokes this script, so flag changes here propagate
# automatically. Edit the flags below to taste.
exec <launcher> \
  <flags> \
  "$@"

Then chmod +x ~/.local/bin/<shimName>.

If <launcher> is cmux claude-teams, leave it as-is — cmux resolves through the user's shell PATH. If it's bare claude, the user must have claude on PATH (Claude Code installs it there by default).

2. /Applications/<HijackedName>.app/Contents/Info.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>CFBundleName</key><string><HijackedName></string>
  <key>CFBundleDisplayName</key><string><HijackedName></string>
  <key>CFBundleIdentifier</key><string>local.cmux-shim.<lowercased-hijackedname></string>
  <key>CFBundleExecutable</key><string><HijackedName></string>
  <key>CFBundleVersion</key><string>1.0</string>
  <key>CFBundleShortVersionString</key><string>1.0</string>
  <key>CFBundlePackageType</key><string>APPL</string>
  <key>LSBackgroundOnly</key><true/>
</dict>
</plist>

3. /Applications/<HijackedName>.app/Contents/MacOS/<HijackedName>

#!/bin/bash
# Hijacks the <HijackedName> slot in claude's deep-link terminal list and
# routes claude-cli:// launches into cmux via the ~/.local/bin/<shimName>
# script (which is the single source of truth for flags).

LOG=/tmp/claude-handler-out.txt

{
  echo "===== invocation $(date -u +%Y-%m-%dT%H:%M:%SZ) ====="
  echo "pwd: $(pwd)"
  printf 'argv:'
  for a in "$@"; do printf ' %q' "$a"; done
  echo
} >> "$LOG" 2>&1

# Parse the argv shape claude's launcher uses for this slot:
#   --working-directory <cwd> -e <claude-bin> <args...>
# (Alacritty / kitty / WezTerm differ slightly in flag names. For Alacritty
# it's exactly the form above. For kitty replace --working-directory with
# --directory and drop -e. For WezTerm the first positional is `start` and
# args are after `--`. Adjust the parser to match the slot you chose.)
cwd=""
args=()
while [ $# -gt 0 ]; do
  case "$1" in
    --working-directory)    cwd="$2"; shift 2 ;;
    --working-directory=*)  cwd="${1#*=}"; shift ;;
    -e)
      shift 2  # drop -e and the claude bin path; cmux runs its own claude
      while [ $# -gt 0 ]; do args+=("$1"); shift; done
      break ;;
    *) shift ;;
  esac
done

if [ -n "$cwd" ] && [ -d "$cwd" ]; then
  cd "$cwd" || true
fi

# launchd hands the wrapper a minimal PATH. Source the user's bash env
# file if present (Claude Code's convention for non-interactive bash),
# then ensure cmux's bin is on PATH regardless of .pathrc contents.
if [ -f "$HOME/.env.claude" ]; then
  # shellcheck disable=SC1091
  . "$HOME/.env.claude"
fi
export PATH="/Applications/cmux.app/Contents/Resources/bin:$PATH"

cmdline="$HOME/.local/bin/<shimName>"
for a in "${args[@]}"; do
  cmdline="$cmdline $(printf '%q' "$a")"
done

{
  echo "-- launching via cmux new-workspace --"
  echo "cwd: $cwd"
  echo "cmdline: $cmdline"
  /Applications/cmux.app/Contents/Resources/bin/cmux new-workspace \
    --cwd "$cwd" \
    --focus true \
    --command "$cmdline" 2>&1
  echo "-- new-workspace exited with $? --"
  # Bring cmux to the front and switch macOS Space if it lives elsewhere.
  # `--focus true` only focuses the workspace inside cmux; this activates
  # the app itself so the user lands on it from wherever they were.
  open -a /Applications/cmux.app 2>&1
  echo "-- open -a exited with $? --"
} >> "$LOG" 2>&1

Then chmod +x /Applications/<HijackedName>.app/Contents/MacOS/<HijackedName>.

Argv-parse note: the snippet above assumes the Alacritty flag shape. If the user picked a different slot in Q1, adjust the parser. For reference, claude's launcher invokes:

Alacritty: open -na Alacritty --args --working-directory <cwd>     -e <bin> <args>
kitty:     open -na kitty     --args --directory         <cwd>        <bin> <args>
WezTerm:   open -na WezTerm   --args start --cwd <cwd> -- <bin> <args>

4. Register the bundle with Launch Services

/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -f /Applications/<HijackedName>.app

Verify ours is the only registered app with that CFBundleName:

/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -dump \
  | awk '/bundle id:/{bid=$3} /CFBundleName = <HijackedName>/{print bid}' | sort -u

You want exactly one line, local.cmux-shim.<lowercased-hijackedname>. If another entry appears, the real app is installed somewhere — abort and have the user pick a different slot.

5. Patch ~/.claude.json

Two edits — preserve every other key. Don't run a destructive rewrite; use a JSON patch tool or read-modify-write.

• In the top-level env object, add (merge with whatever's already there):

"TERM_PROGRAM": "cmux",
"COLORTERM": "truecolor"

• Set top-level deepLinkTerminal to the hijacked name:

"deepLinkTerminal": "<HijackedName>"

6. Verify end-to-end

Ask the user to click any claude-cli:// link (e.g. a session deep-link from the Claude Code web UI), then run:

cat /tmp/claude-handler-out.txt

Expected: an ===== invocation <timestamp> ===== block, with cmux: /Applications/cmux.app/Contents/Resources/bin/cmux resolved, and -- new-workspace exited with 0 -- at the end. A new cmux workspace should have appeared with claude running and the deep-link's prefill text loaded.

Then check that the rewrite gotcha is dead:

grep -E '"deepLinkTerminal"|"TERM_PROGRAM"' ~/.claude.json

After starting any interactive claude session, those values should still match what you wrote. If deepLinkTerminal flipped back to something else, the env override didn't take — re-verify the env block in ~/.claude.json.

---

Troubleshooting cheatsheet

Symptom	Likely cause
Nothing happens when clicking the link	Launch Services hasn't picked up the bundle. Re-run lsregister -f /Applications/<HijackedName>.app.
Log shows cmux: MISSING	PATH prepend in the wrapper script is missing or wrong.
Log shows "Input must be provided ... when using --print"	Wrapper is calling cmux claude-teams directly instead of cmux new-workspace --command "...".
deepLinkTerminal keeps flipping to "Ghostty"	~/.claude.json#env.TERM_PROGRAM isn't set, or is set to a value the lookup table recognizes.
Wrapper runs but two workspaces appear	The shim does cmux claude-teams internally and the wrapper is also invoking via cmux claude-teams somewhere. Make sure the wrapper uses cmux new-workspace --command "<shim> ...".
Log shows the right command but claude opens with no prefill	The argv parser is dropping the wrong tokens — re-check that --deep-link-* and --prefill are all reaching the forwarded cmdline.
Workspace opens but macOS doesn't switch to cmux's Space	The open -a /Applications/cmux.app step is missing from the wrapper, or System Settings ("Displays have separate Spaces" / a window pinned to a specific Space) is overriding the activation. Escalation: replace open -a with osascript -e 'tell application "cmux" to activate'.