tmux-ide
The open-source workspace for coding agents.
An open-source project by Prototyper · MIT license · Docs
Run and coordinate a team of coding agents, such as Claude Code and Codex, in the tmux sessions you already use. tmux-ide shows what every agent is doing, and lets you jump straight to the one that needs you. tmux keeps owning every process and pane, so closing tmux-ide never stops an agent.
Install
curl -fsSL https://tmux-ide.com/install.sh | sh
tmux-ide appOr, with Node.js 20+ already installed:
npm install -g tmux-ide
tmux-ide appRuns on macOS 26+ (ARM64), macOS 15+ (x64) and glibc Linux (ARM64/x64; use WSL on Windows). Both installs bundle tmux 3.7c, and the installer brings its own Node.js, so you need no sudo and no system tmux. tmux servers you already run must be tmux 3.7 or newer; tmux-ide never replaces a running server. Getting started has the details.
What you get
- Home (
F1) lists every agent across your local and SSH machines, with
- Terminals (
F2) mirrors the live tmux session with window tabs, pane
- Agent status for each pane: working, blocked, done or idle. It comes from
- Notifications when an agent is blocked or done: tmux toasts, macOS and
- Remote machines over SSH, side by side with your local sessions.
- Restore after a tmux crash or reboot, including Claude Code, Codex, Cursor
- Scripting:
send,waitandteam --jsonfrom the CLI, plus scoped pane
- tmux chrome:
tmux-ide adoptadds a status bar, sidebar and keys to plain
Agent teams
Run several coding agents as a team, each in its own tmux pane. 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, group panes with tmux-ide team assign and coordinate them with
send and wait; see
Multi-agent teams. tmux-ide shows
and connects the agents; it does not orchestrate them.
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 doneKeys
| Key | Action |
| ------------------- | ------------------------------------------- |
| F1 / F2 | Home / Terminals |
| F5 | Commands |
| F6 / F7 | Sessions / Attention (agents that need you) |
| F10 | Show or hide the sidebar |
| Ctrl+O / Ctrl+T | Next pane / next window |
| Alt+Arrow | Resize the focused pane |
| Right-click a pane | Select text, rename, split, zoom, close |
| Ctrl+Q | Quit, or detach a detachable app |
Get exact Claude Code status
tmux-ide integration install claudeThis installs Claude Code lifecycle hooks, so new Claude Code sessions report working, blocked, done and idle exactly. Any other agent can report its own state with one tmux option:
tmux set-option -p @agent_state "working:$(date +%s)" # working | blocked | done | idleOptional workspace layout
tmux-ide works with the tmux sessions you already have. To describe a repeatable
layout for a project, add .tmux-ide/workspace.yml:
tmux-ide init # scaffold from your detected stack
tmux-ide validate --json
tmux-ide startSee Configuration and Workspace templates.
How it works
| Layer | Owns | | --------------- | --------------------------------------------------------- | | tmux | Processes, PTYs, sessions, windows, panes and persistence | | tmux-ide daemon | Discovery, agent state and pane streams, one per machine | | tmux-ide app | Home, Terminals, chrome and mouse and keyboard input |
tmux has years of coverage for terminal modes, resizes, disconnects and SSH. tmux-ide builds on it 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.
Documentation
Multi-agent teams Agents can read tmux-ide.com/agents.md for a setup manual written for them.Contributing
See CONTRIBUTING.md and Contributing to tmux-ide. Release notes are in CHANGELOG.md, and security reports go through SECURITY.md.
License
MIT © Thijs Verreck