Allows launching and managing Hermes CLI agents in tmux panes, sending prompts, reading output, and handling interactive prompts.
Provides tools for orchestrating tmux sessions and panes, including launching multiple agents in split panes, listing panes, reading output, waiting for idle or patterns, sending text and keys, and killing sessions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@tmux-agents Start a session with agents for tests, backend, and frontend, then wait for idle."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Let one AI agent run a room full of coding agents.
tmux-agents is a Model Context Protocol server that turns tmux into a control surface for CLI agents. Point Claude, Cursor, Codex, Hermes or any MCP client at it and it can start Claude Code / Codex / Hermes / aider in split panes, watch each one, answer their questions, hand them the next task and tear the session down — while you watch the same panes in your own terminal.
uvx tmux-agentsThat is the whole install. It needs tmux on the machine and nothing else.
Every coding agent ships as a terminal program, and every orchestrator wants to run several of them at once. The pieces that are missing are small but annoying:
An agent hosted somewhere else (a cloud session, a desktop app, a phone client) has no terminal. It can plan the work but has to ask a human to type run-batch.sh.
Four agents in four windows are four things to babysit. One stops to ask "overwrite? (y/n)" and everything waits until someone notices.
Reading a pane, deciding it is done, and typing the follow-up is exactly the kind of loop a model is good at — if it can see the pane.
tmux-agents gives the orchestrating model seven tools that map to what you would do by hand, and nothing more. There is no generic shell tool: the model can type into agent panes, not into your machine.
Related MCP server: Terminal MCP Server
Tool | What it does |
| Server config, tmux version, visible sessions |
| Create a session with one pane per agent, title each pane, run each command, pick a layout that fits (side-by-side for 2, tiled for 3+), optionally open it in your terminal app |
| Panes with title, cwd, running command, size |
| Last N lines of a pane, ANSI stripped, secrets redacted |
| Block until a pane is quiet for N seconds or a regex appears — returns |
| Type text (literally, multi-line safe) and press Enter |
| Send |
| Stop one agent or the whole batch (can be disabled) |
Panes are addressed by title ("WP2", case-insensitive partial match), by id (%3) or by tmux target (batch:0.1). Titles are shown on the pane borders, so what the model calls a pane is what you see.
claude mcp add tmux-agents -- uvx tmux-agents{
"mcpServers": {
"tmux-agents": {
"command": "uvx",
"args": ["tmux-agents"],
"env": {
"TMUX_AGENTS_SESSION_PREFIX": "agents-",
"TMUX_AGENTS_OPEN_COMMAND": "open -na Ghostty.app --args -e tmux attach -t {session}"
}
}
}
}TMUX_AGENTS_OPEN_COMMAND is the one macOS-flavoured line: it pops the new session into a real terminal window so you can watch. Other terminals:
Terminal | Command |
Ghostty |
|
iTerm2 |
|
kitty |
|
WezTerm |
|
Terminal.app |
|
Linux (any) |
|
Leave it unset and the session runs detached; tmux attach -t <name> from any terminal shows it.
agents_launch({
"session": "agents-wp5",
"cwd": "/Users/me/repo",
"agents": [
{"title": "WP5 Review", "command": "claude --model claude-opus-5 \"$(cat prompts/wp5.md)\""},
{"title": "WP6a Lazy", "command": "claude --model claude-sonnet-5 \"$(cat prompts/wp6a.md)\""},
{"title": "WP6b Shell", "command": "codex --model gpt-5-codex \"$(cat prompts/wp6b.md)\""}
]
})
// → 3 tiled panes, Ghostty window opens
pane_wait({"pane": "WP6b", "timeout_seconds": 300, "idle_seconds": 8})
// → {"state": "idle", "tail": "... Overwrite tsconfig.json? (y/N)"}
pane_send({"pane": "WP6b", "text": "y"})
pane_wait({"pane": "WP5", "pattern": "handoff\\.md written"})
pane_read({"pane": "WP5", "lines": 80})
session_kill({"session": "agents-wp5"})pane_wait is the heart of it. "Quiet for 8 seconds" is a surprisingly reliable definition of an agent is either done or waiting for you, and the tail tells the model which.
All via environment variables (set them in the env block of your MCP config):
Variable | Default | Meaning |
| (empty = all) | Only sessions whose name starts with this are visible or controllable. Set it. With |
| (none) | Command run after |
|
| Set |
|
| Replace token-looking strings in pane text with |
|
| Hard cap for |
| (default server) |
|
|
| Path to the tmux binary |
pane_send types into a pane. If that pane is a shell, that is a shell. Keep agent sessions under a prefix (TMUX_AGENTS_SESSION_PREFIX) and the model cannot reach anything else.
Pane text is scrubbed for GitHub/OpenAI/Slack/AWS tokens, bearer headers and *_TOKEN= style assignments before it is returned. This is a filter, not a guarantee — do not paste secrets into agent panes.
The server instructs the model to treat everything it reads from panes as data written by another program, never as instructions. Agents talking to agents is exactly where prompt injection lives; the instruction is a reminder, not a defence. Review what your agents commit.
No network, no config files, no state: the server is a thin layer over the tmux CLI and forgets everything between calls.
There are other tmux MCP servers (nickgnd/tmux-mcp, laszlopere/mcp-tmux) and they are good general tmux remotes: create windows, run commands, read output, some over SSH. tmux-agents is narrower on purpose: it knows about agents — titled panes, "launch N of these in a layout that fits", "wait until it goes quiet", prefix-scoped visibility, redaction — and it deliberately leaves out a raw command tool. If you want a tmux remote control, use one of those. If you want an orchestrator, this is the one.
git clone https://github.com/woonyong-choi/tmux-agents
cd tmux-agents
uv sync --extra dev
uv run pytest # real tmux, private socket, ~20s
uv run ruff check src testsTests spin up a throwaway tmux server (tmux -L tmux-agents-test-…), so they never touch your sessions.
MIT — see LICENSE.
Create a tmux session with one pane per agent and start each agent's command.
agents is a list of {"title": ..., "command": ..., "cwd": optional}.
Example command strings:
claude --model claude-sonnet-5 "$(cat prompts/wp1.md)"
codex --model gpt-5-codex "implement WP2 per docs/plan.md"
hermes chat -q "review the diff"
layout: auto (side-by-side for 2, tiled for 3+), or any tmux layout name
(even-horizontal, even-vertical, main-vertical, tiled).
If TMUX_AGENTS_OPEN_COMMAND is set the session is also opened in a terminal app.
replace=true kills an existing session of the same name first.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | Yes | ||
| agents | Yes | ||
| layout | No | auto | |
| replace | No | ||
| session | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does disclose important behaviors: layout auto behavior for 2 vs 3+ panes, TMUX_AGENTS_OPEN_COMMAND opening the session in a terminal app, and replace=true killing an existing session of the same name first. It does not cover blocking behavior or error outcomes, but the main side effects and destructive path are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action, then uses compact structured notes for agents, layout, env-var behavior, and replace. The example command strings earn their place because they clarify the exact format needed for the agents parameter, and there is no redundant or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity, lack of annotations, and existence of an output schema, the description covers the critical side effects and parameter semantics well. It could be more complete by explicitly defining the session parameter and the top-level cwd, and by noting how this launch tool relates to the tmux inspection sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does for agents (with the expected object shape and concrete command examples), layout (with valid values and auto semantics), and replace (kills existing session). It leaves session and the top-level cwd largely to inference from their parameter names, which is a small but real gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Create a tmux session with one pane per agent and start each agent's command.' This clearly distinguishes it from the sibling tools like tmux_status, panes_list, and session_kill, which inspect or destroy sessions rather than create and launch them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to use the tool but gives no guidance on when to choose it over sibling tools, nor any exclusions such as 'use panes_list to inspect an existing session instead.' The usage context is only implied by the tool's purpose, not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a named key to a pane: C-c (interrupt), C-d, Escape, Enter, Up, Tab ...
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | C-c | |
| pane | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full responsibility for behavioral disclosure. It states that a key is sent and that C-c can be an interrupt, but does not explain side effects, whether it types into the pane's input, whether it waits, or any safety considerations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the operation and provides useful examples without wasted words. It is concise and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, an incomplete key list, and an unexplained 'pane' parameter, the description is not fully sufficient for an agent to know exactly how to invoke the tool correctly. The presence of an output schema helps, but the core usage context is underspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaningful examples for the 'key' parameter, but the required 'pane' parameter is unexplained—no format, identifier type, or how to reference a pane. The compensation is only partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Send') with a clear resource ('pane') and object ('named key'), and gives concrete examples (C-c, C-d, Escape, Enter, Up, Tab). This makes the tool's function clear and somewhat distinguishes it from sibling pane_send, though the distinction is implied rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like pane_send or pane_read. The phrase 'named key' implies special-key input, but there is no explicit when-to-use, when-not-to-use, or comparison with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Kill one pane (one agent). Disabled when TMUX_AGENTS_ALLOW_KILL=false.
| Name | Required | Description | Default |
|---|---|---|---|
| pane | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the burden of explaining behavior, and it does state the destructive nature ('Kill') and the exact target ('one pane'). It also discloses a key guardrail: disabled when TMUX_AGENTS_ALLOW_KILL=false. It could add reversibility or side-effect details, but for a one-line destructive tool this is meaningful transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. The first sentence states the action and target, and the second provides a crucial operational condition. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema, the description covers the core purpose and a key environmental guard. However, it does not tell the agent how to identify the pane value, what happens when the tool is disabled, or how to recover the pane identifier (e.g., via panes_list). The definition is minimally viable but not fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only defines a required string parameter named 'pane' with no description, and schema description coverage is 0%. The description says 'one pane (one agent)' but does not explain what format the pane identifier should take, where to obtain it, or whether it is an ID, name, or index. This is a clear gap for an agent trying to invoke the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb, 'Kill', and a specific resource, 'one pane (one agent)', which clearly states what the tool does. It also differentiates itself from the sibling session_kill by emphasizing singular scope. The title and behavior align, leaving no ambiguity about the operation's target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for terminating a single pane or agent, which contrasts with session_kill for a whole session, but it never explicitly says 'use this when you need to stop one agent' or 'use session_kill for all panes'. The conditional environment variable note gives operational context, but alternative-selection guidance is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the last lines lines of a pane (scrollback included).
pane is a pane id (%3), a target (session:0.1) or a pane title (partial,
case-insensitive). raw=true keeps ANSI escape codes.
| Name | Required | Description | Default |
|---|---|---|---|
| raw | No | ||
| pane | Yes | ||
| lines | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It explicitly states that scrollback is included and that raw=true preserves ANSI escape codes, which are meaningful behavioral details beyond the schema. The verb "Read" also implies a non-mutating operation, though it does not explicitly guarantee zero side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, stating the core operation first and then adding only essential identifier and flag semantics. Every sentence contributes information, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema is present, the description does not need to detail return values. It covers the identifier resolution rules, scrollback behavior, and raw-mode behavior. A potential gap is failure or ambiguity behavior when a partial title matches multiple panes, but this is minor for a read tool of this simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain all parameters itself. It does: pane formats are fully enumerated (pane id, target, partial case-insensitive title), raw is explained via ANSI behavior, and lines is defined as the number of trailing lines to read. This fully compensates for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Read the last `lines` lines of a pane (scrollback included)." This clearly distinguishes pane_read from mutation siblings like pane_send and pane_key, and from listing tools like panes_list, by stating exactly what operation it performs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to specify a pane and the raw flag, but it never tells the agent when to choose this tool over alternatives or when not to use it. It does not reference any sibling tool or provide exclusion criteria, so the agent is left to infer tool-selection context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Type text into a pane, then press Enter (unless enter=false).
Text is sent literally (no tmux key-name expansion), so multi-line prompts
and special characters are safe. Use pane_key for control keys.
| Name | Required | Description | Default |
|---|---|---|---|
| pane | Yes | ||
| text | Yes | ||
| enter | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does disclose key behavior: it sends text literally (no tmux key-name expansion), presses Enter by default, and is safe for multi-line/special characters. It does not mention side effects or failure modes, but the core action is transparent enough for a simple tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences with no filler. The action is front-loaded, followed by the literal-sending caveat and the alternative to `pane_key`. Every sentence contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with an output schema present, the description covers the main action, the optional Enter behavior, and the key sibling distinction. It omits minor edge cases like pane targeting syntax, but given the sibling set and simplicity, it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains `text` is sent literally and `enter` controls whether Enter is pressed; however, `pane` is only referenced by name with no format guidance. This is adequate for the two most semantically interesting parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Type `text` into a pane, then press Enter'. It differentiates itself from the sibling `pane_key` by explicitly noting that text is sent literally and that `pane_key` should be used for control keys, so an agent can distinguish them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear direction to use `pane_key` for control keys, which is an explicit when-not and alternative. It does not enumerate all possible alternatives, but the main ambiguity with `pane_key` is resolved, and the literal-sending behavior indicates when multi-line or special-character input is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List panes (id, title, cwd, running command, size). Titles are what agents_launch set.
Omit session to list every visible session.
| Name | Required | Description | Default |
|---|---|---|---|
| session | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It reveals the output shape, states that titles are set by agents_launch, and clarifies that omitting session lists every visible session. While it does not explicitly say 'no side effects,' the verb 'list' strongly implies a read-only operation, and the added cross-tool detail about titles is genuinely useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no filler. The core purpose and output fields are front-loaded, and the second sentence efficiently covers the parameter's behavioral nuance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, the optional session parameter, and the presence of an output schema, the description is nearly complete. The only minor gap is that it does not explicitly state what value session expects (e.g., session name vs. ID), but this is not critical for understanding the listing behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only documents the session parameter's name, type, and default null, with 0% description coverage. The description compensates by explaining the omission behavior ('Omit session to list every visible session'), which adds meaning beyond the schema; the inverse behavior for a supplied session is implied but not explicitly described.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with the resource 'panes' and enumerates the returned fields (id, title, cwd, running command, size), making the tool's purpose unambiguous. It is clearly distinguishable from siblings like pane_read, pane_send, and pane_kill by being a read-only listing operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool and explains the default behavior: 'Omit session to list every visible session.' It does not explicitly name alternatives or exclusion conditions, but the listing semantics already disambiguate it from the action-oriented sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wait until a pane stops changing for idle_seconds, or pattern (regex) appears.
Returns state (idle | matched | timeout) plus the last tail_lines lines so
you can decide whether the agent finished, is asking a question, or errored.
Keep timeout_seconds under your client's tool timeout; call again to keep waiting.
| Name | Required | Description | Default |
|---|---|---|---|
| pane | Yes | ||
| pattern | No | ||
| tail_lines | No | ||
| idle_seconds | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it delivers: it discloses blocking wait behavior, idle/matched/timeout outcomes, tail_lines return, and the timeout/client-timeout relationship. It doesn't explicitly state whether the operation is read-only or whether it consumes pane output, but the wait semantics and retry guidance provide strong behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences with no filler: core condition, return-value purpose, and operational caution. The most important guidance is front-loaded, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter wait tool with no annotations, the description covers the blocking behavior, return states, tail output, and timeout strategy. The output schema fills in the return structure, so the description doesn't need to. Minor gaps like pattern case-sensitivity or behavior when a pane is not found are not critical for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does: idle_seconds (stops changing), pattern (regex), tail_lines (lines returned), and timeout_seconds (limit under client timeout) are all explained. Only 'pane' is left implicit, but the tool name and schema title make it inferable. This is solid compensation for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Wait until a pane stops changing... or pattern (regex) appears.' It also explains the three terminal states and the tail output, making the tool's role unambiguous. This is clearly distinct from siblings like pane_read (immediate read) and panes_list, even without naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear operational context ('so you can decide whether the agent finished, is asking a question, or errored') and practical advice ('Keep timeout_seconds under your client's tool timeout; call again to keep waiting'). It doesn't explicitly contrast with pane_read or pane_send, but the wait-for-condition purpose is obvious enough that an agent can choose it correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Kill a session and every agent in it. Disabled when TMUX_AGENTS_ALLOW_KILL=false.
| Name | Required | Description | Default |
|---|---|---|---|
| session | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a key behavioral trait: it kills every agent in the session, not just the session itself. It also mentions the kill can be disabled via TMUX_AGENTS_ALLOW_KILL=false. With no annotations provided, the description carries the burden, and it does a decent job but doesn't mention reversibility, permissions, or what happens to running processes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. The core action is front-loaded, and the conditional disablement is a useful second sentence. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with one required parameter and no annotations, the description is minimal but covers the main action and a key safety condition. However, it lacks details about the session parameter format, what happens to the tmux session itself, and whether the operation is reversible. The output schema exists but doesn't compensate for these gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the undocumented 'session' parameter. The description says 'a session' but doesn't clarify what format the session parameter takes (name? ID?), whether it's a tmux session name, or how to find valid values. This is a gap for a required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Kill') and resource ('a session and every agent in it'), which clearly distinguishes it from sibling tools like pane_kill (kills a pane) and agents_launch (launches agents). It doesn't explicitly name a sibling, but the scope is clear enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it: when you want to kill a session and all its agents, versus pane_kill for a single pane. However, it doesn't explicitly state when not to use it or mention alternatives. The TMUX_AGENTS_ALLOW_KILL=false note gives a conditional context but not a full usage guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How this server is configured, whether tmux answers, and the visible sessions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral burden. It does a decent job: 'whether tmux answers' signals a liveness probe, and 'visible sessions' indicates a read-only snapshot rather than a mutation. It doesn't explicitly promise no side effects, but no parameters and a status framing make that low-risk.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single one-sentence fragment earns its place; each item — configuration, liveness, sessions — adds distinct information. It is front-loaded with the most important aspect.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter status tool with an output schema, the description is complete enough: it states the three areas the output covers, and the presence of an output schema handles return-value details. It would be stronger if it said 'run this before pane tools to confirm tmux is alive,' but that is a usage nicety, not a correctness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the parameter burden is minimal; the baseline for 0-param tools applies. The description hints that the output is server/tmux state, which is sufficient for a no-input tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description enumerates three concrete outputs — server configuration, tmux liveness, and visible sessions — which clearly identifies a status/health tool. It lacks an explicit action verb like 'returns' or 'reports', so it stops short of a 5, but the resource scope distinguishes it from pane-level siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description never states when to prefer tmux_status over pane_read, panes_list, or session_kill. The status semantics imply it is a diagnostic entry point, but no explicit conditions or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1agents_launchpane_keypane_killpane_readpane_sendpane_waitpanes_listsession_killtmux_statusScored across 9 tools
Most tools have clear boundaries: tmux_status is informational, panes_list enumerates, pane_read/send/key/wait operate on a single pane, agents_launch creates sessions, and session_kill/pane_kill destroy them. The only mild overlap is pane_send vs pane_key, but their descriptions clearly separate literal text from named keys.
Tool names follow a consistent noun_verb pattern (tmux_status, panes_list, pane_read, pane_send, pane_key, pane_wait, agents_launch, session_kill, pane_kill). Minor deviation: tmux_status uses a prefix rather than a resource noun, and agents_launch is a compound noun rather than agent_launch, but the pattern is otherwise predictable.
Nine tools is well-scoped for a tmux agent orchestration server: one status, one list, four pane interaction tools, one launch tool, and two kill tools. Each tool serves a distinct operational need without redundancy.
The surface covers the full lifecycle: launch agents, inspect panes, read output, send input, wait for completion, and kill sessions/panes. Minor gaps include no way to rename sessions/panes or resize panes, but these are not essential for the server's stated purpose.
Docs for agent-manager, the terminal UI that runs AI coding agents as live tmux sessions.
Shared control plane for AI coding agents — tasks, memory, decisions, file locks. 12 tools.
Coordination hub for AI coding agents: message teammates, ask humans, audit every event.
Develop, manage, and debug Railway projects, services, and deployments from within agents.
