App tour

The tmux-ide app has two main views. Home (F1) lists every coding agent across your local and SSH machines and shows which ones are working or need you. Terminals (F2) mirrors the selected tmux session live, with window tabs, pane headers and mouse controls. The machine sidebar (F10) lists your machines, sessions and agents next to either view, and Commands (F5), Sessions (F6) and Attention (F7) open on top. To see it move, watch the app demo.

Home

Home shows agents across your configured local and SSH machines. Each agent row includes its machine, tmux server and session so identical session names stay distinguishable. Select an available agent to open its terminal on that machine.

Use the machine filter to narrow the roster, or show only agents needing attention. Connection and observation status remain visible: disconnected machines show last-observed information, and their agents cannot be opened until the connection recovers. One unavailable machine does not prevent other machines from updating.

Search with /, cycle the machine filter with f, and switch between All (0), Working (w) and Needs attention (a). Enter opens the selected agent's pane. "Unavailable" means the connection or observation is missing, not that the agent stopped. Working and needs-attention states come from agent detection.

Quick actions on Home browse sessions (or open Terminals), add a machine (or open Commands), start Learn tmux-ide, and cycle the theme. When no tmux session exists, press n to create one.

Learn tmux-ide

Choose Learn tmux-ide on Home to start a guided walkthrough. It introduces machines, servers, sessions, windows and panes, then guides you through splitting, focusing and resizing panes, finding commands, changing themes and returning to a running session.

Practice happens in a dedicated local tutorial session. Steps advance from observed application changes, and progress is saved locally so you can pause and resume. You can replay the walkthrough from Home. Your other sessions keep running; the walkthrough does not close them.

Recent pane activity

Recent pane activity shows the latest reported reads and input actions, with brief matching indicators in pane headers. This includes tmux-ide actions and send-keys/capture-pane commands observed by the daemon's hooks on tracked panes. Other tmux servers, untracked panes, and commands that bypass those hooks are outside this view. External commands are not automatically attributed to an agent, and the feed does not show the contents of input or captured text.

Terminals

Terminals is a visual client for the selected tmux session:

• the left sidebar lists machines, sessions and detected agents;
• the window strip reflects real tmux windows and creates new ones;
• every pane has a title, state, and relevant controls;
• terminal content is mirrored as terminal cells, including indexed and truecolor output;
• pane clicks and agent rows navigate to the canonical tmux pane;
• splitting, resizing, renaming, creation, and closing are daemon-owned tmux mutations, not a parallel layout model.

The UI retains terminal content through quiet periods, resize, theme switching, daemon replacement, and viewer reattachment. tmux remains the source of truth.

Pane menu

Right-click a pane to open its menu. Each item also has a key while the menu is open:

Closing asks for confirmation. Ctrl+O cycles panes, Ctrl+T cycles windows, and Alt+Arrow resizes the focused pane; you can also drag pane borders.

Named agents

In a live workspace, open Commands → New agent…, enter a display name such as “Architect” or “Reviewer”, and choose Claude Code or Codex. Tab switches the harness; Enter creates the agent in a new window using the workspace directory. The harness must be installed on the selected machine. Select a remote workspace first to create the agent there.

Explicit manual pane names are retained. For Claude Code agent teams in split panes, tmux-ide reads the local runtime team metadata and matches each member against the Claude process running inside that pane. Matched teammate names take precedence over automatic names and changing activity titles. Otherwise, meaningful native pane titles appear ahead of generic process labels. A pane with nothing better gets a stable, memorable fallback such as warm-redwood; an unnamed agent is listed by its harness, Claude Code or Codex. Rename any pane from its menu (R).

The same naming rules feed pane headers, the sidebar, Home and agent details. Team metadata is refreshed on inventory reads with a two-second cache; deleted or unrecognized metadata falls back to ordinary pane naming. In-process Claude teammates share their lead's terminal and are not shown as separate tmux panes. Unknown Claude metadata formats also fall back to native pane titles. Names are display labels; identity and routing still use the exact machine, server and pane binding.

Creating a named agent starts an independent session. It does not register a member in Claude's native team, and renaming a pane does not change a Claude teammate's messaging address.

Scrolling

The mouse wheel acts on the pane under the pointer. At live output, applications that request mouse input receive ordinary wheel events; otherwise, the wheel scrolls terminal history locally. Hold Shift while scrolling to explicitly read terminal history, including inside a mouse-enabled application.

While reading history or selecting text, scrolling stays local. Returning to the bottom during a continuous history gesture does not send its remaining events to the application. Press Escape to return to live output. Alt/Option+wheel remains available for application scrolling at live output; Shift takes precedence. Clicks and drags continue to follow the application's mouse mode.

Selection and links

Drag to select and copy terminal text. Double-click selects a word; triple-click selects a logical line, including its wrapped rows. Continue dragging while scrolling, or hold the pointer above or below the pane to extend into history. Escape clears selection and returns to live output. In a mouse-enabled application, hold Shift to select locally, or use the pane's Select text action.

Local macOS copying uses the system clipboard and shows confirmation when the write finishes. Over SSH and on other platforms, copying uses the host terminal's OSC 52 support. To explicitly use that terminal route on macOS, launch with TMUX_IDE_CLIPBOARD_BACKEND=osc52 tmux-ide. Terminal-routed confirmation indicates that the request was sent; the terminal controls whether it is accepted.

Shift+click a visible HTTP or HTTPS URL to open it in your browser; Ctrl+click and ⌘+click also work. Ordinary clicks retain their existing terminal behavior. Links split across soft-wrapped rows are recognized; this does not open links merely because a program prints them.

Connect to another machine over SSH

The sidebar can hold your local machine and any number of SSH machines, and Home lists agents from all of them. See Run agents on remote machines over SSH to set one up.

Commands

F5 opens Commands: a searchable list of actions with their shortcuts.

Commands also lists your sessions and agents, so typing a name jumps straight to it. Transient notes, such as a successful split, dismiss automatically.

Sessions and Attention

F6 opens Sessions: every session across your machines, with favorites, recent sessions and a live preview. F7 opens the same picker filtered to sessions whose agents need attention. Open sessions become tabs; F9 cycles them and F8 goes back through recently opened sessions. See Getting started for the picker keys.

Not in this release

.tmux-ide/workspace.yml can declare app.views panels such as files, diff and missions. The 2.9 app does not read them: it always shows Home and Terminals. Mission profiles are validated but not dispatched, and tmux-ide web is unavailable. See Workspace layouts.

See also

• Getting started — every keyboard shortcut
• Remote machines over SSH — connect other machines
• Multi-agent teams — group panes and coordinate agents