muxray

intent

muxray turns a live tmux pane into deterministic JSON so you can read what a program is doing without scraping raw terminal bytes. reach for it when you are supervising one or more interactive CLIs in tmux, especially terminal coding agents (Claude Code, Codex, Copilot), and you need to know what state a pane is in, what changed, or whose turn it is. output is JSON on stdout; errors are JSON on stderr. it runs locally with no network egress unless you explicitly call muxray update. pane content, which may hold secrets, never leaves the machine.

inputs

• tmux session/window/pane target: session name (e.g., work), full path (work:1.0), pane id (%3), session id ($0), or omitted to use the current pane if invoked inside tmux. pass as --pane <target> or --session <name>.
• muxray binary: installed via go install github.com/dandriscoll/muxray/cmd/muxray@latest. verify with which muxray and muxray doctor to check environment.
• tmux binary: required; muxray reads panes via tmux capture. must be running and have at least one session.
• snapshot file (optional): for diff and watch commands, a prior baseline captured via muxray snapshot --out <file> or a snapshot id stored in muxray's local store (usually ~/.cache/muxray/snapshots/ or similar; check muxray doctor).
• baseDir context: if using the wrapper script {baseDir}/scripts/muxray-run.sh, ensure that path is set at invocation time.

procedure

1. verify environment. run muxray doctor. confirm tmux is running, the binary is present, and the local snapshot store is writable. if any check fails, abort; output will include the specific error class and hint.

2. list all panes (optional fleet view). run muxray list to see every tmux session/window/pane in structured form. this is not required for single-pane operations but helps you find the right target when you have many sessions.

3. capture a baseline snapshot (if doing diff later). run muxray snapshot --pane <target> --out <file> to save the current pane state as JSON. the snapshot includes raw terminal bytes, cleaned text, and metadata. store the file path or note the snapshot id reported in the output.

4. classify a single pane's state. run muxray status --pane <target> to get the live classification: program (claude/codex/copilot/shell/unknown), status (idle/running/blocked/waiting_for_input/needs_approval/error/completed/unknown), confidence (0.0-1.0), and evidence (the footer line that decided the classification). parse exit code: 0 means success; non-zero codes (1-5) indicate failure. always check schema_version to ensure you are parsing the correct JSON shape.

5. wait for a pane to settle. run muxray watch --pane <target> [--until <states>] [--timeout <duration>] to block until the pane reaches a settled state. default --until waits for any of: idle, completed, needs_approval, waiting_for_input, blocked, error. narrow the wait with --until idle,needs_approval if you only care about specific outcomes. bound the wait with --timeout 5m to return after 5 minutes even if unsettled; exit code 5 indicates timeout. the command emits the final classification before exiting.

6. inspect one pane comprehensively. run muxray inspect --pane <target> to get snapshot, status, and diff (vs the latest stored baseline) in a single call. this is a convenience shorthand for the common "what is this pane doing and what changed?" question.

7. diff against a prior baseline. run muxray diff --pane <target> --since <file|id|latest> to compare the live pane against a prior snapshot. --since accepts a file path (from step 3), a snapshot id (reported by prior snapshots), or omit it to use the most recent stored snapshot. output includes changed (boolean; both true and false are exit 0), summary (plain english diff summary), added (lines the program output), removed (lines that scrolled off), hunks (count of distinct change regions), and snapshot ids. interpret changed: false as deterministic and reproducible across machines; a spinner or timer line flip is a cosmetic 1-line change, not progress.

8. scan the entire fleet (all panes). run muxray scan [--text] to classify every tmux pane in one call. output is { "panes": [ { "target": "%3", "session": "work", … "classification": {…} } … ] }. pane ids in target can feed directly back into status/watch/diff. a pane that can't be read returns unknown with an error class rather than failing the whole scan. --text gives a terse one-line-per-pane human view instead of JSON.

