Skip to main content
Glama
Sign In
computer-agent-labs

terminal-use

by computer-agent-labs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Wait for terminal

terminal_wait
Read-onlyIdempotent

Block until a terminal command finishes, output matches a regex, or output stays quiet, avoiding sleeps and polling.

Instructions

Block until the terminal reaches a state, instead of guessing with sleeps or polling terminal_read. Use it after terminal_type for anything that outlives the settle window: builds, installs, test runs, servers starting up.

DEFAULT (no pattern): waits for the running command to finish — i.e. for the shell to take the terminal's foreground back and its prompt to go quiet. This asks the kernel who owns the terminal, so it works with any prompt and stays correct while a command is silent (sleep 60) or chatty. Returns immediately if the shell is already at its prompt. On Windows this cannot be detected in a shell session: the call waits for a stretch of silence instead and says so — prefer pattern there. In a session created with command, it waits for that command to exit and reports its exit status. Background jobs (cmd &) do not count as running, and inside a nested program (ssh, a REPL, a TUI) the outer shell never regains the foreground until that program exits — use pattern there.

until: "quiet": waits until nothing has been printed for quietMs (default 1000), whatever owns the terminal. This is the same "settled" rule terminal_type uses, without its 10s cap — for nested programs where completion cannot be detected and no pattern fits.

WITH pattern: waits until the regex matches the text on screen (the viewport plus the 200 rows above it). Use this for servers that never exit ("Listening on"), REPL prompts, or TUI states. Text that is already on screen counts, so pick a pattern that only the new output can satisfy.

Returns the screen when the condition is met, or when timeoutMs runs out (not an error — the response says the command is still running). In a shell session this does not report an exit status; run echo $? afterwards if you need it.

Input Schema

NameRequiredDescriptionDefault
untilNo"command" (default): the running command has finished and the shell is back at its prompt. "quiet": output has been silent for `quietMs`. Ignored when `pattern` is given.
patternNoJavaScript regular expression matched against the screen text, lines joined with "\n" (e.g. "Listening on .*:3000", "^>>>\\s*$", "(?i)error"). `^` and `$` match at the start and end of each line; trailing spaces are trimmed from screen lines, so do not match a space after a prompt. Omit to wait for command completion.
quietMsNoHow long the output must stay silent. With until="command" (default 300) it applies once the shell is back in the foreground, so the prompt has finished drawing; with until="quiet" (default 1000) it is the whole condition.
sessionIdYesNumeric id of the session to target. Get one by calling terminal_create. Use terminal_list to enumerate currently-known ids.
timeoutMsNoGive up after this long. Default 30000, max 600000.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavior the annotations cannot: kernel-level foreground detection, platform-specific Windows fallback, background-job handling, nested-program limitations, and the critical fact that a timeout is not an error and reports the command still running. It even notes no exit status is reported in shell sessions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The text is long but well-structured, with labeled sections (DEFAULT, until: "quiet", WITH pattern) and the core purpose front-loaded. Most sentences carry a distinct edge case, though a few restate schema-documented details, keeping it just short of fully waste-free.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description steps in to explain the return ("Returns the screen when the condition is met, or when timeoutMs runs out") and the timeout semantics. Combined with the mode-specific behavior, an agent has everything needed to call it correctly across scenarios.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents each parameter, setting a baseline of 3. The description adds real guidance beyond the schema, such as the viewport-plus-200-rows match scope and the gotcha "pick a pattern that only the new output can satisfy," which meaningfully shapes correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: "Block until the terminal reaches a state." It explicitly distinguishes itself from the sibling terminal_read ("instead of guessing with sleeps or polling terminal_read"), so an agent can tell the tools apart without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use ("after terminal_type for anything that outlives the settle window: builds, installs, test runs, servers starting up") and when-not (complex nested programs, Windows shells, servers that never exit). It also names the alternative rule (terminal_type's settle window) and routes to `pattern` where the default cannot work.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools