# App tour

> Tour the tmux-ide app: Home lists coding agents across machines, Terminals mirrors live tmux panes, plus Commands, Sessions and the machine sidebar.

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](/docs/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](/docs/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:

| Item               | Key |
| ------------------ | --- |
| Select text…       |     |
| Rename pane…       | `R` |
| Split pane right   | `→` |
| Split pane down    | `D` |
| Zoom / unzoom pane | `Z` |
| Close pane…        | `X` |

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](/docs/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](/docs/remote-machines) to set one up.

## Commands

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

| Command                 | What it does                                         |
| ----------------------- | ---------------------------------------------------- |
| Home / Terminals        | Switch view (`F1` / `F2`)                            |
| New terminal window     | Add a window to the current session                  |
| New agent…              | Start a named Claude Code or Codex agent             |
| Split pane right / down | Split the focused pane                               |
| Close pane…             | Close the focused pane after confirmation            |
| Zoom / unzoom pane      | Toggle tmux zoom                                     |
| Appearance…             | Theme and contrast — see [Appearance](/docs/theming) |
| Using tmux-ide          | Built-in help                                        |
| Keyboard shortcuts      | Searchable shortcut list (`Ctrl+K`)                  |
| What's new              | Recent changes (`Ctrl+B`)                            |
| Switch session          | Opens Sessions (`F6`)                                |
| Show / hide sidebar     | Same as `F10`                                        |

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](/docs/getting-started#commands-and-sessions-menus) 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](/docs/configuration#app-views).

## See also

* [Getting started](/docs/getting-started#keyboard-shortcuts) — every keyboard shortcut
* [Remote machines over SSH](/docs/remote-machines) — connect other machines
* [Multi-agent teams](/docs/multi-agent-teams) — group panes and coordinate agents