Skip to main content
Glama

rex_run

Run a command in a new unfocused block, optionally wait for exit and capture output, or keep it open for dev servers and interactive agents.

Instructions

Run a command in a new block (a new window, or a split beside anchor_block). Never takes focus. With wait_seconds, wait until the command exits, return its screen as output, and close the block (and its window, when this block was the only one). That is the default for a one-off command. Set keep_open true to leave the block up after it exits, for a dev server or an interactive agent. If the wait times out, the program is still running and the block stays open; close it with rex_block_close if you are done with it. Without wait_seconds the call returns once the block exists and does not close it. Rex closes that block when the program exits, unless keep_open is true. Nothing is closed for being idle. A long-lived program closes its own block when it finishes by running rex-mcp close (see the README). That command refuses wispy-fjord, tmux session claude-rc, and claude --remote-control.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "command": "<command>"
    },
    "name": "rex_run"
  }
}

Input Schema

NameRequiredDescriptionDefault
cwdNo
labelNo
ratioNo
splitNo
commandYesProgram and arguments, one word per element
sessionNoSession label or ID
keep_openNo
anchor_blockNoBlock label, ID, or ID suffix
wait_secondsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so well: it states that the tool never takes focus, explains waiting versus non-waiting behavior, describes block/window closing semantics, timeout behavior, idle behavior, keep_open behavior, and even refusal cases. These are concrete behavioral traits beyond the schema that materially affect safe invocation.

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 description is front-loaded with purpose and key defaults, and most sentences add behavioral value. It is somewhat dense and includes a tangential final detail about rex-mcp close refusing specific names, which could be trimmed or separated.

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

Completeness3/5

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

For a 9-parameter tool with no annotations, no output schema, and low schema coverage, the description covers the core execution and lifecycle model well. It still leaves important gaps around cwd, label, ratio, split/session semantics, and what identifier is returned when wait_seconds is omitted, so it is adequate but not complete.

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

Parameters3/5

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

Schema description coverage is only 33%, and the description compensates well for wait_seconds and keep_open, plus partially for anchor_block and splitting. However, it does not explain cwd, label, ratio, split direction values, or session behavior, leaving several parameters undocumented in both schema and description.

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?

The description gives a specific verb and resource: run a command in a new block, either a new window or a split beside anchor_block. It clearly states the primary effect, but it does not explicitly differentiate this tool from sibling alternatives such as sending keys/text to existing blocks.

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

Usage Guidelines4/5

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

It gives useful usage conditions: with wait_seconds it waits, returns screen output, and closes the block; keep_open is for dev servers or interactive agents; without wait_seconds it returns once the block exists. It also directs the agent to rex_block_close after a timeout, but it does not state when not to use this tool versus other execution or input tools.

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