wavyrai/tmux-ide/skill

tmux-ide — Claude Code Skill

<!-- tmux-ide-skill-version: 2.6.0 -->

tmux-ide is the open-source tmux workspace for coding agents. The app (tmux-ide app) shows every agent across local and SSH machines with ground-truth working/blocked/done status, and drives the live tmux session. tmux-ide adopt adds the same status to plain tmux clients as tmux chrome: a status bar, keys and menus, all additive tmux options with no wrapper process. Around both: notifications when an agent needs a human, and crash-proof restore. tmux owns every process and pane, so sessions survive tmux-ide. .tmux-ide/workspace.yml is optional.

When to use

• User mentions tmux, a dock/status bar over sessions, an agent fleet, or session status
• User wants live working/blocked/done status across multiple agents or panes
• You are an agent and want to report your own status so the dock/fleet reflects it (the agent contract, below)
• Post-crash recovery — a tmux server died and the user wants their fleet + Claude conversations back
• User wants a git worktree (plus an adopted session) per branch
• User wants to set up a multi-pane dev workspace with .tmux-ide/workspace.yml

The agent contract

This is the core of tmux-ide. Detection is two-layer, and an agent that reports its own state is the authoritative layer — the dock trusts it over any screen-scraping. If you are an agent running in a tmux pane, self-report by setting a pane-local tmux option:

tmux set-option -p @agent_state "<state>:$(date +%s)"   # state = working | blocked | done | idle

The value is <state>:<unix-epoch>. A working/blocked report older than ~10 minutes is treated as stale (the detector falls back to Layer 2), so long-running agents should re-stamp periodically. Two optional companions:

tmux set-option -p @agent_session_id "<id>"   # your own session id — powers restore --resume-agents
tmux set-option -p @agent_hint claude          # force which agent manifest Layer 2 uses for this pane

Display metadata — say WHAT you're doing and WHO you are, right in the fleet UI. Two more optional pane-local options:

tmux set-option -p @agent_status_text "refactoring auth"  # one-liner, ≤32 chars — shows in the pane chip ("● claude · refactoring auth")
tmux set-option -p @agent_display_name "reviewer"          # your name — replaces the detected kind in sidebar rows & chips

