tmux chrome

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; 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.

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. 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.
• 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 when an agent becomes blocked or done;
• writes the event log;
• writes the snapshot that tmux-ide restore 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

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:

Learn it once; it works in the fleet home, the sidebar, and every panel. (The app has its own keys — see Getting started.)

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.

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.

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

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.

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 in a workspace layout:

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?

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 — the Home and Terminals app
• Agent detection — what the glyphs mean and where they come from
• Configuration — rebind every key and recolor every glyph
• CLI reference — every chrome command