@cotal-ai/tmux

The tmux integration: a thin driver over the tmux CLI (open/close a window, send keys) plus a self-registering tmux Runtime and TerminalLayout provider. Importing it registers both with the core Registry, so the manager can spawn agents into tmux windows without depending on this package.

Tier: extensions/. Peer-depends @cotal-ai/core; self-registers on import.

What it does

• Runtime (tmux) — each agent gets its own window in a shared per-space tmux session (cotal-<space>). Spawned unfocused; switch to session:name to watch it. Env is isolated (env -i) so the tmux server's environment doesn't reach agents. That env is written to an owner-only launch script, which keeps it off tmux's command line, and the script removes its directory before it starts the agent. When it cannot remove the directory, the agent does not start. Graceful stop types /exit then kills the window; hard stop kills immediately. A close reads a window as already closed only from tmux's own can't find window or can't find session report and throws on any other failure, such as a missing socket. Exit waits poll the stable pane id and honor tmux's pane_dead state, including remain-on-exit; provider errors fail the wait closed. Each handle carries a reference to its tmux server, window and pane, so a later manager can reap the seat after the one that spawned it is gone. The reap closes the window while the session still holds it, even when the agent's pane already exited. It refuses a pane that has moved out of that window, whether it still runs or has exited, and a window that has moved out of the session, including one that moves while the reap runs.

• TerminalLayout (tmux) — opens/closes tmux windows for host-side orchestration (e.g. cotal setup). Detects the current session from $TMUX; must be called from inside a tmux session. Supports multi-pane tabs via split-window. Looking up tabs by label throws when tmux cannot be queried.

Usage

cotal ext add @cotal-ai/tmux
cotal supervise --runtime tmux

Library composition roots can instead import it explicitly:

import "@cotal-ai/tmux"; // self-registers; no other setup needed

Differences from @cotal-ai/cmux

cmux opens a per-agent workspace (tab) in the cmux app; this package opens a per-agent window in a tmux session. Both are native-watch (no PTY streaming). No cli.ts helper is included — tmux is always on PATH and needs no bundled binary path.

See docs/architecture.md (Manager) and the root AGENTS.md for the tier rules.