tmux-ide puts a status board over the agents in your tmux panes

tmux keeps the sessions, tmux-ide keeps the picture

The pitch is short: run and coordinate a team of coding agents, such as Claude Code and Codex, in the tmux sessions you already use, and tmux-ide shows what every agent is doing so you can jump to the one that needs you. The part that makes it safe is stated plainly: tmux keeps owning every process and pane, so closing tmux-ide never stops an agent. There is a layer table in the README that spells out the split. tmux owns processes, PTYs, sessions, windows, panes and persistence. A tmux-ide daemon owns discovery, agent state and pane streams, one per machine. The tmux-ide app owns Home, Terminals, chrome and mouse and keyboard input. The stated principle is that tmux has years of coverage for terminal modes, resizes, disconnects and SSH, and tmux-ide builds on that instead of replacing it, and never puts your work behind a proprietary session format. If the app or daemon stops, your sessions are still ordinary tmux.

Two install routes and an explicit platform floor

The shell installer is one line:

curl -fsSL https://tmux-ide.com/install.sh | sh
tmux-ide app

With Node.js 20 or newer already present, npm is the other route:

npm install -g tmux-ide
tmux-ide app

The platform support is spelled out and worth reading before you try. It runs on macOS 26 and newer on ARM64, macOS 15 and newer on x64, and glibc Linux on both ARM64 and x64, with WSL needed on Windows. Both installs bundle tmux 3.7c and the installer brings its own Node.js, so no sudo and no system tmux are required. The one hard constraint is on servers you already run: tmux servers must be tmux 3.7 or newer, and tmux-ide never replaces a running server. That last point is a deliberate design choice, and it also means an old server on a remote host is a hard stop rather than something the tool works around.

Where agent status comes from, and how wrong it can be

Each pane can show one of four states: working, blocked, done or idle. The status comes from Claude Code hooks or from an agent's one-line self-report, and it falls back to reading the screen when neither is available. That fallback ordering is the most important detail in the whole tool, because screen reading is a guess and a hook is a fact. If you rely on status to decide which pane to open, you want the hook path. The README documents a command that installs the Claude Code lifecycle hooks, so new Claude Code sessions report working, blocked, done and idle exactly:

tmux-ide integration install claude

and for anything else, an agent can set its own state with a single tmux option:

tmux set-option -p @agent_state "working:$(date +%s)"   # working | blocked | done | idle

The timestamp is included so a stale state can be spotted, and the pane-local flag means the state belongs to that pane rather than to the session.

The CLI, the MCP server and the SDK are the real surface

The interactive app is one way in, but the project leans on the scriptable interfaces. The README names send, wait and team --json from the CLI, plus scoped pane reads and sends over MCP and an SDK:

tmux-ide team --json                               # every session, pane and agent status
tmux-ide send %2 "Run the tests and report back"   # type into another agent's prompt
tmux-ide wait agent-status api --status done       # block until a session's agent is done

That trio is the useful part. team --json gives a machine-readable inventory of every session, pane and agent status, which is what you would feed to a script or another tool. send types into another agent's prompt, so one agent can instruct another. wait blocks on a state, which is how a script sequences steps without polling. A team --json output that lists every pane, together with a status vocabulary that is fixed at four values, is a much easier contract to build on than a screen.

tmux-ide observes agents rather than orchestrating them

This is the line the README draws twice and it is the one to hold onto. With Claude Code agent teams, a Claude Code lead spawns teammates in split panes, and tmux-ide shows each one by name, grouped under its team, with live status. To mix Claude Code, Codex and other agents, you group panes with tmux-ide team assign and coordinate them with send and wait. And then the explicit sentence: tmux-ide shows and connects the agents, it does not orchestrate them. So the orchestration logic, the decision about which agent gets which subtask, stays in the agent or in your script. The value the tool adds is legibility across panes and a command channel to them, which is a smaller promise than an agent platform and a much easier one to keep.

Surfaces, keys and the recovery path

The app has two main screens. Home on F1 lists every agent across your local and SSH machines, with search and All, Working and Needs attention filters. Terminals on F2 mirrors the live tmux session with window tabs, pane headers and mouse controls, where splits, resizes, renames and closes are real tmux operations rather than emulations. F5 opens Commands, F6 and F7 are Sessions and Attention, F10 shows or hides the sidebar, Ctrl+O and Ctrl+T move to the next pane and window, Alt+Arrow resizes the focused pane, and right-clicking a pane gives text selection, rename, split, zoom and close. Notifications arrive as tmux toasts, macOS and terminal banners, and sound. Two features matter more than the rest for a long session: restore, which brings back sessions after a tmux crash or reboot including Claude Code, Codex, Cursor and opencode conversations, and tmux-ide adopt, which adds a status bar, sidebar and keys to plain tmux clients so the tool can meet you where you already work.

Where tmux-ide is the wrong tool

Three cases. The first is a single agent in a single pane, where the Home screen and the status machinery cost more than they give you. The second is Windows without WSL, which the platform list rules out. The third is a workflow where you already have a reliable agent status signal and do not want a second daemon observing your panes, since the daemon is a per-machine process that holds pane streams and has to be running for the status to be current. Compared with plain tmux plus a statusline script, tmux-ide's difference in approach is that it is a structured, queryable inventory of sessions, panes and agent states with a JSON output and a wait primitive, rather than a status line you read with your eyes. That is a real gain for scripting and no gain at all for a human who knows where their one agent is. The native alpha builds in the release list, dated 2026-10-17 and 2026-10-18 and described as opt-in GPUI and daemon test drives, indicate the interface is still being rebuilt underneath.

Editorial conclusion

tmux-ide is a good fit for someone running several coding agents at once who has lost track of which pane is waiting on them, and who wants the tmux session layout they already know to stay exactly where it is. It is a poor fit if your agents already report their own state through a mechanism you trust, if you need it to run on Windows without WSL, or if you are not prepared to accept a daemon that has to survive independently of the interface. Check three things before you install it: that your existing tmux servers are version 3.7 or newer, since older servers are not supported and tmux-ide never replaces a running server, that you are on macOS 26+ on ARM64, macOS 15+ on x64, or glibc Linux, and that the agent status you rely on is one you can produce, because when no hook and no self-report are available the tool falls back to reading the screen, which is the least precise of the three mechanisms.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. wavyrai/tmux-ide on GitHub