9. invoke via safe wrapper (optional but recommended). for untrusted pane/session targets from context variables, use {baseDir}/scripts/muxray-run.sh <command> <flags> instead of calling muxray directly. the wrapper validates the target and restricts you to read-only subcommands. for fully-supervised, literal targets you control, call muxray directly. in both cases: fixed subcommand, explicit --pane/flags, never interpolated shell strings.

10. use the canonical watch-diff-inspect wrapper (optional). run {baseDir}/scripts/muxray-watch-diff.sh --pane <target> to run the sequence: baseline snapshot, wait until settled, diff against baseline, classify. this prints all three results in one call, summarizing a single agent's working turn.

decision points

• if you need to send input / approve a prompt / type a command: do not use muxray. instead use the tmux skill with tmux send-keys. muxray is read-only; it observes panes, never sends keystrokes or mutates sessions.

• if the pane classification is needs_approval or waiting_for_input: the agent is paused on a human decision. surface the prompt to the user and stop. do not auto-approve; route to a human.

• if the pane classification is error: the agent hit a hard failure. check the evidence field for the error line. either restart the agent or alert the user depending on the task. if program=shell, the agent exited and dropped to an interactive shell prompt, which is program=shell/status=idle, not an agent error state. relaunch the agent, do not assign to a live agent.

• if the pane classification is running: the agent is actively working. do not interrupt it. call muxray watch --pane <target> to block until it settles, then re-classify.

• if the pane classification is unknown with a recognizable agent name in scrollback: the live frame scrolled away or the pane is mid-redraw. call muxray status --pane <target> again; if still unknown, fall back to reading the tail_excerpt from a snapshot yourself or check the --explain trace for diagnosis.

• if you have many panes to monitor: run muxray scan --text to get a one-line fleet view. call out only the panes that need action (non-idle, error, needs_approval). do not sweep unrelated sessions for its own sake.

• if diff returns changed: false: the pane has not produced new output since the prior snapshot. this is deterministic and reproducible; changed: false is not an error, just a fact. a cosmetic spinner line or elapsed-timer change is a tiny 1-line diff; treat it as "still working" unless the status changed.

• if watch times out (exit code 5): the pane never reached a settled state within the timeout window. the last-seen classification is still emitted. decide whether to increase --timeout and retry, or abort the task.

• if the snapshot store is full or unwritable: muxray doctor will report it. muxray keeps local snapshots in ~/.cache/muxray/snapshots/ by default (check muxray doctor output for the actual path). clean up old snapshots manually or configure a cleanup policy.

• if you see schema_version other than "2": the JSON shape may have changed in a newer muxray version. do not assume the old parsing logic applies. upgrade muxray or branch on the version string to handle both old and new formats.

• if pane text contains secrets (tokens, API keys, .env echoes): muxray does not redact snapshot.raw, snapshot.clean, diff lines, or tail_excerpt. you must manually summarize or redact obvious secrets before showing output to the user or sending it anywhere external. prefer reporting classification fields (program, status, evidence) over raw pane dumps. pass --no-raw to drop the raw capture from a snapshot.

• if you are performing observation as part of an agent control loop, not operator maintenance: do not call muxray update, telemetry, or bundle --include-excerpt. those are operator actions that may perform network egress or read large excerpts. stick to read-only status, watch, diff, inspect, and scan for agent steps.

output contract

• exit code 0: command succeeded. changed: true or changed: false in a diff are both exit 0. JSON on stdout follows the envelope schema below.

