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