wait_for_text

Python

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

Wait for NEW output in a tmux pane, then return.

Polls until one of patterns appears on a line written after this call starts, one of stop appears (immediate failure exit), or the timeout expires. Pass patterns=null to wait for any new output at all. Use this instead of polling capture_pane in a loop.

Pre-existing scrollback is never matched, and neither is paint left below the cursor at entry — only rows written after the call began count. If a pattern was already on screen the result says so via matched_at_entry.

Last resort: reserve for output you did not author. Commands you send are AUTHORED — use run_command (returns exit status) or compose ; tmux wait-for -S <channel> with wait_for_channel instead, both cheaper and exact. For unattributable recurring prompts or background log lines, bracket your own command with a unique sentinel (cmd; echo __WAIT_$RANDOM__) and wait for that.

stop is the cheap way to avoid burning the whole budget: pass the failure markers you already know ("error:", "FAILED", "Traceback") and a failed run returns in milliseconds instead of at the ceiling.

The server caps timeout. An over-large value is not an error — the wait returns at the ceiling and reports effective_timeout.

All Python tools · JSON · Source

Arguments

interval optional · number: Seconds between polls. Default 0.05 (50ms). Minimum 0.01.
Default: 0.05.
match_case optional · boolean: Whether to match case. Default False (case-insensitive).
Default: false.
pane_id optional: Pane ID (e.g. '%1').
Default: null.
patterns optional: Success patterns; the first one to match ends the wait. Literal text unless ``regex=True``. Omit or pass ``null`` to wait for any new output.
Default: null.
regex optional · boolean: Interpret ``patterns`` and ``stop`` as regular expressions. Default False (literal text).
Default: false.
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.
stop optional: Failure patterns. A hit ends the wait immediately with ``outcome="stopped"`` and ``found=false``; ``matched_index`` says which entry fired.
Default: null.
timeout optional · number: Requested seconds to wait. Default 8.0. Clamped by server policy; see ``effective_timeout`` in the result.
Default: 8.
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": {
    "interval": {
      "default": 0.05,
      "description": "Seconds between polls. Default 0.05 (50ms). Minimum 0.01.",
      "type": "number"
    },
    "match_case": {
      "default": false,
      "description": "Whether to match case. Default False (case-insensitive).",
      "type": "boolean"
    },
    "pane_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Pane ID (e.g. '%1')."
    },
    "patterns": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Success patterns; the first one to match ends the wait.\nLiteral text unless ``regex=True``. Omit or pass ``null`` to\nwait for any new output."
    },
    "regex": {
      "default": false,
      "description": "Interpret ``patterns`` and ``stop`` as regular expressions.\nDefault False (literal text).",
      "type": "boolean"
    },
    "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."
    },
    "stop": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Failure patterns. A hit ends the wait immediately with\n``outcome=\"stopped\"`` and ``found=false``; ``matched_index``\nsays which entry fired."
    },
    "timeout": {
      "default": 8,
      "description": "Requested seconds to wait. Default 8.0. Clamped by server\npolicy; see ``effective_timeout`` in the result.",
      "type": "number"
    },
    "window_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Window ID for pane resolution."
    }
  },
  "type": "object"
}

Output schema

{
  "description": "Result of a bounded wait for new pane output.\n\nDeliberately free of inference. Every field is something the tool\nobserved directly — a match, a clock reading, a tmux flag. There is\nno \"likely cause\", no \"next action\", no quiescence verdict: a\nconfidently-wrong diagnosis costs the agent more than an honest\n\"nothing appeared, here is what the pane shows\".\n\nField count is load-bearing. ``outputSchema`` is re-sent on every\nrequest of every session, so a field that no agent branches on is a\npermanent tax. ``outcome`` carries what three separate booleans\ncarried before it.",
  "properties": {
    "alternate_screen": {
      "default": false,
      "description": "True when the pane was on the terminal's alternate screen at any point during the wait.",
      "type": "boolean"
    },
    "effective_timeout": {
      "description": "Seconds actually enforced. Server policy caps the requested ``timeout``; compare against what you passed to see a clamp.",
      "type": "number"
    },
    "elapsed_seconds": {
      "description": "Time spent waiting in seconds",
      "type": "number"
    },
    "found": {
      "description": "True when a ``patterns`` entry matched new output, or, with ``patterns=null``, when any new output appeared.",
      "type": "boolean"
    },
    "matched_at_entry": {
      "default": false,
      "description": "True when ``patterns`` already matched on-screen text before the wait began and nothing new matched after. The wait holds out for a FRESH occurrence, so re-running a command whose output looks identical still works. Read it as: the text is there, but it predates your call.",
      "type": "boolean"
    },
    "matched_index": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Zero-based index into ``patterns``, or into ``stop`` when ``outcome`` is ``stopped``. Null otherwise."
    },
    "matched_lines": {
      "description": "Newly-written lines that matched (empty on timeout).",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "outcome": {
      "description": "How the wait ended. ``matched``: a ``patterns`` entry hit. ``any_output``: ``patterns`` was omitted and something — possibly just a prompt repaint — was written; read it as 'the pane moved', never as 'the command finished'. ``stopped``: a ``stop`` failure marker hit. ``alternate_screen``: the pane was under a pager, editor, or full-screen TUI, which repaints the whole grid, so matching was suppressed — read the screen with snapshot_pane instead of retrying. ``timeout``: nothing matched in the budget.",
      "enum": [
        "matched",
        "any_output",
        "stopped",
        "alternate_screen",
        "timeout"
      ],
      "type": "string"
    },
    "pane_id": {
      "description": "Pane ID that was polled",
      "type": "string"
    },
    "saw_new_output": {
      "default": false,
      "description": "True when content was written on or below the entry cursor row. Read it with ``found=false``: true means output arrived and did not match — read ``tail`` and fix the pattern; false means the pane was quiet — suspect the command never ran, or check ``alternate_screen``.",
      "type": "boolean"
    },
    "tail": {
      "description": "Rows from the entry cursor row down at the final poll, tail-limited by lines and bytes. Includes stale rows excluded from matching, so it shows what the pane looks like, not what matched. On a timeout this usually already contains the answer — read it before retrying with a different pattern.",
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "found",
    "outcome",
    "pane_id",
    "elapsed_seconds",
    "effective_timeout"
  ],
  "type": "object"
}

Tool annotations

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