tmux Integration

WorkFlow works in any terminal. When you run it inside tmux, it lights up with window integration — but always as a guest: it creates real windows in your current session that you navigate with your own keybindings, and never wraps, captures, or bootstraps a session of its own.

Guest, not owner

Splitting, resizing, and moving between panes and windows keep working exactly as they do today. WorkFlow only ever adds windows to the session you're already in. This is the single most important rule of the tmux integration.

How it's detected

WorkFlow checks for the $TMUX environment variable. Present → the tmux launcher backend is used. Absent → the universal launcher is used. There's nothing to configure.

The model

One flat session, one window per workspace, with the dashboard as a peer window. You jump between them with native tmux keys (prefix + window number); WorkFlow never remaps your keys.

Command	In tmux
wf add <branch>	Creates the workspace and a real window at its path
wf open <branch>	Jumps to the workspace's window, creating it on demand
wf close <branch>	Kills the window (keeps the worktree and branch)
wf merge <branch>	Merges, then closes the window as it cleans up
wf rm <branch>	Removes the workspace, then closes the window

In the dashboard, t jumps to the selected workspace's window, and a ▣ marks any workspace whose window is open right now.

Agent status in the tab

When a coding agent is running in any tab — a workspace window, the project base, or a tab you opened by hand — its window shows a live working / waiting / ready / idle icon and recolours to match, so you can see which tab is busy, blocked on you, or done from the tmux status line alone. Borrowed tabs are reverted to exactly their prior state when the session ends. Turn it on with wf hooks install; the Agent Status guide covers the setup, the icons, and how to customise them.

Resurrect

tmux windows are derived, not persisted — the registry is the source of truth. After a tmux server restart or a reboot, recreate the windows for every tracked workspace in one command:

wf resurrect          # alias: wf restore

It reconciles live tmux against the registry, creating a window for any tracked worktree that doesn't have one (and skipping those already open or missing from disk). It reports what it did:

  rebound acme-api/feature-login
Resurrect: 1 created, 2 already open

Sidebar

wf sidebar is a thin, always-on strip of the workspace windows open right now — meant to run in a split pane for an at-a-glance view while you work across several features:

wf sidebar

Unlike the dashboard (the full ledger of everything tracked), the sidebar shows only what's currently open, with each window's live agent status beside it.

Without tmux

Outside tmux, the window-only commands fall back gracefully:

• wf open opens the worktree in your editor instead of jumping to a window.
• wf close, wf resurrect, and wf sidebar report that no tmux session was detected (they need $TMUX).
• wf path, wf copy, and the shell cd helper give you universal ways to reach a workspace.

You still get the full worktree manager and dashboard — tmux just adds the window navigation on top.

Captures

Genuine tmux/sidebar captures can be generated with the procedure in docs/capture/ — capture targets: sidebar, tmux-windows.