Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
Magmux
A minimal terminal multiplexer for running AI models side by side.
Magmux splits your terminal into panes, each running an independent command. Claudish uses it for --grid mode, where multiple models work on the same task in parallel and you watch them all at once.
It also works standalone -- three shell panes in your terminal with zero config.
Quick start
# Install
brew install MadAppGang/tap/magmux
# Run with 3 shell panes (default layout)
magmux
# Run specific commands in each pane
magmux -e "htop" -e "tail -f /var/log/system.log"
You'll see a split terminal with a status bar at the bottom. Press Ctrl-G then q to quit.
Why a multiplexer, and not just claude -p
Headless mode is not interactive-without-a-TTY. It diverges, and at least one divergence is
silent: an unknown --agent name exits 1 with the list of valid agents in interactive mode and
under plain -p, but under --input-format stream-json it exits 0, prints nothing, and runs
the DEFAULT agent with the full tool set. The run reports result: success.
A magmux pane is a real PTY running a real interactive session — so the child behaves the way interactive Claude Code behaves, not the way print mode does.
Crucially, that does not cost you a terminal. --headless refers to magmux's output, not the
pane's: no raw mode, no alternate screen, nothing on stdout, with the socket as the whole
interface. The panes are still PTYs.
| child sees | unknown --agent |
needs a terminal? | |
|---|---|---|---|
claude -p --input-format stream-json |
no TTY, print mode | silently ignored, exit 0 | no |
claude in a magmux pane, magmux --headless |
real PTY, interactive | refused, agents listed | no |
So automation does not have to accept print mode's divergences in exchange for being scriptable.
Measurements and the upstream status are in ai-docs/architecture/headless-vs-interactive.md.
Headless panes: MCP team and MCP sessions
This is what claudish uses magmux for most. Every slot of an MCP team run, every CLI
claudish team / --team --mode json slot, and every create_session session runs as an
interactive Claude Code inside its own magmux --headless pane. Nothing is drawn on your terminal;
claudish drives each pane over its socket, follows Claude Code's own transcript to know when a turn
has finished, and closes the pane when the slot or session ends.
Requirements:
- magmux 0.18.0 or newer. The npm package bundles it on macOS and Linux; otherwise
brew install MadAppGang/tap/magmux(orbrew upgrade MadAppGang/tap/magmux). With an older magmux, or none,team(mode:"run"),create_sessionandclaudish team/--teamrefuse withmagmux_unavailable: <path> is version <v>; panes need >= 0.18.0 …; claudish never substitutes print mode. 0.18.0 is the floor because it is the first magmux that binds and dials its socket at any path depth, so a pane socket path may be any length (CLAUDISH_PANE_ROOTcan sit anywhere, such as inside a sandbox's home). It also carries what 0.17.0 introduced: claudish delivers every prompt through magmux's Claude Code input gate, bound to the pane's own transcript: magmux types the prompt only into an empty input box, presses Enter only when the box holds exactly that text, and says whether it was submitted. A prompt that is never accepted fails withprompt_not_accepted, and itsreason_detailquotes magmux's answer — for examplemagmux not_accepted still_in_box: …,busy vim_mode: vim editing mode is on …, ormagmux could not tell whether the prompt was submitted …— instead of a silent empty answer. - macOS or Linux. Windows is not supported for MCP
team,create_session, or CLIclaudish team/--team.
Watching a headless pane. You cannot attach to these panes, but you can read their screens:
| Tool | What it returns |
|---|---|
team(mode:"list") |
every run the MCP server holds, with one row per slot: state, activity, idle seconds, tokens |
team(mode:"status", path) |
one run's rows under run.slots |
team(mode:"capture", path, slot) |
that slot's current screen |
capture_session(session_id) |
an MCP session's current screen |
resize_session(session_id, cols, rows), team(mode:"resize", …) |
set the pane's terminal size; Claude Code redraws at the new width |
list_sessions |
every MCP session, same row shape |
A capture carries a seq that grows with every visible change; pass it back as since_seq and an
unchanged screen answers {unchanged: true}, so polling about once a second is cheap.
A pane starts at 160×50. A viewer can resize it at any time (cols 40–9999, rows 24–9999,
at most 4 000 000 cells, clamped);
the next capture carries the new cols/rows. Resizing needs a magmux that ships the resize
verb (MIN_MAGMUX_VERSION); an older magmux answers resize_unsupported and the pane stays 160×50.
See MCP server.
What you might notice on disk. Each pane has a socket and two small directories under
/tmp/claudish-mux-<uid>/ (mode 0700), and one claudish-pane-watcher shell process. They are
removed when the pane closes. If the MCP server is killed, the watcher stops the pane and removes
its files; anything left after a machine crash is cleaned by the next claudish that starts a pane.
With claudish: the visible grid
The --grid flag on claudish team run launches a visible magmux with one pane per model, for you to watch. Each pane streams output in real time while a status bar tracks progress. (Without --grid, CLI team slots run in headless panes, as above.)
claudish team run --grid \
--models kimi-k2.5,gpt-5.4,gemini-3.1-pro \
--input "Refactor the auth module to use JWT"
What happens:
- Claudish creates a session directory with anonymized model IDs
- Generates a gridfile (one command per pane)
- Launches magmux with the grid layout
- Connects to magmux's IPC socket as a client and collects its lifecycle events
Claudish does not poll. Magmux owns the entire pane lifecycle — idle detection, the DONE/FAIL overlays, the green/red tints, the status bar, and auto-exit — and pushes snapshot, exit, results and shutdown events over that socket. Claudish reads them and treats the final results event as the authoritative per-pane state.
The status bar shows live progress, redrawn by magmux's own render loop:
claudish team 3 done 32s complete ctrl-g q to quit
When models fail, the status bar turns red for those entries. Each pane shows a green DONE or red FAIL banner when finished.
Two-model comparison
claudish team run --grid \
--models google@gemini-3-pro,openai/gpt-5.1-codex \
--input "Write a rate limiter for the API"
Two panes, side by side. Compare outputs visually as they stream.
Three-model tournament
claudish team run-and-judge --grid \
--models kimi-k2.5,grok-code-fast-1,gemini-3.1-pro \
--judges glm-5 \
--input "Design the database schema for a multi-tenant SaaS"
Three models run in grid mode. After all complete, GLM-5 blind-judges the anonymized outputs.
Controls
Magmux uses a prefix key (Ctrl-G) for commands, similar to tmux's Ctrl-B.
| Key | Action |
|---|---|
Ctrl-G then q |
Quit magmux |
Ctrl-G then Tab |
Switch focus to next pane |
Ctrl-G then o |
Switch focus to next pane (alternative) |
| Mouse click | Focus the clicked pane |
| Mouse drag | Select text in the focused pane |
| Mouse release | Copy selection to clipboard |
Mouse behavior
Click anywhere in a pane to focus it. Drag to select text -- the selection highlights in yellow (configurable).
When you release the mouse button, the selected text copies to your clipboard through two methods:
- OSC 52 escape sequence (works over SSH)
- pbcopy fallback (local macOS)
Programs running in alternate screen mode (vim, htop, Claude Code) receive mouse events directly, matching tmux behavior.
Pane layouts
The layout adapts to the number of commands:
| Panes | Layout |
|---|---|
| 1 | Fullscreen |
| 2 | Left / Right (50/50 split) |
| 3 | Top-left, Top-right, Bottom |
# 1 pane: fullscreen
magmux -e "claudish --model gemini-3-pro"
# 2 panes: side by side
magmux -e "claudish --model gemini-3-pro" -e "claudish --model grok-code-fast-1"
# 3 panes: default (runs your login shell in each)
magmux
Standalone usage
Magmux works without claudish. Run any commands in split panes:
# Dev workflow: editor + server + tests
magmux -e "vim ." -e "npm run dev" -e "npm test -- --watch"
# Monitoring: logs + processes + disk
magmux -e "tail -f app.log" -e "htop" -e "watch df -h"
Each pane runs a full pseudo-terminal with TERM=screen-256color. Programs that detect screen/tmux TERM types render correctly.
Configuration
Environment variables
| Variable | Default | Purpose |
|---|---|---|
MAGMUX_SEL_FG |
0 (black) |
Selection text color (256-color index) |
MAGMUX_SEL_BG |
220 (yellow) |
Selection background color (256-color index) |
MAGMUX_DEBUG |
unset | Write debug log to /tmp/magmux-debug.log |
# White text on blue selection
MAGMUX_SEL_FG=15 MAGMUX_SEL_BG=33 magmux
Terminal compatibility
Magmux sets TERM=screen-256color for child processes. Programs that check for tmux or screen TERM values work correctly -- this matches what tmux itself does.
The VT-100 parser handles:
- 256-color and truecolor (24-bit RGB) escape sequences
- Bold, dim, italic, underline, strikethrough, overline attributes
- Alternate screen buffer (vim, htop, less)
- Scrollback buffer (1000 lines per pane)
Install
Homebrew (macOS)
brew install MadAppGang/tap/magmux
Go install
go install github.com/MadAppGang/magmux@latest
Build from source
git clone https://github.com/MadAppGang/magmux
cd magmux
go build -o magmux .
The binary has zero third-party dependencies beyond golang.org/x/sys and golang.org/x/term.
Why magmux replaced MTM
Claudish originally used MTM, a C-based terminal multiplexer. Magmux is a Go port of MTM's core VT engine (~2,100 lines) with these advantages:
- Same tech stack -- Go is readable by the claudish community; C was not
- Single file -- one
main.go, no Makefile, no system library dependencies - Clipboard integration -- mouse drag-to-select with OSC 52 + pbcopy
- Status bar -- tab-separated colored pills for team-grid progress display
The C MTM binary still ships in the repo (packages/cli/native/mtm/) as a fallback. The team-grid.ts orchestrator currently resolves whichever binary is available.
Troubleshooting
Panes show garbled output
Cause: The terminal emulator does not support SGR mouse mode or 256-color.
Fix: Use a modern terminal -- iTerm2, Ghostty, Kitty, or Alacritty. The default macOS Terminal.app works but has limited truecolor support.
Text selection does not copy
Cause: OSC 52 clipboard access is disabled in your terminal, and pbcopy is not available (non-macOS).
Fix: Enable "Allow clipboard access from terminal" in your terminal settings. On Linux, install xclip or xsel and alias pbcopy to it.
Ctrl-G does nothing
Cause: Your shell or program intercepts Ctrl-G (the BEL character) before magmux sees it.
Fix: Magmux receives raw input, so this is rare. If it happens in a specific program, try clicking the pane first to ensure focus, then press Ctrl-G followed by the command key.
Status bar shows stale data in grid mode
Cause: Magmux redraws the status bar from its own render loop, counting done and running panes. A model that has finished producing output but whose process has not yet exited still counts as running, so a brief lag between the last line of output and the counter moving is normal.
Fix: Wait a moment. The final status always reflects the true state after all models finish.
Next
- Interactive mode -- Single-model sessions
- MCP server -- Use models as tools inside Claude Code