lmux

lmux — Linux terminal multiplexer for Claude Code agent orchestration. The Linux peer of cmux (macOS) and wmux (Windows).

lmux is a thin CLI wrapper around tmux that exposes a stable, scriptable interface for orchestrating multiple Claude Code agents in panes, splits, and workspaces. It mirrors the cmux API one-to-one so the same orchestration code, skills, and agent definitions work unchanged across all three platforms.

Platform ecosystem

| Platform | Tool | Backend | Install | |---|---|---|---| | Windows | wmux | Electron + ConPTY | Installer | | macOS | cmux | Swift / AppKit | Homebrew | | Linux | lmux | tmux wrapper | curl | bash |

All three expose the same CLI surface (<x>mux send, read-screen, new-split, tree, identify, ...), so an agent skill written against one runs against all of them.

Requirements

• Linux (any distribution with bash)
• tmux >= 3.0
• bash >= 4.0

Install

Preferred (npm):

npm install -g @danielishi/lmux

Alternative (curl | bash):

curl -sL https://raw.githubusercontent.com/DanielIshi/lmux/master/install.sh | bash

The installer symlinks lmux* into /usr/local/bin/ and verifies the install with lmux identify. The npm install registers the lmux* binaries on your PATH via npm's global bin directory.

Quick start

tmux new-session -d -s agents              # start a tmux session
lmux new-split right                        # → surface:2
lmux send --surface surface:1 "claude\n"   # launch claude in left pane
lmux send --surface surface:2 "claude\n"   # launch claude in right pane
lmux read-screen --surface surface:1        # read left pane output

Command reference

| Command | Flags | Description | |---|---|---| | lmux send | --surface surface:N "text" | Send text to pane (append \n for Enter) | | lmux send-key | --surface surface:N <key> | Send key: return, ctrl+c, ctrl+d, etc. | | lmux read-screen | --surface surface:N [--scrollback] [--lines N] | Read pane output | | lmux new-split | right\|down | Split pane, returns new surface:N | | lmux close-surface | --surface surface:N | Kill pane | | lmux tree | --all --json | JSON hierarchy of all panes | | lmux identify | — | Verify lmux (tmux) environment | | lmux list-workspaces | — | List workspaces (tmux windows) | | lmux notify | --title T --body B | Desktop notification | | lmux-send | --surface surface:N "text" | Wrapper: auto-resolves surface refs | | lmux-read | --surface surface:N [--scrollback] | Wrapper: auto-resolves surface refs | | lmux-send-key | --surface surface:N <key> | Wrapper: auto-resolves surface refs | | lmux-grid | <rows> <cols> | Build a rows×cols grid of panes; returns JSON array of new surface:N refs |

See commands/lmux.md for full per-command documentation and tmux equivalents.

Wrapper scripts

lmux-send, lmux-read, lmux-send-key, and lmux-grid are thin convenience wrappers around the core commands. They:

• Auto-resolve surface references against the active workspace (no need to spell out the full tmux target).
• Apply newline normalization automatically.
• Are the recommended entrypoints for agent skills and orchestration loops — the bare lmux <verb> form is the lower-level primitive.

lmux-grid <rows> <cols> builds a rows×cols pane grid in the current workspace and prints a JSON array of the new surface:N references — convenient for spawning a swarm of agents in one call.

Newline rules (critical)

Same semantics as cmux — get this wrong and your agent will type its prompt without ever pressing Enter:

• lmux send "text" — sends literal text. No Enter is pressed.
• lmux send "text\n" — sends text and Enter. Use this to submit a prompt.
• lmux send-key return — presses Enter on its own (e.g. to dismiss a prompt).
• Multi-line input: embed \n between lines; the final \n submits.
• Never rely on a trailing space or shell behavior to submit — be explicit.

Claude Code integration

lmux is designed to be driven by Claude Code agents. See the using-lmux skill at skills/using-lmux/SKILL.md for the canonical agent-side usage patterns, including the orchestration loop, polling cadence, and cleanup contract.

For multi-agent setups (lead + worker panes, cross-server SSH panes), see commands/lmux-team.md.

Uninstall

npm rm -g @danielishi/lmux
# or, if installed via curl|bash:
sudo rm /usr/local/bin/lmux*

Troubleshooting

• lmux: command not found — the lmux* binaries are not on your PATH. For npm installs, check that npm's global bin directory (npm config get prefix/bin) is on PATH. For curl|bash installs, verify the symlinks landed in /usr/local/bin/ and that this directory is on PATH.
• lmux: not inside a tmux session (TMUX env var unset) — every lmux command (except identify reporting the error) must run inside a tmux session. Start one first: tmux new -s agents, then re-run your command from inside that session.
• tmux >= 3.0 required — check your tmux version with tmux -V. Upgrade via your package manager (apt install tmux, dnf install tmux, brew install tmux). Distributions on older LTS lines (e.g. Ubuntu 18.04) ship 2.x and will not work — install from a backports repo or build from source.

License

MIT