Skip to main content
Glama
Sign In
tmux-mcp

tmux-mcp

by vn-lazyming
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Read terminal

tmux_read
Read-onlyIdempotent

Reads recent terminal pane output, including scrollback, and can wait for a regex match or command completion. Use it to inspect live command results and pane status.

Instructions

Return the pane's last lines lines (what the human sees, plus scrollback), optionally waiting first. Last line: [at shell prompt] or [foreground: X], plus [timeout: ...] if the wait gave up.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "tmux_read"
  }
}

Input Schema

NameRequiredDescriptionDefault
linesNoHow many trailing lines to return, scrollback included.
timeoutNoMax seconds to wait.
wait_forNoPython regex; first poll until it appears in output since the last tmux_send in this pane, e.g. '(?m)^BUILD OK'. Anchor it with ^ so the typed command line itself doesn't match.
wait_doneNoFirst poll until the last tmux_send's command has finished (shell or REPL prompt back).
target_paneNotmux target such as "0:1.0" (session:window.pane, from tmux_list_panes); empty = the agent session "agent"

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds real value by disclosing exactly what content comes back (visible screen plus scrollback) and the shape of the trailing status line. Only the semantics of `[foreground: X]` and the timeout-indicator format remain unstated.

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?

Three short sentences with the core action front-loaded and no filler. The final clause describing the footer is compressed to the point of terse shorthand, costing a little clarity for its brevity.

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

Completeness4/5

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

An output schema exists, so return-value documentation is not required, and annotations carry the safety hints; the description covers the action, the optional wait, and the status footer. The main residual gap is that multi-pane targeting behavior is left entirely to the schema.

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 baseline would be 3, but the description adds the sequencing semantics — the wait happens before the read — which the schema does not convey on its own. It also ties the `lines` parameter to scrollback inclusion, though it adds no detail on timeout/wait_for beyond what the schema documents.

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

Purpose4/5

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

States a concrete verb and resource — return the pane's trailing `lines` lines, including scrollback and what the human sees — which is more specific than the title 'Read terminal'. It does not explicitly name tmux_send or tmux_list_panes, but the read-only framing makes the split from siblings obvious in context.

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

Usage Guidelines3/5

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

'optionally waiting first' and the `[timeout: ...]` footer imply the poll-then-read workflow, so the usage pattern is inferable but never stated as a rule. There is no explicit 'use this after tmux_send to check output' or guidance on when to prefer this over listing panes.

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