Python MCP reference

tool MCPstable

`capture_since`

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.

MCP request method: tools/call Send capture_since as the tool name, with the arguments below.

Arguments#

cursor? = null (string | null) #

Opaque cursor returned by a prior capture_since call. When omitted, the tool captures the current visible screen and starts a new cursor.
max_bytes? = 128000 (integer | null) #

Maximum UTF-8 bytes to return across lines. Defaults to CAPTURE_SINCE_DEFAULT_MAX_BYTES. Pass None to disable byte truncation.
max_lines? = 500 (integer | null) #

Maximum number of lines to return. Defaults to CAPTURE_SINCE_DEFAULT_MAX_LINES. Pass None to disable line truncation.
pane_id? = null (string | null) #

Pane ID (e.g. ‘%1’). Optional when cursor is supplied; the cursor carries the original pane id.
session_id? = null (string | null) #

Session ID (e.g. ‘$1’) for pane resolution.
session_name? = null (string | null) #

Session name for pane resolution.
socket_name? = null (string | null) #

tmux socket name.
window_id? = null (string | null) #

Window ID for pane resolution.

No other arguments are accepted.

Result#

This server does not advertise an output schema for this tool. Its description defines the returned content.

Annotations#

destructiveHint: true
idempotentHint: false
openWorldHint: true
readOnlyHint: false

Protocol data#

Use the complete advertised contract for validation and client integration.

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"
}

Scripting & web

Compiled & native

JVM

.NET

tmux

`capture_since`

Arguments#

Result#

Annotations#

Protocol data#