Plain text only (control characters are stripped, tabs break the line for your pane — don't stamp them; anything past 32 chars is ellipsized). Both surface in tmux-ide team --json (per-pane statusText / displayName), the unified app's pane chips, and the sidebar agent rows. They follow the SAME staleness rules as @agent_state: they only show while your state stamp is fresh, so re-stamp @agent_state alongside — update the text whenever your focus changes, and it disappears with a stale/cleared state instead of lying.

Claude Code users get this for free — tmux-ide integration install claude writes a POSIX hook into ~/.claude/settings.json that stamps @agent_state on every lifecycle event (UserPromptSubmit/PreToolUse → working, Notification → blocked, Stop → done, SessionEnd → idle) and records @agent_session_id. It takes effect for new Claude Code sessions; the merge is reversible (integration uninstall claude).

Session-id capture for other kinds (what restore --resume-agents resumes from): codex and cursor-agent panes are stamped automatically — the chrome updater reads each CLI's own on-disk session state; opencode gets a plugin via tmux-ide integration install opencode. tmux-ide integration status shows what's active. Kinds without a verified resume story (gemini, aider, copilot, …) can self-report the id as above.

How detection layers work: Layer 1 is the authority above — a fresh @agent_state option is ground truth. When none is present, Layer 2 resolves the agent from the pane's process tree and reads the visible screen against evidence-tuned per-agent manifests to infer working/blocked/done. Run tmux-ide agent explain <pane> to see exactly which layer fired for a pane and why.

Coordinating with other agents

The status bus is shared, so you can work as part of a team — and the teammates don't have to be Claude Code. As an agent, you can:

tmux-ide team --json                     # fleet rollup: each session's + window's agent status
tmux-ide agent explain %2 --json         # one specific pane's status + why (per-pane read)
tmux-ide send %2 "do X, then run tests"  # task another pane's agent (by %id, title, role, or @ide_name)
tmux-ide wait output %2 --match "done"   # block until that pane prints something (exit 0 match / 1 timeout)
tmux-ide wait agent-status api --status done   # block until a whole session finishes
tmux-ide events --follow                 # subscribe to the live session-status transition stream

send types straight into the target agent's prompt (use --no-enter to stage text; pipe stdin for long input — messages over ~150 chars auto-route through a .tasks/dispatch/ file). Report your own status with the @agent_state contract above so teammates coordinating on you see the truth. This works across Claude Code, codex, cursor-agent, aider, or any CLI agent in a pane.

Fleet control from the CLI

Every command takes --json for structured output.

tmux-ide team --json                      # whole-fleet state: sessions, panes, agent statuses
tmux-ide events --follow                   # stream agent-status transitions (needs an adopted session)
tmux-ide events --json                     # recent transitions as JSON
 
tmux-ide wait agent-status <session> --status blocked --timeout 60000   # block until a session hits a status
tmux-ide wait output <pane|session> --match "<regex>" --timeout 60000   # block until a pane's output matches
 
tmux-ide send <target> "<message>"        # send text to a pane (by name/title/role/ID); --to <name>, --no-enter
tmux-ide agent explain <pane> --json       # debug how a pane's agent state was detected
 
tmux-ide adopt <session>                   # add the dock to an existing session (additive tmux config)
tmux-ide adopt --all                       # adopt every live session
tmux-ide unadopt <session>                 # remove the dock — sessions keep running as plain tmux
 
tmux-ide restore --dry-run --json          # preview rebuilding the fleet from the last snapshot
tmux-ide restore --resume-agents           # rebuild after a tmux crash; revive agent convos (claude/codex/cursor/opencode)
 
tmux-ide worktree create <branch> --from <ref>   # git worktree on a new branch + a session in it
tmux-ide worktree open <branch>            # open/switch to an existing worktree's session
tmux-ide worktree list --json              # worktrees joined with their session status
tmux-ide worktree remove <branch> --force  # kill the session + remove the worktree
 
tmux-ide update --dry-run                  # detect install method (dev checkout vs npm/pnpm/bun) and show/run the update
tmux-ide doctor                            # system + integration health (tmux version, TUI surfaces, skill freshness)

Drive tmux-ide over the socket (agent loops)

The CLI above spawns a process per call. If you are driving the fleet in a loop — polling status, waiting on agents, reacting to transitions — start the control server once and keep ONE connection open instead:

tmux-ide serve &   # local Unix socket at ~/.tmux-ide/control.sock (0600, this user only)

Frame format: newline-delimited JSON, one object per line. Send {"v":1,"id":<any>,"verb":"<verb>","params":{…}}; you get back {"v":1,"id":<same>,"ok":true,"data":…} or {"v":1,"id":<same>,"ok":false,"error":{"code","message"}}. Responses correlate by id (they may arrive out of order — a long wait doesn't block other verbs on the same connection). After the subscribe verb the server also PUSHES unsolicited {"v":1,"event":"agent-status","data":{ts,session,from,to}} frames the moment its detection tick sees a session change state — no polling.

Verbs: fleet (the team --json payload) · agents (per-pane entries, optional {session}) · send ({session,target,message,noEnter?,dir?}) · wait ({kind:"agent-status",session,status,timeoutMs?} or {kind:"output",target,match,timeoutMs?}; a timeout is an error response with code timeout) · spawn ({kind|command, session?|sessionName, dir?, placement?, paneId?} → the new paneId) · restart-agent / stop-agent ({paneId, kind|command}) · explain ({target}) · subscribe.

One-shot from a shell (nc keeps the pipe open for the response):

printf '{"v":1,"id":1,"verb":"fleet"}\n' | nc -U ~/.tmux-ide/control.sock | head -1

A subscribe loop from node:

const net = require("node:net");
const os = require("node:os");
const sock = net.connect(`${os.homedir()}/.tmux-ide/control.sock`);
let buf = "";
sock.on("data", (chunk) => {
  buf += chunk;
  const lines = buf.split("\n");
  buf = lines.pop();
  for (const line of lines.filter(Boolean)) {
    const frame = JSON.parse(line);
    if (frame.event === "agent-status") console.log(frame.data); // react here
  }
});
sock.write('{"v":1,"id":1,"verb":"subscribe"}\n');

Right after subscribe, the first tick reports every session once with from:null (a snapshot of where the fleet stands); real transitions follow.

Socket vs CLI: prefer the socket for anything event-driven or repeated (subscribe replaces an events --follow poll; a server-held wait costs no spawn-per-poll). Prefer the CLI for one-shot reads and anything a human might re-run — it needs no server. With a server running, tmux-ide events --follow --socket and tmux-ide wait … --socket use it automatically and fall back to polling silently when it's gone. The server is local-only by design: no network listener, no tokens — filesystem permissions are the auth.

Keys & surfaces to tell USERS about

Once a session is adopted, the whole UI is a keystroke away. Lead with the prefix — an agent pane can temporarily change key encoding and swallow a root-table Alt bind, but the tmux prefix always reaches tmux. Every surface has a prefix twin and an ⌥ fast-path (single keystroke when the terminal allows it). Right-click any pane or the bar opens the actions menu at the pointer.

One interaction grammar everywhere: j/k move, enter opens, / filters, esc backs out, ? asks. Bare tmux-ide with no project config opens the app (below). tmux-ide cheatsheet prints the full sheet.

The app — tmux-ide app

The full-screen app: tmux stays the engine (PTYs, agents, persistence); the app renders it. Launch tmux-ide app (Home) or tmux-ide app <session>. Installed releases include the runtime; tmux-ide update --tui-binary re-downloads it.