# Getting started

> 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

```bash
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.

```text
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:

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

```bash
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:

```bash
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:

```bash
tmux-ide integration install claude
```

New Claude Code sessions report their state from then on. See
[how agent detection works](/docs/agent-detection).

## 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  |

### Sidebar (when focused)

| 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:

```bash
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](/docs/remote-machines#run-the-daemon-as-a-service) for service status
and restart commands.

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

```bash
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:

```bash
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

```bash
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](/docs/troubleshooting).

## Next steps

* [Tour Home, Terminals and Commands](/docs/app-surfaces)
* [Run agents on remote machines over SSH](/docs/remote-machines)
* [Run a team of Claude Code and Codex agents](/docs/multi-agent-teams)
* [Restore sessions after a tmux crash](/docs/restore-resume)
* [Change the theme](/docs/theming)
* [Every CLI command](/docs/commands)