tmux-ide

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 app

Or, with Node.js 20+ already installed:

npm install -g tmux-ide
tmux-ide app

Runs 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 search and All / Working / Needs attention filters.
• Terminals (F2) mirrors the live tmux session with window tabs, pane headers and mouse controls. Splits, resizes, renames and closes are real tmux operations.
• Agent status for each pane: working, blocked, done or idle. It comes from Claude Code hooks or any agent's one-line self-report, and falls back to reading the screen.
• Notifications when an agent is blocked or done: tmux toasts, macOS and terminal banners, and sound.
• Remote machines over SSH, side by side with your local sessions.
• Restore after a tmux crash or reboot, including Claude Code, Codex, Cursor and opencode conversations.
• Scripting: send, wait and team --json from the CLI, plus scoped pane reads and sends over MCP and an SDK.
• tmux chrome: tmux-ide adopt adds a status bar, sidebar and keys to plain tmux clients.

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 done

Keys

See every keyboard shortcut.

Get exact Claude Code status

tmux-ide integration install claude

This 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 | idle

Optional 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 start

See Configuration and Workspace templates.

How it works

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

• Getting started
• App tour
• Agent status detection
• Claude Code agent teams and Multi-agent teams
• Remote machines over SSH
• Restore and resume
• tmux chrome
• CLI reference
• Troubleshooting

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