Native tmux control surface for sessions, windows, and panes. Designed for automation and agent workflows.

arc-tmux sessions
arc-tmux panes --session dev --window 2
arc-tmux inspect --pane=dev:2.0
arc-tmux follow --pane=dev:2.0 --lines 200
arc-tmux launch "htop" --cwd /srv/app --env NODE_ENV=development
arc-tmux locate --field command node
arc-tmux monitor --pane=dev:2.0 --output json
arc-tmux ensure "npm test" --session dev --window build
arc-tmux signal --pane=dev:2.0 --signal TERM
arc-tmux stop --pane=dev:2.0 --timeout 20

All inventory-style commands support --output table|json|yaml|quiet.

JSON shape:

[
  {
    "name": "dev",
    "windows": 3,
    "attached": 1,
    "created_at": "2025-01-29T10:12:15Z",
    "activity_at": "2025-01-29T10:15:42Z"
  }
]

Filters: --command, --title, --path, --session, --window. Use --fuzzy for fuzzy matching.

JSON shape:

[
  {
    "session": "dev",
    "window_index": 2,
    "window_name": "api",
    "window_active": true,
    "pane_index": 0,
    "pane_id": "%5",
    "formatted_id": "dev:2.0",
    "active": true,
    "command": "bash",
    "title": "build",
    "path": "/Users/me/project",
    "pid": 1234,
    "activity_at": "2025-01-29T10:15:42Z"
  }
]

JSON shape:

{
  "pane": {
    "session": "dev",
    "window_index": 2,
    "window_name": "api",
    "window_active": true,
    "pane_index": 0,
    "pane_id": "%5",
    "active": true,
    "command": "bash",
    "title": "build",
    "path": "/Users/me/project",
    "pid": 1234,
    "activity_at": "2025-01-29T10:15:42Z"
  },
  "process_tree": [
    { "pid": 1234, "ppid": 1, "command": "bash", "depth": 0 },
    { "pid": 2345, "ppid": 1234, "command": "node server.js", "depth": 1 }
  ]
}

Streams NDJSON events (one object per line):

{ "time": "2025-01-29T10:15:42.123Z", "line": "Starting server..." }

By default follow emits only new lines after it starts (wrapped lines are joined for stability). Use --from-start to emit the full buffer first. --lines controls the capture size (0 for full). Use --duration/--timeout or --once to stop.

When --exit-code is enabled, run emits a sentinel exit code and parses it into structured output. Use --segment to capture only the output produced by the command (using start/end markers), and --exit-propagate to return a non-zero exit status when the parsed exit code is non-zero. Use --cwd to run from a specific directory and --env KEY=VAL to set environment variables.

{
  "output": "tests passed\n",
  "exit_code": 0,
  "exit_found": true,
  "wait_error": ""
}

Same shape as panes --output json, filtered by query and field. Use --fuzzy for fuzzy matching or --regex for regex matching.

Commands that accept --pane also support selectors:

• @current uses the current pane when inside tmux.
• @active uses the active pane across all sessions.
• @name uses a saved alias (see alias below).

Session selectors (for --session) support @current and @managed.

Create and use pane aliases for quick targeting:

arc-tmux alias set api --pane=@current
arc-tmux send "npm test" --pane=@api
arc-tmux alias list

arc-tmux recipes
arc-tmux recipes --output json

Sessions created by arc-tmux are prefixed with arc- when a new session is needed (existing sessions keep their original name). Newly created agent sessions receive distinctive styling and metadata for easy identification:

• Status bar + active window/pane styling
• @arc_tmux=1, @arc_tmux_owner, @arc_tmux_host, @arc_tmux_created_at
• ARC_TMUX=1 environment in the session
• Agent sessions default new windows to sh for predictable automation

When commands fail, errors include a stable code prefix for machine parsing (e.g. ERR_INVALID_PANE: ...).

Common codes:

• ERR_PANE_REQUIRED
• ERR_INVALID_PANE
• ERR_UNKNOWN_SELECTOR
• ERR_NO_ACTIVE_PANE
• ERR_NO_CURRENT_PANE
• ERR_NOT_IN_TMUX
• ERR_SIGNAL_UNSUPPORTED
• ERR_COMMAND_EXIT

Monitor a pane once for idle status and output hash:

arc-tmux monitor --pane=@current --idle 5 --lines 200 --output json

arc-tmux stop --pane=@current --timeout 20 --idle 3
arc-tmux signal --pane=@current --signal TERM

• Run a command and capture output:
  • arc-tmux run "make test" --pane=dev:2.0 --timeout 300 --output json
• Stream new output only:
  • arc-tmux follow --pane=dev:2.0 --lines 200
• Full buffer then follow:
  • arc-tmux follow --pane=dev:2.0 --from-start
• Send control keys:
  • arc-tmux send --pane=dev:2.0 --key C-x --key C-c
• Locate panes by command/title/path:
  • arc-tmux locate --field command node
• Ensure a window/pane exists without duplication:
• arc-tmux ensure "npm run dev" --session dev --window api --pane-title server --panes 2 --layout tiled

Integration tests require tmux and an isolated socket:

ARC_TMUX_IT=1 go test ./...