Capture since¶

Use when you need to observe the same pane repeatedly — tailing logs, watching a long-running command, checking a daemon, or revisiting a terminal without paying to re-read the same scrollback every turn. The first call returns the current visible screen plus a cursor; later calls pass that cursor back and receive only rows written or rewritten after it.

Avoid when you control the command and only need completion — compose tmux wait-for -S <channel> into the command and call wait_for_channel. If you need a one-shot content + metadata view, use snapshot_pane; if you do not know which pane contains text, use search_panes.

Side effects: None. Readonly.

Example:

Start a cursor with the currently visible screen:

{
  "tool": "capture_since",
  "arguments": {
    "pane_id": "%2"
  }
}

Response:

{
  "pane_id": "%2",
  "cursor": "capture-since-v1:...",
  "lines": [
    "$ pytest -vv",
    "tests/test_api.py::test_health PASSED"
  ],
  "elapsed_seconds": 0.003,
  "lines_missed": false,
  "truncated": false,
  "truncated_lines": 0,
  "truncated_bytes": 0
}

Read only content since that cursor:

{
  "tool": "capture_since",
  "arguments": {
    "cursor": "capture-since-v1:..."
  }
}

The cursor carries the original pane id, so the follow-up call does not need pane_id. If you pass both, they must match; a cursor for another pane raises a tool error instead of silently reading the wrong process.

If nothing new was written after the cursor, lines is empty and the response still includes a fresh cursor for the same pane. If the cursor row scrolled into retained history, the tool can still return an exact delta; retained scrollback is not a loss condition.

lines_missed becomes true when tmux has cleared or trimmed the history needed to compute an exact delta. In that case, lines is a conservative current visible capture and the response includes a fresh cursor.

Pane lifecycle is part of the cursor contract. If the pane dies or is respawned, the call raises a tool error instead of reading from a different process that reused the same pane id.

truncated, truncated_lines, and truncated_bytes are structured metadata. No truncation marker is injected into lines, so clients can display terminal text without parsing an in-band header.

The cursor is intentionally opaque. It is based on tmux grid state (history_size + cursor_y) and pane lifecycle fields (pane_id, pane_pid); see tmux’s grid and capture implementation in grid.c and cmd-capture-pane.c, and libtmux’s Pane.capture_pane().

Parameters