Install tmux-ide with one command, open your first agent-aware tmux session, and learn every key that moves between agents, sessions and panes.

This guide installs tmux-ide 2.9.3, opens your first session in the app, and lists its keyboard shortcuts. Installing takes one command on macOS or glibc Linux, needs no sudo, and leaves any tmux sessions you already run untouched.

Requirements

macOS 26+ on ARM64, macOS 15+ on x64, or glibc Linux (Ubuntu 24.04 or newer baseline) arm64/x64
curl, tar, gzip, and a SHA-256 utility (normally included with your OS)

The installer supplies a private Node.js runtime and bundled tmux 3.7c, so no sudo, Homebrew, or system Node installation is needed. If you already run a tmux server, it must be tmux 3.7 or newer; the installer never kills or replaces a running server. Alpine/musl and native Windows are not supported; use a supported Linux distribution inside WSL.

Installed releases include a compiled app runtime and do not require Bun. Development checkouts use Bun to build the runtime and can opt into live source with TMUX_IDE_TUI_SOURCE=1.

Install

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

You don't need to install tmux first: both the installer and the npm package bundle tmux 3.7c.

Copies Read https://tmux-ide.com/agents.md, set up tmux-ide for this project, and tell me what you did.

The installer prints a PATH instruction if your shell needs one. It installs under ~/.local, verifies the Node.js and app runtime downloads, and preserves existing tmux sessions. To inspect it before running, download install.sh and read it first.

To choose a version or a different user-owned location:

curl -fsSL https://tmux-ide.com/install.sh -o install.sh
sh install.sh --version 2.9.3 --prefix "$HOME/.local"

Claude Code agent teams can open each teammate as a tmux split pane; that page shows the two settings to add. Needs a release newer than 2.9.3: the installer adds them for you when Claude Code is installed. It only adds missing keys, keeps a backup, and never overrides a value you set. To skip it, pass --no-claude-agent-teams to install.sh or set TMUX_IDE_NO_CLAUDE_AGENT_TEAMS=1; to turn it off later, run tmux-ide integration agent-teams disable. If the step fails, the install still succeeds and prints a warning. Installing 2.9.3 skips it and says so.

With Node.js 20+ already installed, npm install -g tmux-ide is also supported. The npm package does not change Claude Code settings.

For npm installations, the first app launch downloads the exact-version runtime if it is missing. It verifies the release metadata and SHA-256 digest, then caches the runtime under ~/.tmux-ide/bin. tmux-ide starts its daemon (the background process that discovers sessions and tracks agent state) only after the app runtime is in place.

If the download was interrupted:

tmux-ide update --tui-binary
tmux-ide app

Open your first session

Home lists the agents and tmux sessions you already have. Select one with the mouse or keyboard, or name a session directly:

tmux-ide app work

If there are no sessions, press n on Home to create one. You do not need a system tmux command: tmux-ide uses its private bundled copy for new servers. If you already use tmux, its existing sessions are discovered too. Closing tmux-ide does not kill the tmux session.

New to the app? Choose Learn tmux-ide on Home for a guided walkthrough in a practice session.

Get exact agent status from Claude Code

tmux-ide detects agents from their process and screen. For exact working, blocked and done states from Claude Code, install its lifecycle hooks once:

tmux-ide integration install claude

New Claude Code sessions report their state from then on. See how agent detection works.

Keyboard shortcuts

Function keys work everywhere in the app. Press Ctrl+K inside Commands to search the full shortcut list, or Ctrl+B for what's new.

Anywhere

Key	Action
`F1`	Home
`F2`	Terminals
`F5`	Commands
`F6`	Sessions — switch sessions across machines
`F7`	Attention — sessions with agents that need you
`F8` / `Shift+F8`	Back / forward through recently opened sessions
`F9` / `Shift+F9`	Next / previous open session tab (`Ctrl+F9` closes the tab)
`F10`	Show or hide the sidebar
`Ctrl+G`	Focus the sidebar (opens Sessions on Home or when hidden)
`Ctrl+Q`	Quit, or detach a detachable app

Terminals

Key	Action
`Ctrl+O`	Next pane
`Ctrl+T`	Next window
`Alt+Arrow`	Resize the focused pane
Right-click a pane	Pane menu: select text, rename, split, zoom, close
`Shift+drag`	Select text inside a mouse-enabled application
`Shift+click`	Open a link (`Ctrl+click` or `⌘+click` also works)

All other keys go to the focused pane. Pane headers and window tabs expose the same actions to the mouse.

Home

Key	Action
`/`	Search agents
`f`	Cycle the machine filter
`0`	All agents
`w`	Working agents
`a`	Needs attention
`Enter`	Open the selected agent

Key	Action
`↑` `↓` or `j` `k`	Move
`Enter`	Open
`←` `→` or `h` `l`	Collapse / expand a machine
`Tab`	Switch between sessions and machines
`/`	Search sessions
`f`	Toggle a session favorite
`?`	Using tmux-ide (help)
`A` / `R` / `D`	Add / retry / disconnect a machine
`Esc`	Return to the terminal

Commands and Sessions menus

Type to search, ↑ ↓ to choose, Enter to activate, Esc to go back. Ctrl+Space switches to navigation mode (j k move, g G first/last, i returns to search). In Sessions, Ctrl+H toggles local/all hosts, Ctrl+F favorites, and Ctrl+P toggles the preview, which Ctrl+E expands. Ctrl+N creates a session, Ctrl+X closes one after confirmation, Ctrl+R retries a host, and Ctrl+← / Ctrl+→ browse windows without switching.

Update, roll back or uninstall

To update an installer-owned copy, run tmux-ide update. It remembers your installation prefix and keeps stable installs on latest and beta installs on beta. Use tmux-ide update --dry-run to preview the operation. The command downloads and runs the same installer used for first-time setup. It verifies the new release before switching the launcher, and retains the previous release for rollback. It does not restart a daemon or replace a tmux server during installation. After installing, reopen the app. To explicitly refresh a running daemon:

tmux-ide update --daemon --if-running

Package-manager installations can use tmux-ide update to update their package.

If you installed a daemon supervisor service, remove it before uninstalling the launcher: tmux-ide daemon service remove --yes --json. Service removal preserves your tmux sessions. See daemon supervision for service status and restart commands.

For an installer-owned copy, use the same prefix with these recovery commands:

sh install.sh --rollback --prefix "$HOME/.local"
sh install.sh --uninstall --prefix "$HOME/.local"

Rollback selects the previous verified release without a download. Uninstall removes the launcher, preserves sessions and settings in ~/.tmux-ide, and leaves runtime files available for processes that are still running. After those processes have exited, you can remove ~/.local/share/tmux-ide/releases to reclaim the space.

The installer retains at most eight marked releases and refuses a ninth until cleanup. To reclaim retired versions, first close every tmux-ide app and stop its daemon and any supervisor service. Ordinary tmux sessions may stay running. Then:

sh install.sh --prune --yes --prefix "$HOME/.local"

--yes confirms that those processes have stopped; the installer does not stop or detect them for you. Cleanup preserves the current and previous rollback releases, settings, and unrecognized files. Releases installed by an older script without a release marker are left for manual review.

Troubleshooting

tmux-ide doctor --json
tmux-ide inspect --json

When reporting an issue, include the output plus the shortest sequence that reproduces it. For specific symptoms, see Troubleshooting.

Getting started