• exit codes 1-5 on failure:

  • 1: internal error (parsing, store corruption, etc.); stderr carries error.class and error.hint.
  • 2: usage error (bad flags, missing required arg); stderr carries error.class and error.hint.
  • 3: tmux/capture error (tmux not running, pane does not exist, can't capture); stderr carries error.class and error.hint.
  • 4: snapshot not found (a --since file or id does not exist).
  • 5: watch timed out (pane did not settle within --timeout); the last-seen classification is still emitted on stdout.

• JSON envelope (all commands):

  {
    "schema_version": "2",
    "command": "status",
    "muxray_version": "v1.2.3",
    "generated_at": "2025-01-15T14:32:10Z",
    … (command-specific fields below) …
  }
  

• status and inspect output: includes classification object:

  {
    "program": "codex|claude|copilot|shell|unknown",
    "status": "idle|running|blocked|waiting_for_input|needs_approval|error|completed|unknown",
    "rule_id": "codex.running",
    "confidence": 0.88,
    "evidence": "Working (esc to interrupt)"
  }
  

• list output: structured session/window/pane hierarchy:

  {
    "sessions": [
      {
        "name": "work",
        "id": "$0",
        "windows": [
          {
            "index": 1,
            "name": "editor",
            "panes": [
              {
                "id": "%3",
                "index": 0,
                "width": 120,
                "height": 40
              }
            ]
          }
        ]
      }
    ]
  }
  

• diff output: includes changed (boolean), summary (string), added/removed/context (line arrays), hunks (count), previous_snapshot_id, current_snapshot_id:

  {
    "changed": true,
    "summary": "5 lines added, 0 removed, 2 hunks",
    "added": [ "file.ts created", "$ " ],
    "removed": [],
    "context": [ "… working …" ],
    "hunks": 2,
    "previous_snapshot_id": "abc123",
    "current_snapshot_id": "def456"
  }
  

• snapshot output: includes id, pane, raw (full terminal bytes), clean (normalized text), tail_excerpt (last ~20 lines), timestamp:

  {
    "id": "abc123",
    "pane": "%3",
    "session": "work",
    "raw": "… full terminal content …",
    "clean": "… normalized text …",
    "tail_excerpt": "$ ",
    "timestamp": "2025-01-15T14:32:10Z"
  }
  

• scan output: fleet view with all panes:

  {
    "panes": [
      {
        "target": "%3",
        "session": "work",
        "window": 1,
        "pane_index": 0,
        "classification": { "program": "codex", "status": "running", … }
      }
    ]
  }
  

• watch output: blocks until settled, then emits final classification:

  {
    "classification": { "program": "codex", "status": "completed", … },
    "settled_at": "2025-01-15T14:33:20Z"
  }
  

• inspect output: combines snapshot, status, and diff:

  {
    "snapshot": { … },
    "classification": { … },
    "diff": { … }
  }
  

• error JSON on stderr:

  {
    "error": {
      "class": "tmux.pane_not_found",
      "hint": "pane %3 does not exist. run 'muxray list' to see active panes."
    }
  }
  

outcome signal

• single pane check: muxray status --pane <target> exits 0 and outputs a classification with program, status, and evidence. if status is running, the agent is working. if needs_approval or waiting_for_input, surface the prompt. if error, alert or restart. if idle or completed, assign the next task.

• wait for completion: muxray watch --pane <target> blocks, then exits 0 with the final classification. if exit code is 5, the pane did not settle within the timeout; check the last-seen classification and decide whether to continue waiting.

• detect change: muxray diff --pane <target> --since <baseline> exits 0 with changed: true if the pane produced new output, or changed: false if identical. read the summary and added lines to see what the program output. a 1-line cosmetic diff is "still working," not "made progress."

• fleet overview: muxray scan --text outputs one line per pane in human-readable format. look for non-idle, error, or needs-approval states. only panes flagged as needing action require further investigation.

• wrapper convenience: {baseDir}/scripts/muxray-watch-diff.sh --pane <target> runs the full sequence and prints a summarized turn report: baseline snapshot id, final classification, and diff summary. use it to confirm a single agent's turn is complete.

• secrets safety: before showing pane output to the user or sending it externally, check for tokens, api keys, or .env echoes in snapshot.raw, snapshot.clean, or diff lines. redact or summarize them. prefer reporting classification fields over raw pane dumps.