# tmux-agent-workbench tmux plugin for running agentic coding tasks (Claude Code, Codex, opencode) inside tmux, where they actually live for hours or days instead of a single terminal command. Workbench v2 also discovers Codex, Claude, Trae, and OpenCode processes in every pane of the current tmux server and maintains one canonical attention snapshot. A per-server Rust daemon classifies `working`, `blocked`, `idle`, and `unknown`, derives unseen `done`/blocked attention, drives a responsive sidebar and touch-friendly searchable lists, and owns focus-aware desktop/sound notification delivery. It does not require agents to be launched by Workbench and it never displays or persists prompt text by default. See the durable [v2 specification](docs/attention-v2.md) and [implementation status](docs/attention-v2-status.md). ## What it is / why A direction often has several tasks in flight. Workbench gives each task a place to run and keeps their code changes independent: - **One session groups a direction or larger goal.** - **One window is one task**, with its own agent, conversation, and progress. - **Each coding task owns isolated worktrees and branches.** Multiple tasks may use the same repository, but never the same writable checkout. - Git tools, editors, shells, and services open on demand within the task. Temporary tools close on exit; there is no prebuilt inspection layout. For example: ```sh tmux-agent-workbench new --task formulas word-experience bear-web-x tmux-agent-workbench task new image-layout bear-web-x ``` This creates two task windows in `word-experience`, with independent checkouts under `~/Workspace/word-experience/tasks/formulas/` and `tasks/image-layout/`. Tasks can start without repositories, and one task can span multiple repos. Shared machine/environment maintenance is an explicit exception to checkout isolation, rather than the default for parallel coding work. The repo has two layers: - **Layer 1** (`workbench.tmux` + `bin/`) tracks agents, supplies navigation, temporary tools, and supporting service panes. - **Layer 2** (`git/workbench-git.tmux` + `git/bin/`) creates workspace sessions, task windows, and isolated worktrees using `~/Code` as the source-checkout pool and `~/Workspace` for task directories. Disable its tmux bindings with `@workbench-disable-git 1`. Both layers live in one repo and load from a single `@tpm_plugins` entry — see [Install](#install). ## Requirements - **tmux >= 3.6 for interactive status/sidebar menus** (core requires >= 3.2), **git**, and the shipped `tmux-agent-workbench` binary — hard requirements. The installer downloads a matching macOS/Linux x86_64/aarch64 or iSH i586 musl release, then falls back to a local Cargo build. - **Bash**, **jq**, and **Python 3** — required for assistant session persistence. Python 3 and jq also let local Codex/Trae token summaries read session logs without the optional `ccusage` CLI. The reader respects `CODEX_HOME` and `TRAE_HOME`, including Termux home paths. - **tig** or **lazygit** — used only when opening a temporary Git tool. Defaults to `tig`; set `@workbench-git-tool` to change it. - **nvim** or **vim** — used only for an explicitly opened editor. Uses `$VISUAL`/`$EDITOR`, otherwise `nvim`, then `vim`. - Project, repository, Session and Agent pickers use the built-in searchable list UI, with large touch targets and a pinned Close button. - **zoxide** — soft dependency of the picker: widens its candidate list with your directory-jump history. Its absence degrades the picker (fewer candidates), it doesn't break it. - **tmuxinator** and **sesh** — soft dependency of the *persistent pool* layer 2 generates. `tmux-agent-workbench projects rebuild` only ever writes YAML under `~/.config/tmuxinator/`; it never shells out to the `tmuxinator` binary itself. Whether that YAML actually gets used to spin up sessions later is on you (`tmuxinator start `, or `sesh connect` if it reads the same pool) — install them if you want that part of the workflow, skip them if you're happy driving `tmux-agent-workbench new`/`tmux-agent-workbench add` directly. ## Install Via TPM, one entry covers both layers — TPM discovers and runs every executable `*.tmux` file under a plugin's cloned tree, so `workbench.tmux` and `git/workbench-git.tmux` both load automatically: ```tmux set -g @tpm_plugins 'lukewang1024/tmux-agent-workbench' ``` Then `prefix+I` to fetch and source it (or `prefix+U` to update, same as any other TPM plugin). Install the versioned attention binary once after TPM has cloned the plugin: ```sh ~/.local/share/tmux/plugins/tmux-agent-workbench/install tmux-agent-workbench doctor ``` The POSIX installer first downloads the matching macOS/Linux x86_64/aarch64 or iSH i586 musl release and falls back to `cargo build --release` when no release asset is available. It installs executables under `~/.local/bin` by default, stages the binary before replacing it, and signs the staged Mach-O on macOS. The installer then hands off running daemons and resident sidebars in the current runtime directory. Sidebar panes retain their IDs, layout and focus, and installation waits for their replacement processes to render before returning. Repeating the handoff leaves current processes running. Reload tmux after installation to update key bindings and hooks. Plugin loading never overwrites Workbench configuration or Agent configuration. Termux is detected explicitly and always builds for its native Android target. Tagged releases provide Android arm64 and x86_64 assets; install the Termux `rust` package only when using an unreleased revision or an architecture without a release asset. iSH uses the static i586 musl asset to avoid unsupported SSE instructions; no Rust compiler is needed inside the emulator. Android notification setup remains specific to Termux. Set `TMUX_AGENT_WORKBENCH_RELEASE_TAG=v` with release-only mode to select an exact prerelease instead of GitHub Latest. The public CLI, tmux plugin, status menus and sidebar launchers share one core selection rule: prefer the installed core over any binary left under `target/release`. Thus a release upgrade also takes effect on machines that previously built from source. To run a development build explicitly, set `TMUX_AGENT_WORKBENCH_BIN` to that executable's absolute path; an invalid override does not silently select another version. Without an installed core, the checkout's release binary remains available as a fallback. If you want layer 2 disabled from the start, set this **before** the `@tpm_plugins` line so it's in effect the first time the plugin loads: ```tmux set -g @workbench-disable-git 1 ``` ## Keybindings Workbench uses Sidebar and one unified Workbench menu as its control surfaces. Press `prefix+Tab` for Sidebar, or `prefix+m` / `prefix+M-t` for the Workbench menu; the left status-bar control opens the same menu. The Sidebar menu contains Sidebar actions only. Once Sidebar is focused, press `?` for a centered list of plain single-key actions. Optional global bindings are (re)installed each time the plugin loads when their option is explicitly set. The Workbench menu groups Create, Switch, Close and Layout. Create first offers Agent, Pane, Window and Session; Agent opens Quick create and each installed Coding Agent. Window contains new-window and VS Code choices when available. Switch and Close each list Agent, Window, Pane and Session; Close confirms its target. Extract is in the menu and has its own status-bar button beside Workbench. Detach, Host / SSH and CPU / resources remain available. The `+` status-bar shortcut launches the last-used Agent setup directly, or opens Create when no setup has been saved. The Sidebar status-bar control opens Sidebar actions directly: visibility, details (`d`), next attention (`n`) and reload (`r`). All action menus use the custom menu component, including shell-defined menu providers through a compatibility adapter. Sidebar popups and built-in selection lists close on an outside tap without passing it to the terminal. Project/repository pickers and workspace/task name dialogs use the same container and pinned Close control. | Action | Option | Default | Runs | |---|---|---|---| | Pick/start a tmuxinator project | `@workbench-key-project` | unbound | Project picker | | Open a temporary Git tool | `@workbench-key-inspect` | unbound | Task repository picker | | Regenerate the tmuxinator pool | `@workbench-key-regen` | unbound | `tmux-agent-workbench projects rebuild` | | Prompt for a new workspace | `@workbench-key-new` | unbound | Workspace name prompt | | New isolated task in this workspace | `@workbench-key-task` | unbound | Task name popup | | Toggle current-window Agent sidebar | `@workbench-key-sidebar` | `Tab` | Rust sidebar | | Open Workbench menu | `@workbench-key-main-menu` | `m` | Create / Switch / Close / Layout / Extract / Host / resources | | Open Workbench menu | `@workbench-key-mobile-menu` | `M-t` | Same Workbench menu | | Mark current pane | `@workbench-key-pane-mark` | `M-m` | tmux pane mark | | Open Agent commands | `@workbench-key-agent-menu` | `M-a` | Agent menu | | Toggle all Agent sidebars | `@workbench-key-sidebar-all` | unbound | Rust sidebar | | Pick any session by attention | `@workbench-key-session` | unbound | session picker | | Pick any detected Agent | `@workbench-key-agent` | unbound | Agent picker | | Jump to next unseen attention | `@workbench-key-attention` | unbound | attention queue | The Agent sidebar/session/Agent/attention actions belong to layer 1 and do not depend on the git-worktree layer. Regenerate/new/task require layer 2. The old `@workbench-key-promote` option also opens the task-name popup for compatibility. Their global options remain available for users who prefer direct prefix shortcuts; the default avoids claiming memorable tmux keys for infrequent operations. **Check for collisions before trusting any default, including these ones** — a key that's free in your `tmux.conf` text can still be silently claimed by a plugin loaded later via TPM (this exact thing happened choosing these defaults: plain `g` looked free in the config file but `tmux-sessionist` grabs it at load time). Verify with the *live*, post-plugin-load table, not just the file: ```sh tmux list-keys -T prefix | grep -E '(^| )(m|M-a|M-m|M-t|Tab)( |$)' ``` To rebind, set the option **before** the plugin loads (add it above `@tpm_plugins` in `tmux.conf`, or set it and reload the plugin), e.g.: ```tmux set -g @workbench-key-inspect 'g' set -g @workbench-key-regen 'M-r' set -g @workbench-key-new 'n' set -g @workbench-key-task 'M-p' ``` Then `prefix+I` (or `tmux source-file ~/.tmux.conf` followed by re-running the plugin script) to re-bind with the new key. ## Configuration Read once at plugin-load time. Each option is bridged to a same-shaped `WORKBENCH_*` environment variable **only if you actually set it** — if you don't, the underlying scripts fall back to their own built-in default, so "unset" and "set to the default value" behave identically. | Option | Bridged env var | Default | Effect | |---|---|---|---| | `@workbench-agent` | `WORKBENCH_AGENT` | `claude` | Which CLI `tmux-agent-workbench agent start --managed` execs: `claude`, `codex`, `trae`, or `opencode`. | | `@workbench-git-tool` | `WORKBENCH_GIT_TOOL` | `tig` | Git TUI opened on demand in a temporary popup (e.g. `lazygit`). | | `@workbench-code-root` | `WORKBENCH_CODE_ROOT` | `~/Code` | Root of your persistent repo checkouts. Layer 2 looks here to resolve a short repo name (`tmux-agent-workbench add web-app`) to its main checkout. | | `@workbench-workspace-root` | `WORKBENCH_WORKSPACE_ROOT` | `~/Workspace` | Workspace directions; task checkouts live at `/tasks//`. Legacy workspaces reopen as one existing task. | | `@workbench-disable-git` | — (checked directly, not bridged) | unset | Set to `1` to skip loading layer 2 (`git/workbench-git.tmux`) entirely. | ```tmux set -g @workbench-agent 'codex' set -g @workbench-git-tool 'lazygit' set -g @workbench-code-root '~/Code' set -g @workbench-workspace-root '~/Workspace' ``` ### Attention v2 The Rust engine reads `$XDG_CONFIG_HOME/tmux-agent-workbench/config.toml` (normally `~/.config/tmux-agent-workbench/config.toml`). Unknown keys and invalid values are rejected. `tmux-agent-workbench config check` validates the file and every per-Agent manifest override; `tmux-agent-workbench reload` swaps a completely validated replacement into the running daemon and retains the previous config if validation fails. ```toml [ui] language = "auto" # auto follows the OS; e.g. zh-CN, en-US, ja-JP [detection] process_interval_ms = 1000 active_capture_interval_ms = 500 idle_capture_interval_ms = 2000 # Opt in to fewer background processes when every live agent is idle. # low_process_churn = true capture_lines = 40 capture_bytes = 65536 stale_grace_ms = 3000 [sidebar] width = 26 min_width = 18 max_width = 64 main_min_width = 80 position = "left" auto_create = true agent_sort = "grouped" # grouped or prioritized # Optional: enable automatic splitting (defaults: five tasks and semantic grouping). # [auto_split] # enabled = true # threshold = 5 # strategy = "semantic" [notifications] enabled = true sound = true style = "overlay" # overlay or system; Linux uses notify-send volume = 1.0 no_repeat = true mute_done = false mute_request = false [openpeon] # packs_dir = "/path/to/packs" # default: ~/.openpeon/packs # active_pack = "my-pack" [relay] bind = "127.0.0.1" port = 19999 ``` Sidebars share one core-maintained inventory, including team information, session branches, visibility and appearance. Routine inventory queries are limited to one per second by the core, regardless of sidebar count; concurrent interactive refresh requests are coalesced. If that inventory is temporarily unavailable, sidebars retain the last frame while the core retries. Agent screen sampling and explicit user actions have their own cadence. With `low_process_churn = true`, lifecycle hooks and user-driven focus changes wake detection promptly. While all agents are idle, panes in attached sessions share one foreground probe at the configured idle interval (two seconds by default). The same probe supplies focus, sidebar inventory and palette changes; sidebars normally render these within one more refresh. Hookless background screen changes are sampled less frequently, with an interval of at least five seconds per idle agent. Background process discovery falls back to at least 20 seconds; foreground command and topology changes trigger discovery sooner. Intervals are scheduling targets and can be longer on a busy machine. Unknown or active agents retain the regular detection cadence. Alternatively, create the empty file `$XDG_CONFIG_HOME/tmux-agent-workbench/enable-low-process-churn` to opt in without modifying TOML. Older binaries ignore the file, so rollback remains safe. To restore normal intervals, set the option to `false` and remove the marker file if present; restart sidebars after changing the setting. Automatic direction splitting is disabled by default. When enabled, a task's own agent chooses its direction by meaning, using existing direction names and task titles. `title set` counts distinct windows with live local agents in the selected direction. Five tasks fit by default. If another placement would exceed that limit, Workbench leaves the caller in its current window and queues the request for one machine-wide Codex manager session. A global XDG state lock serializes manager creation and ticket submission across tmux servers; the manager session lives in a reserved tmux session and processes tickets in its persistent Codex conversation. Callers must not start another worker or move windows themselves. The manager handles one exact source session at a time and its scoped apply preserves unrelated directions, non-agent windows, team windows, the personal assistant, panes, clients, and manually marked focus windows. The manager session is excluded from task capacity and protected from reorganisation plans. Its Codex sandbox is `danger-full-access` so it can read Workbench state and control local tmux sockets; the configured approval policy is unchanged. After the manager finishes, the caller chooses an appropriate child direction and retries placement. Unrelated full directions do not trigger work. If the tasks cannot be split confidently or the manager cannot start, the caller stays in its current window and continues its task. A task started inside an already full direction can temporarily bring that direction above the limit. `tmux-agent-workbench auto-split status` shows pending tickets and manager session status. Tickets remain pending until the manager settles them; a repeated placement request requeues the same active manager ticket instead of creating another manager. The manager checks the exact ticket ID before acting, so duplicate queue deliveries are harmless. After fixing the cause of a failed or unavailable ticket, reopen only that ticket with `tmux-agent-workbench auto-split retry --ticket `, then retry placement. Unchanged failures use the normal retry backoff. Tickets created by older releases keep their original worker ownership and are not transferred automatically. After confirming that the old worker stopped, settle one with `tmux-agent-workbench auto-split finish --ticket --result failed`; the next placement attempt can then use the singleton manager. On macOS, clicking an overlay resolves the tmux client attached to the target session, focuses its exact iTerm2 or Terminal TTY/tab, and then selects the target window and pane. If no matching attached client exists, Workbench falls back to the most recently active client and activates the terminal application. The layout controller also honors the established tmux options `@sidebar_width`, `@sidebar_position`, `@sidebar_auto_create`, `@sidebar_min_width`, `@sidebar_max_width`, and `@sidebar_main_min_width`. Explicit tmux values win over seeded config values. All attention bindings can be changed with `@workbench-key-sidebar`, `@workbench-key-sidebar-all`, `@workbench-key-session`, `@workbench-key-agent`, and `@workbench-key-attention` before the plugin loads. The sidebar switches between Agents and Sessions from the current tmux server. Click the first Powerline segment or press `Tab` to switch views. The adjacent pinned count opens the pinned menu for the current view; the sort and global menu segments are also touchable. Pinned cards stay just below the bar. Select an Agent or session and press `p`, or use its item menu, to pin or unpin it. In Sessions, tap the pin icon at the right of a row to toggle its pin. Click a pinned card, or press its `1`–`9` shortcut, to visit it. Each view has its own pinned items, which also remain in its scrolling list. Keyboard, wheel, and touch navigation can move between pinned cards and ordinary rows. On short screens, the pinned menu still contains every pinned item. Window-scoped `@agent_focus` markers follow Agent window moves; session pins use a session-scoped `@workbench_session_focus` marker. A designated personal assistant stays first in the Agents view and is automatically pinned again when the same thread resumes in another window. The view and sort selection are remembered across sidebars. Agents can be sorted by `grouped` (stable session/window/pane order) or `prioritized` (blocked > done > working > idle > unknown). Sessions can be sorted by name or priority. Press `d` to toggle more detail, including Agent kind, human-readable window/pane indices, process id, state source, hook health, and matched rule. Enter or left-click focuses a row; `m` or right-click opens session/agent actions. The top row opens the tmuxinator-project picker and the global action menu. In responsive popup mode, `Escape`, `Ctrl-C`, and `Ctrl-D` close the popup; the footer and global menu also expose a mouse-driven close action. Those exit keys are popup-only and do not terminate a persistent sidebar pane. Activating a session or Agent with Enter or a left click also closes the popup after the navigation succeeds. Agent cards show the agent thread-name on the first line. For Codex sessions without hook metadata, Workbench reads the thread title from the Codex terminal title; it then falls back to a meaningful tmux window title and the tmux session name. This keeps several unnamed task windows in one direction distinguishable without displaying generic titles such as `zsh`. The second line shows task progress (when available), workspace session name, status, and agent type. Grouped mode shows the session name once above its agents; prioritized mode keeps it on each agent card, so parallel tasks within one direction remain distinguishable. Both lines are clickable, and long Chinese titles truncate to their actual terminal width. Pane Teams appear as a single task, collapsed by default. The lead row shows worker count and `!N` / `✓N` for blocked / done workers, including when the team is collapsed. Its status color and agent type follow the lead agent. Press Space or Left/Right on the lead, or click its arrow, to collapse or expand the indented workers; Enter or a click on a worker focuses its pane. A worker card shows its task title, then its member name and status. An explicit received new-task message takes precedence over the agent thread title; the original brief and member name are fallbacks. Priority sorting keeps the team together and uses its most urgent member. Live membership requires matching pane markers and agent-team state for the same window and tmux socket; uncertain members remain separate. Retained snapshots of stopped workers stay hidden after the lead exits when their team state still identifies them. Expansion is local to the open sidebar. With focus in the sidebar, press `?` for the complete centered shortcut card. The everyday keys are plain letters: `i` opens a temporary Git tool, `d` toggles details, `n` jumps to attention, and `s`/`a` open pickers. Heavier mutating actions use uppercase: `N` picks/starts a tmuxinator project, `W` creates a workspace, `T` creates a task in the selected session, and `R` rebuilds generated projects. `m` opens the row menu. The Sidebar icon opens Sidebar actions; the Workbench menu groups Create, Switch, Close and Layout around Agent and tmux objects. The daemon publishes `@workbench_window_state` and `@workbench_window_label` as window-scoped tmux options for status themes. They aggregate Agents in that window using `blocked > working > unseen done > idle`; both options are unset when the window has no Agent. This keeps process detection in Workbench while allowing a theme to render a lightweight current- window badge without polling or screen scraping. When `tmux-adaptive-theme` is present, the plugin registers those values through the theme's generic `@adaptive_context_*` interface. Agent Status opens the active agent's command menu. From a shell pane, it focuses the most recently used interactive agent in the same window first; without a remembered target, multiple agents appear in a single chooser. The usage suffix has a separate click target for its usage menu. Windows without an interactive agent hide this capsule. Separators and empty status space have no click action. Usage shows the selected provider's remaining quota and token totals from the local cached usage data; its existing compact- width policy remains unchanged. Host metrics are enabled by default in the adaptive theme Host capsule. The resource capsule starts in Compact mode (CPU and memory); clicking it opens a menu for Standard (also disk), Full (also upload/download), or btop. Workbench owns sampling, caching, width defaults and the menu action. Set `@workbench-host-metrics off` to disable them. See [host metrics](docs/host-metrics.md) for mode selection, platform support and the standalone CLI. Session/Sidebar and tmux controls form the left group, followed by window labels. By default, the left accent is the Session control and the left neutral buttons are Workbench then Quick Agent (`+`). The right neutral order is Extract, CPU, time, date, battery and Host; Agent status is in the right accent. Host remains neutral. These four regions can be ordered independently; see [custom status-bar layout](#custom-status-bar-layout). Workbench opens the same menu as `m` and `M-t`; Extract has its own button and remains in the menu. Agent status opens Agent commands as `M-a`. The session label performs the same responsive Sidebar toggle as `Tab`. Prefix remains available through the keyboard. Workbench owns their ranges and behavior; the adaptive theme owns their placement, separators, and colors. The Host segment is a separate clickable range: it launches the existing `ssh-connect` effective inventory as a tmux menu; choosing a Host opens a new window and connects there. Host filtering and SSH behavior remain owned by the dotfiles command rather than duplicated in Workbench. ### Custom status-bar layout When [tmux-adaptive-theme](https://github.com/lukewang1024/tmux-adaptive-theme) is installed, set the four order options in `.tmux.conf` to choose each region's contents and order. Lists are space-separated. Built-in items are `session` on the left and `context`, `cpu`, `time`, `date`, `battery` and `host` on the right. Workbench registers the semantic action IDs `workbench_menu`, `workbench_quick_agent` and `workbench_extract`; place an action with `action:`. This reproduces Workbench's defaults: ```tmux set -g @adaptive_status_left_accent_order "session" set -g @adaptive_status_left_neutral_order "action:workbench_menu action:workbench_quick_agent" set -g @adaptive_status_right_accent_order "context" set -g @adaptive_status_right_neutral_order "action:workbench_extract cpu time date battery host" ``` The left accent renders before the left neutral region. On the right, neutral renders before accent, with accent at the outer edge. The theme omits hidden items and their separators; a region disappears when all its items are hidden. To hide a Workbench action, set its `@adaptive_action__visible` option to a tmux format that evaluates to `0`. Reapply `tmux-adaptive-theme.tmux` after changing the order options in a running server. The Workbench menu opens from the left status-bar control or `m` / `M-t`. Create first offers Agent, Pane, Window and Session; Agent opens Quick create and each installed Coding Agent. Window contains new-window and VS Code choices when available. Switch and Close each list Agent, Window, Pane and Session; Close confirms its target. Layout contains pane arrangements. Extract is in the menu and has its own status-bar button. Detach, Host / SSH and CPU / resources remain available. The `+` shortcut repeats the last successful Agent setup, or opens Create when no setup has been saved. Sidebar's icon opens its own actions only. Switch Window lists only the source Session's windows; Switch Pane lists only its Window's panes. Sessions and running Agents have separate server-wide views. The shared custom menu uses Sidebar's bordered popup and two-line title/context rows, with search, paging, and full-width Back and Close rows. The popup caps its size at 96 columns by 40 rows and uses all available space on very small screens. Labels use available cells without ellipses. Selection happens on release; dragging scrolls without activating. Back restores the originating Sidebar or Workbench menu. Wheel scrolling, touch, keyboard navigation and refresh positioning share one list component across Sidebar and filtered views. New Session prompts for a name, starts in the source pane's directory, and switches only the invoking client. Selecting an agent opens one configuration panel. Codex recommendations are loaded dynamically from the active agent-team recommendation cache. The menu shows all distinct scenarios in cache order and keeps the newest numeric model version in each category. Agent-team calculates choices from the available benchmark data. The first eight scenarios have numeric shortcuts; additional scenarios remain available through navigation or mouse. When recommendations exist, the first one is selected on entry. The Codex defaults choice remains available regardless of recommendations. Trae keeps its daily, hard and batch scenes. All tools expose Single/Team and, for Team, Native/tmux choices in the same panel. Codex has a Fast control that follows the selected recommendation by default or forces Fast off. The preview shows the recommendation's Fast value, the explicit override, or the Codex default when no recommendation is available. The panel previews the selected model and effort from the recommendation cache; it does not query a model catalog. Opening Create Agent → Codex prepares the cache once, with asynchronous daily refresh after the first successful fetch. Workbench does not duplicate model configuration; agent-team resolves recommendation IDs and uses Codex defaults when no recommendation is selected. An unknown explicit ID fails instead of silently changing the selected model. ```sh agent start codex --recommendation agent start codex --recommendation --team agent start codex --recommendation --team --tmux agent start codex --team agent start traex --scene daily agent start claude agent start opencode --team ``` Dynamic Codex recommendation rows use numbered shortcuts. Trae scene shortcuts remain `d/h/b`; `s/t` selects mode and `n/m` selects Native/tmux. The Codex panel's Permission control (`p`) defaults to Auto approval and can persistently switch to YOLO. Fast (`f`) follows the selected recommendation by default and can persistently force Fast off. Auto approval launches Codex with `--no-yolo --approve-for-me`; YOLO uses `--yolo` alone. Other tools keep their existing automatic approval flags. Quick Agent repeats the last successful launch's permission and Fast choices. Single and native Team open one new window; pane Team lets `agent-team` create its own window, with no launcher pane left behind. Presentation is chosen at launch and never mixed mid-session. The Agent menu includes **Usage summary** (`u`) to open plan limits and token usage for its current CLI, including when the narrow status bar hides the usage badge. Codex labels this **Usage & reset cards** when the `codex-reset-card` skill is installed. Its Usage menu offers **Schedule card · 5 min before expiry** and **View / adjust scheduled tasks**. These prefill complete requests for that skill in the opening Codex pane; press Enter to submit. Scheduling chooses the earliest-expiring available card and reuses an existing task for that card. The skill owns persistent scheduling and redemption receipts. The Host menu shows the current machine's hostname above its SSH destinations. The Agent menu belongs to the pane from which it was opened. It identifies the live foreground CLI from its process ancestry and offers provider-specific commands: goal, side question and Codex Fast where supported. Installed `grill-me` and `handoff` skills are pinned alongside them. Planning, compaction, session branching, status, configuration and Botmux live under **More**. Shells, background or noninteractive agents, approval prompts, unknown states, and tmux copy mode do not receive slash commands. Working agents get only documented busy-safe shortcuts. Commands **prefill without Enter** and do not erase an existing draft; review the input in the CLI before submitting. Replacing the process invalidates an open menu's callbacks. Reopening the menu rechecks status. For pane teams, **Team members & progress** shows roles and member-reported status from `agent-team`, lets you focus any live member, and restores the main-vertical layout (`prefix Alt+4`). Native subagents remain managed inside the coding CLI. The status bar and `prefix+m` / `prefix+M-t` share the Workbench menu and custom menu component, including touch behavior and small-screen pagination. See [menu design and validation](docs/menus.md) for the interaction map and capability boundaries. `tmux-agent-workbench menu` and `prefix+m` / `prefix+M-t` open the unified Workbench menu. Each submenu returns to that menu. The source pane and client may also be supplied explicitly with `--pane` and `--client`. Status-bar menus open after `MouseUp`. Workbench, Host, Agent, Usage, Resources and Sidebar menus all use the same Menu model. Menus have two-row buttons and a content-sized popup capped at 60 columns. Menus share Sidebar's wheel/drag, keyboard and release handling; held presses never open the next menu early. Wheel moves the selection even when the list fits, and scrolls to keep it visible. Hover highlights both entries and pinned controls. Back/Close and Launch remain visible on short screens. Information and blank taps inside the menu leave it open. Clicking the muted backdrop closes on release without clicking through; outside hover, wheel and drags leave it open. Escape or Close also dismisses it. Context menus dismiss when the terminal viewport changes; the scoped lists retain their search and resize behavior. Long Host/member lists remain scrollable after their shortcut keys run out. Set `@workbench-usage-source` to `codex`, `claude`, `trae`, or `opencode` (default `codex`). Set `@workbench-usage off` before the plugin loads to omit the usage suffix while retaining the Agent Status capsule and focus behavior. The compact quota row displays the backend-reported plan type alongside the remaining quota and reset time. Reset cards show the available count and the nearest known expiry. No subscription multiplier is inferred from the plan name. Usage refreshes in the background every ten minutes while the status bar is rendering. Choose **Refresh now** (`r`) in the Usage menu to bypass the cache. Codex plan limits come from `account/rateLimits/read` via `codex app-server`, not session logs; this requires `codex` and Python 3 on the tmux server's PATH. All windows share the cache under `$XDG_STATE_HOME/tmux-agent-workbench/usage`. Failed quota requests retain the last successful reading with a `(stale)` label in the Usage menu. Requests time out after twenty seconds. Per-Agent manifest overrides live at `$XDG_CONFIG_HOME/tmux-agent-workbench/manifests/{codex,claude,trae,opencode}.toml`. One local file replaces that Agent's whole bundled manifest; Workbench does not download rules. See [the accepted v2 specification](docs/attention-v2.md) for the version-1 matcher and state semantics. ### Attention commands ```sh tmux-agent-workbench daemon ensure|status|stop tmux-agent-workbench daemon ensure --all tmux-agent-workbench snapshot --json tmux-agent-workbench resurrect save|restore tmux-agent-workbench agent explain %3 [--show-content] tmux-agent-workbench metadata report --pane %3 --label build --ttl-ms 5000 tmux-agent-workbench config check tmux-agent-workbench reload tmux-agent-workbench doctor ``` `daemon ensure` also hands off outdated resident sidebar processes for its tmux server. `--all` discovers running servers in the current runtime directory, so the installer can complete the handoff from a shell outside tmux. With no running servers it is a no-op; it never creates a tmux session. `resurrect save|restore` is the all-in-one assistant session layer for this plugin. Snapshot saving accepts both legacy tmux layouts and tmux 3.8 JSON layouts, removes ephemeral sidebars, and writes a legacy layout that tmux can restore across versions. Invalid conversions leave the original snapshot intact. It composes with `tmux-resurrect` and `tmux-continuum`, preserves the existing `assistant-sessions.json` data, restores Claude, Codex, OpenCode, Copilot, Pi, Oh My Pi, and Grok sessions, and uses Workbench's native hooks for Claude, Codex, OpenCode, and TraeX. No separate assistant-resurrect TPM entry is needed. The session adapters and their compatibility tests are maintained by Workbench; see [assistant session persistence](docs/assistant-sessions.md) for the supported formats, legacy options, and session-less relaunch controls. Pane teams are saved as a group and rebound to the restored panes before their sessions resume. This requires an `agent-team` version with `resume-pane` and the original team state under `$XDG_STATE_HOME/agent-team`. Each member resumes with its team instructions, model and permission options; saved prompts are not replayed. A missing session ID, unsupported saved option, missing team state, or an occupied target prevents that member or team from being resumed. Teams do not automatically restart stopped members; a member without one unique session remains unconfirmed and has no live pane. A verified lead remains a team group even when no worker is running. Teams saved before this feature have no team sidecar and cannot be reconstructed by this mechanism. The team sidecar is private, stays in the resurrect folder, and is bound to the exact snapshot and assistant session sidecars saved alongside it. Selecting an older snapshot without its matching sidecars will not restore it as a team. Capture a complete tmux-resurrect save (prefix then `Ctrl-s` with the default bindings); the assistant-only `resurrect save` command is not a replacement for saving the tmux layout. Like Herdr, Workbench renders one state per Agent pane. Claude `/btw` and Codex `/side` are classified from whichever thread is currently in the foreground; main and side threads are not shown as separate rows. Install the native lifecycle reporters explicitly after the binary is present: ```sh tmux-agent-workbench hooks install all tmux-agent-workbench hooks check all ``` Claude and TraeX JSON, Codex TOML, and the OpenCode XDG plugin are merged idempotently. Existing hooks (including Peon Ping) and unknown settings are preserved; `hooks remove` deletes only Workbench-owned entries. Hook processes send only lifecycle metadata (event id, Agent/pane/session/process identity, event type, timestamp, and reason category). They never scan transcripts or deliver notifications. If the daemon socket is briefly unavailable, reports are isolated by tmux server and spooled for at most 30 seconds. There is one detached daemon per tmux server. It keeps scanning when every sidebar is closed and exits when that server's socket disappears. Sidebar and picker refreshes only read its versioned Unix-socket snapshot; they do not run their own process scans, captures, or notifications. Native hooks are the lifecycle authority: prompt/busy means working, permission means blocked, and Stop/idle means done. A live Agent process exit without Stop is the other authoritative completion source. Screen/title matching remains a low-confidence estimate for hookless setups and lost-event diagnosis; estimated transitions are dimmed and can never create attention or notifications. Snapshot schema v1 keeps `base_state`/`display_state` and adds `state_source`, `confidence`, `estimated_state`, and `hook_health`. Codex automatic approval review displays as `working`, including when the pane title says `Action Required`. The detector checks the live review overlay before classifying that title. For hook-backed permission requests, the lifecycle state is retained while the working display temporarily suppresses input attention; a subsequent human approval prompt restores the blocked display and attention. All outgoing channels use one notification pipeline: the state machine supplies attention, `NotificationScheduler` rechecks it after one second, and `NotificationPipeline` routes the resulting semantic event to a client or the local/legacy-relay fallback. Automatic review suppression, cancellation, expiration, and acceptance deduplication run before transport selection. A channel switch cannot replay an accepted event. Client queues are revalidated again before dequeue; obsolete relay retries are cancelled too. Restored attention must agree with the reconciled live snapshot before it can notify. Adapters handle platform rendering, framing, and transport retries only. Workbench also consumes two non-lifecycle CESP signals without changing the canonical pane state: `session.start` is silent on every channel, while native failure events and failed `PostToolUse` payloads produce `task.error` through the same pipeline without the attention debounce. The legacy HTTP relay protocol continues to support only `task.complete` and `input.required`. Raw tool payloads are inspected only inside the short-lived reporter and are never sent to the daemon or persisted. OpenPeon categories are resolved from the active pack, so a separate notification hook such as Peon Ping is not required. ### Client-aware SSH from Termux Install the Termux:API Android app from the same signing source as Termux, then install its CLI package and allow Android notification permission: ```sh pkg install termux-api tmux-agent-workbench client setup termux termux-notification --title Test --content 'Workbench notification' ``` Use Workbench as the SSH entrypoint instead of attaching through plain `ssh`: ```sh tmux-agent-workbench client attach devbox tmux-agent-workbench client attach devbox --session my-task ``` The command keeps an authenticated control channel beside the interactive PTY. Completion, input-required, and task-error events from the devbox are delivered through `termux-notification`; tapping one brings Termux to the foreground and uses that control channel to switch the attached remote tmux client to the event's exact session, window, and pane. Closing the SSH attachment removes the endpoint. No listening port, reverse tunnel, or third-party push provider is required. The same authenticated channel can open a web link on the invoking device: ```sh tmux-agent-workbench client open-url --client /dev/pts/9 'https://example.com/?x=1&y=2' ``` Pass the actual `#{client_name}` from a tmux key binding. Routing uses that client's exact authenticated attachment, so another phone or desktop viewing the same session cannot receive the request. The client runs `termux-open-url` on Android, `open` on macOS, `xdg-open` on Linux, or the Windows URL handler through PowerShell in WSL. This works independently of the terminal emulator's OSC extensions. Only HTTP and HTTPS URLs are accepted. POSIX helpers receive the URL as one process argument; WSL uses a quoted PowerShell string literal. The command returns the local helper's success or error. Delivery is bounded and a timeout never retries an open automatically. Both ends need the URL-opening capability. After updating a client, reconnect its SSH attachment to advertise it; existing clients without the capability receive a clear upgrade message rather than opening on the server. Compatible clients negotiate a one-second control heartbeat for prompt explicit actions; older clients retain the previous heartbeat interval. URL requests and results are transient memory only and are not checkpointed or added to snapshots. An established attachment stays connected when optional daemon updates fail. If the daemon restarts or forgets a temporarily offline client, its next heartbeat restores the live terminal's registration and binding. Optional failures are recorded in the server's private Workbench daemon log instead of being printed over the terminal. A superseded or closed terminal cannot reclaim a newer one. Reconnects restore the last session, window, and pane for that device and terminal. An explicit `--session` takes precedence. History lives in the target tmux server, survives Workbench daemon restarts, and expires with that server; closed panes fall back to their window, then session. Plain SSH can invoke `tmux-agent-workbench client attach` on the server: without a client identity, it uses the server's last detached target as a shared fallback. With no sessions, the local entrypoint creates one. ### Attach to a Mac without running its SSH server For a tmux host that cannot accept SSH, Workbench can keep a TLS connection from the host back to a broker on the Devbox. The broker joins that stream to a phone terminal that entered the Devbox through `ssh-connect --workbench`. The Mac agent attaches a PTY to its existing tmux server; sessions remain on the Mac. Install a Workbench build containing the `client stream` and `client route` commands on the Devbox and Mac before configuring the route. The phone continues to use its existing `ssh-connect --workbench` entry into the Devbox. The phone-to-Devbox hop uses SSH as before. On the Mac, Workbench asks the existing Machine Fabric Executor to maintain an SSH local forward to the Devbox's loopback broker, then carries the terminal stream over TLS inside that forward. This needs an outbound SSH client on the Mac; the Mac's SSHD stays closed. It does not require a Machine Fabric binary change. Python 3.8 or newer is required on the Devbox and Mac for the embedded standard-library TLS and PTY helper. Create a CA and server certificate on the Devbox, then copy the public CA certificate and the target's mode-0600 pairing token to the Mac through a trusted setup channel: ```sh mkdir -p ~/.config/tmux-agent-workbench/remote-terminal cd ~/.config/tmux-agent-workbench/remote-terminal openssl req -x509 -newkey rsa:3072 -nodes -sha256 -days 3650 \ -subj '/CN=workbench-relay-ca' -keyout ca.key -out ca.pem \ -addext 'basicConstraints=critical,CA:TRUE' \ -addext 'keyUsage=critical,keyCertSign,cRLSign' \ -addext 'subjectKeyIdentifier=hash' \ -addext 'authorityKeyIdentifier=keyid:always,issuer' openssl req -new -newkey rsa:3072 -nodes -sha256 \ -subj '/CN=workbench-relay' -keyout server.key -out server.csr printf '%s\n' 'basicConstraints=critical,CA:FALSE' \ 'keyUsage=critical,digitalSignature,keyEncipherment' \ 'extendedKeyUsage=serverAuth' \ 'subjectKeyIdentifier=hash' \ 'authorityKeyIdentifier=keyid,issuer' \ 'subjectAltName=DNS:workbench-relay' > server.ext openssl x509 -req -in server.csr -CA ca.pem -CAkey ca.key -CAcreateserial \ -days 3650 -sha256 -extfile server.ext -out server.pem chmod 600 ca.key server.key ``` On the Devbox, configure the broker on a loopback high port and generate a random token. Keep the broker running under a user service or supervisor: ```sh tmux-agent-workbench client stream server-configure \ --bind 127.0.0.1:48765 \ --certificate ~/.config/tmux-agent-workbench/remote-terminal/server.pem \ --private-key ~/.config/tmux-agent-workbench/remote-terminal/server.key tmux-agent-workbench client stream target-add MacBook-Pro \ --endpoint 127.0.0.1:48765 --server-name workbench-relay \ --ca-certificate ~/.config/tmux-agent-workbench/remote-terminal/ca.pem tmux-agent-workbench client stream pair MacBook-Pro tmux-agent-workbench client stream serve ``` On the Mac, install the matching token and CA file with mode `0600` for the token, then configure the local forward. `client stream agent` uses the local Machine Fabric CLI to call `tunnel.ensure` on the selected Mac Executor. Replace `MF_EXECUTOR_ID` and `DEVBOX_SSH_ALIAS` with the values in the Mac's existing Machine Fabric configuration. Include `~/.local/bin` and the Homebrew binary directory in launchd's `PATH` so Workbench can find Machine Fabric and `tmux` (`/opt/homebrew/bin` on Apple Silicon): ```sh tmux-agent-workbench client stream target-add MacBook-Pro \ --endpoint 127.0.0.1:48766 --server-name workbench-relay \ --ca-certificate ~/.config/tmux-agent-workbench/remote-terminal/ca.pem \ --token-file ~/.config/tmux-agent-workbench/remote-terminal/MacBook-Pro.token \ --machine-fabric-executor MF_EXECUTOR_ID \ --ssh-host DEVBOX_SSH_ALIAS \ --forward-to 127.0.0.1:48765 tmux-agent-workbench client stream agent MacBook-Pro ``` Stop the managed SSH forward when the Mac agent should no longer reach the broker: ```sh tmux-agent-workbench client stream tunnel-stop MacBook-Pro ``` On the phone, add `Mac` to the existing `ssh-connect` host inventory and map that alias to the Devbox route. Use the Devbox SSH alias already present in the phone's `ssh-connect` inventory in place of `DEVBOX_SSH_ALIAS`: ```sh tmux-agent-workbench client route add Mac --via DEVBOX_SSH_ALIAS --target MacBook-Pro ssh-connect --workbench ``` The route record is stored under `$XDG_CONFIG_HOME/tmux-agent-workbench` with mode `0600`. The broker authenticates each target with a random per-target token, verifies TLS against the configured CA, and relays separate input and output streams. The existing Devbox SSH login remains the phone's entrypoint; the Mac has no SSH listener, and the broker stays bound to Devbox loopback behind the Machine Fabric SSH local forward. When the Devbox's release-managed core does not yet include `client stream`, a route can select a local core only for that alias. Stage an executable on the Devbox and pass its absolute Devbox path when adding the Mac route: ```sh tmux-agent-workbench client route add Mac \ --via DEVBOX_SSH_ALIAS --target MacBook-Pro \ --remote-core /home/USER/.local/bin/tmux-agent-workbench-core-mac-route-local ``` The Mac route executes that absolute binary path directly on the Devbox. Other routes continue to use the normal `tmux-agent-workbench` launcher and the release-managed core. Each terminal attachment has its own identifier and its own Mac PTY. Multiple phones or terminal windows can attach at the same time; each attachment forwards its own size changes to a separate tmux client, so tmux applies its normal multi-client sizing behavior. The phone only routes its terminal through the Devbox and does not speak this stream protocol directly, so protocol-only changes do not require reinstalling the phone CLI. The `--remote-core` route option is implemented by that CLI, so enabling this override requires a Termux build that supports the option. After responsive sidebar/zoom maintenance settles, Workbench refreshes the client and sends one `SIGWINCH` to the active pane's foreground process group. The same maintenance runs when the client switches sessions or windows. If the window's recorded size and layout geometry disagree, maintenance reapplies the recorded size and restores the original window sizing policy, so pane PTYs receive the actual dimensions before the foreground process is notified. This optional compatibility notification does not change terminal dimensions; disable it with `set -g @workbench-attach-refresh off`. A signal being delivered does not prove that an application's stale-rendering bug has been fixed. Clients attached to the same tmux session share window selection and pane dimensions. With `window-size latest`, the most recently active client determines the window size; desktop navigation can therefore move and resize a phone's view. Each local terminal has its own identity and attachment. Multiple Termux tabs on the same phone can connect simultaneously. Reconnecting from the same terminal replaces only that terminal's old remote client. A local terminal lock prevents two Workbench connections from writing to the same terminal; close the existing connection before starting another there. Notification actions are scoped to the connection that received them. Clients attached to the same tmux session still share its selected window. Use `--session` with different sessions when independent navigation is needed. This does not change tmux's shared pane layout or zoom semantics. Upgrade the remote Workbench installation before upgrading clients: the Hello message now includes an optional `terminal_id`. Updated servers accept older clients without that field, but do not evict connections by device ID or infer which old terminal they should replace. Older servers reject the new field; the updated client cleans up that failed connection instead of falling back to device-wide replacement. Both ends need updating for terminal-aware reconnects. ### Legacy SSH notification relay Run one user-level listener on the laptop (under launchd, systemd --user, or a terminal supervisor), then pair each SSH config host alias independently: ```sh tmux-agent-workbench relay serve tmux-agent-workbench relay pair devbox tmux-agent-workbench relay doctor devbox ``` `pair` prints the required SSH stanza, for example `RemoteForward 19999 localhost:19999`; it never edits `~/.ssh/config`. `relay doctor` checks the alias and probes that reverse tunnel from the remote. Use `relay rotate devbox` to atomically replace its token and `relay revoke devbox` to remove the pairing. Tokens are stored mode 0600. The listener accepts only authenticated CESP `task.complete` and `input.required` events at `POST /v1/events`, with a 16 KiB limit and rate limiting. Notification clicks map the stored remote id back to the SSH alias and execute only Workbench's validated fixed focus command. On macOS the click first focuses the interactive terminal tab running that SSH host, then switches the matching remote tmux client to the exact target window and pane. Remote arguments are POSIX-shell quoted before OpenSSH transports them, so opaque tmux ids such as `$11` are not expanded by the remote login shell. ### Migration from tmux-agent-sidebar Remove the old `tmux-agent-sidebar` TPM item, hook installer/updater calls, hooks containing its path, and obsolete rich-UI options before enabling v2. Do not load both plugins: Workbench refuses to create a second sidebar, and `tmux-agent-workbench doctor` prints the remaining cleanup steps. V2 does not modify Claude, Codex, Trae, or OpenCode hook/config files; optional metadata is reported through the TTL-bound command above. ## Commands ### Public workflow API All callers use `tmux-agent-workbench`. `pick project` opens the tmuxinator project picker; `pick session` opens the running-session picker. The dispatcher owns the mapping to private `wb-*` implementations. Legacy aliases only forward to this public API and are retained for compatibility through 2.1. ### Layer 1 — repo-agnostic (`bin/`) - **`tmux-agent-workbench agent start --managed`** — launches the current task's agent (`$WORKBENCH_AGENT`: `claude`, `codex`, `trae`, or `opencode`). New task windows launch this automatically. Agent/profile pane metadata supports handoff. - **`tmux-agent-workbench inspect [--git|--editor|--shell] [--pane]`** — opens one temporary tool, in a popup by default or a supporting pane with `--pane`. A file path opens that file in `$VISUAL` / `$EDITOR` (falling back to Neovim or Vim); directories default to the Git tool. For example, `tmux-agent-workbench inspect ./README.md --pane` previews the file on the right. To run a particular tool, use `tmux-agent-workbench inspect [--pane] -- `, for example `tmux-agent-workbench inspect . --pane -- lazygit` or `tmux-agent-workbench inspect . --pane -- less build.log`. Arguments after `--` are passed literally; use an explicit `sh -c '...'` for shell syntax. This command form cannot be combined with `--git`, `--editor`, or `--shell`. Use a popup for a quick interaction and a pane for human input, side-by-side reading, or temporary log observation and debugging. For a password or login prompt, identify or focus the returned pane so the user can type there. Panes use `main-vertical`: the main pane stays on the left and supporting panes share the right column's height, preserving the sidebar. Exit the tool to close its pane and rebalance the remaining tools. A manually changed layout is kept. It creates no persistent inspection window. Legacy `--focus`/`--force` flags are accepted without recreating inspection windows. - **`tmux-agent-workbench pick repo [--git|--editor|--shell]`** — selects a directory for a temporary tool. Within a task it lists that task's checkouts; elsewhere it uses directory history and configured project roots. It does not add repos or send commands to another agent. - **`tmux-agent-workbench run [--name