# tmux chrome

> A tmux status bar and sidebar for coding agents: tmux-ide adopt adds live agent status glyphs, prefix keys, menus and alerts to plain tmux sessions.

**tmux chrome** is the status bar, keys and menus that `tmux-ide adopt` adds to a
tmux session, so you see agent status in a plain tmux client: `tmux attach`, a
phone over SSH, another terminal. It is built from tmux options and is separate
from [the app](/docs/app-surfaces); nothing it draws appears inside the app.

`tmux-ide adopt <session>` adds the chrome to any existing session: a status
bar (the dock) with a tab per session and live agent-status glyphs, plus keys,
menus and popups for the fleet home, the cheat sheet and session switching. Everything it draws is a tmux
option, so it renders on the server and shows up on every client (including SSH).
`unadopt` removes it from that session. The keys and mouse bindings are
server-wide, so unadopting one session also removes them for the other adopted
sessions; run `tmux-ide adopt` on one of those to restore them.

## Agent sidebar for tmux

`prefix b` (or `⌥b`) opens the tmux-ide sidebar in the current adopted session: a
narrow, full-height tmux pane on the left that lists your fleet as a tree of
projects, sessions and windows, each with a live agent-status glyph. Press
`Enter` or double-click a row to jump your tmux client there. The same key closes it.
The sidebar is a real tmux pane, so it stays put while you work and never counts
as an agent.

```bash
tmux-ide sidebar-toggle --session work   # the command behind prefix b
```

You can also add it to a layout as a `type: sidebar`
[widget pane](/docs/configuration#widget-panes). It is part of tmux chrome; the
app has its own `F10` sidebar.

## What's on the bar

```
┌ web ● ─┬ api ○ ─┬ infra ◍ ─┐   [ ⌂ home ^b h ] [ ? keys ^b k ] [ ⧉ switch ^b j ]
```

* **Fleet tabs** — one per session in your fleet. Click a tab to switch to it.
* **Agent-status glyphs** — each tab carries a glyph tinted by the session's
  agent state: blocked, working, done, or idle. One glance across the bar tells
  you where the fleet stands. See [Agent detection](/docs/agent-detection).
* **Triggers** — clickable `[ ⌂ home ]`, `[ ? keys ]`, and `[ ⧉ switch ]` open
  the fleet home, the cheat sheet, and the session switcher. Each advertises
  its **prefix twin** (`^b h`, `^b k`, `^b j`) — the key form that works
  everywhere (see below).

Per-pane, the border chip reads the agent for that specific pane, e.g.
`claude · working`.

## The background updater

Adopting a session starts a small background updater in an internal
`_tmux-ide-chrome` tmux session. Besides refreshing the bar, it:

* sends [notifications](/docs/notifications-events) when an agent becomes blocked or done;
* writes the [event log](/docs/notifications-events#stream-status-changes-as-jsonl);
* writes the snapshot that [`tmux-ide restore`](/docs/restore-resume) rebuilds from;
* captures Codex and Cursor session ids for resume.

Sessions and agents created from the app start the same updater, so these work
whether or not you use the status bar.

## Adopt, unadopt, and safety

```bash
tmux-ide adopt work        # add the chrome to one session
tmux-ide adopt --all       # adopt every live (non-internal) session
tmux-ide unadopt work      # remove the chrome; session keeps running
```

Adoption is **purely additive tmux configuration**. There is no wrapper process
between you and tmux. If tmux-ide crashes or you uninstall it, adopted sessions
keep running as ordinary tmux without the decoration.

## One interaction grammar

Every tmux chrome surface uses the same five keys:

| Key       | Action                     |
| --------- | -------------------------- |
| `j` / `k` | Move down / up             |
| `enter`   | Open / confirm             |
| `/`       | Filter                     |
| `esc`     | Back out / close           |
| `?`       | Show keys for this surface |

Learn it once; it works in the fleet home, the sidebar, and every panel. (The
app has its own keys — see [Getting started](/docs/getting-started#keyboard-shortcuts).)

## The keys

Once a session is adopted, every chrome popup is a couple of keystrokes away.
Each has two bindings — reach for the **prefix twin** first; the `⌥` key is a
faster shortcut when it's available.

| Action         | Prefix (always works) | Alt fast-path |
| -------------- | --------------------- | ------------- |
| Fleet home     | `prefix h`            | `⌥h`          |
| Switch session | `prefix j`            | `⌥p`          |
| Cheat sheet    | `prefix k`            | `⌥k`          |
| Actions menu   | `prefix u`            | `⌥m`          |
| Sidebar        | `prefix b`            | `⌥b`          |
| File explorer  | `prefix e`            | `⌥e`          |
| Git changes    | `prefix g`            | `⌥g`          |
| Config editor  | `prefix v`            | `⌥,`          |

`prefix` is your tmux prefix (`C-b` unless you've changed it), so `prefix h` means
"press `C-b`, release, then `h`".

### Why prefix-first

The prefix twins are the **reliable** path: they work under every keyboard
protocol. The `⌥` (root-table) binds are a one-keystroke fast path. But an agent
pane can temporarily switch how the terminal encodes keys (the kitty keyboard
protocol), and then tmux may never see the `Alt` bind. tmux-ide registers
kitty-encoded fallbacks for the `⌥` keys, but coverage varies by terminal. The
prefix always works, so lead with it.

Both forms come from the same entries in `~/.tmux-ide/config.json` (`keys.*`):
rebind the `⌥` key and its prefix twin follows the new letter, unless tmux
already uses that letter after the prefix. Re-run `tmux-ide adopt` to apply
changes. See [Configuration](/docs/configuration#other-sections).

On a fresh install, a first-run welcome card names the core keys once. Reprint the
full sheet any time:

```bash
tmux-ide cheatsheet
```

## The actions menu

Right-click any pane or the status bar to open a native tmux menu **at the
pointer** — it opens on button *release*. The same menu is on `prefix u` (or
`⌥m`). Either way the action set is identical wherever you invoke it, so you never
have to remember which popup owns a command.

```bash
tmux-ide menu [--client N]
```

## Panels

`prefix e`, `prefix g` and `prefix v` open the file explorer, git changes and
workspace config as floating tmux popups (`Esc` closes). The same widgets can
run as [widget panes](/docs/configuration#widget-panes) in a workspace layout:

```bash
tmux-ide popup explorer
tmux-ide popup changes
tmux-ide popup config
```

These are tmux chrome panels, separate from the app.

## Common questions

### Does adopt change my tmux.conf?

No. `adopt` sets tmux options and key bindings on the running server; it never
writes `tmux.conf`. Root-table bindings such as `⌥h` apply to the whole tmux
server, not just the adopted session.

### Why doesn't ⌥h work inside Claude Code?

Claude Code can switch the terminal to a key encoding that tmux can't match
against `⌥` bindings. Use `prefix h` instead.

### How do I remove it?

```bash
tmux-ide unadopt <session>
```

The session keeps running as ordinary tmux. The chrome keys and mouse bindings
are server-wide, so this also removes them for your other adopted sessions. Run
`tmux-ide adopt <session>` on one of them to bring the keys back.

## See also

* [App tour](/docs/app-surfaces) — the Home and Terminals app
* [Agent detection](/docs/agent-detection) — what the glyphs mean and where they come from
* [Configuration](/docs/configuration#global-config) — rebind every key and recolor every glyph
* [CLI reference](/docs/commands#tmux-chrome-adopt-existing-sessions) — every chrome command