capture_since

Python

Python
Ruby Unavailable
Lua Unavailable
TypeScript
Rust
Go
Java
.NET
C++
Swift

Capture new tmux terminal scrollback since the previous cursor.

Use for observation-first workflows: tailing a shell, watching a long-running command, or repeatedly checking a tmux workspace pane without re-sending the same visible screen every turn. The first call with cursor=None returns the current visible pane and an opaque cursor. Later calls pass that cursor back and receive only rows written or rewritten after the cursor, as long as tmux still retains the required scrollback history.

If tmux history was cleared or trimmed before the cursor anchor, the tool returns the current visible pane with lines_missed=True and a fresh cursor. Malformed cursors, cursors for a different pane, pane death, and pane respawn fail with ExpectedToolError so agents do not accidentally observe the wrong process.

All Python tools · JSON · Source

Arguments

cursor optional: Opaque cursor returned by a prior ``capture_since`` call. When omitted, the tool captures the current visible screen and starts a new cursor.
Default: null.
max_bytes optional: Maximum UTF-8 bytes to return across ``lines``. Defaults to ``CAPTURE_SINCE_DEFAULT_MAX_BYTES``. Pass ``None`` to disable byte truncation.
Default: 128000.
max_lines optional: Maximum number of lines to return. Defaults to ``CAPTURE_SINCE_DEFAULT_MAX_LINES``. Pass ``None`` to disable line truncation.
Default: 500.
pane_id optional: Pane ID (e.g. '%1'). Optional when ``cursor`` is supplied; the cursor carries the original pane id.
Default: null.
session_id optional: Session ID (e.g. '$1') for pane resolution.
Default: null.
session_name optional: Session name for pane resolution.
Default: null.
socket_name optional: tmux socket name.
Default: null.
window_id optional: Window ID for pane resolution.
Default: null.

Schemas

The schema defines required fields, nested values, defaults, and validation constraints.

Input schema

{
  "additionalProperties": false,
  "properties": {
    "cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Opaque cursor returned by a prior ``capture_since`` call. When\nomitted, the tool captures the current visible screen and\nstarts a new cursor."
    },
    "max_bytes": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": 128000,
      "description": "Maximum UTF-8 bytes to return across ``lines``. Defaults to\n``CAPTURE_SINCE_DEFAULT_MAX_BYTES``. Pass ``None`` to\ndisable byte truncation."
    },
    "max_lines": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": 500,
      "description": "Maximum number of lines to return. Defaults to\n``CAPTURE_SINCE_DEFAULT_MAX_LINES``. Pass ``None`` to\ndisable line truncation."
    },
    "pane_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Pane ID (e.g. '%1'). Optional when ``cursor`` is supplied; the\ncursor carries the original pane id."
    },
    "session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Session ID (e.g. '$1') for pane resolution."
    },
    "session_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Session name for pane resolution."
    },
    "socket_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "tmux socket name."
    },
    "window_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Window ID for pane resolution."
    }
  },
  "type": "object"
}

Tool annotations

{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": true,
  "readOnlyHint": false
}