Loading ToolBench
Strong foundation with 15 well-named tools covering tmux operations. All tools have descriptions (avg 180 chars, within 10-1024 baseline) and explicit input schemas with typed parameters. Naming follows verb_noun convention (list_sessions, create_session, set_option). However, several tools lack output schema documentation, and some parameter descriptions are generic. Error handling guidance is minimal, tools don't explain recovery paths when operations fail. Security-sensitive tools (kill_server, set_environment) lack explicit permission/scope declarations. Composition is sound: tools chain well (list_sessions → create_session → set_option), and batch_tools provides aggregation for read-only operations.
Call several `inspect` tools serially and return per-tool results. Use when one agent turn needs several observations. Each nested call still goes through FastMCP validation and this server's middleware. Only `inspect` tools are accepted; anything that changes tmux state is refused, whatever this server has enabled. This wrapper aggregates authority under its own name: a client rule keyed on a nested tool's name does not fire for a call made through it. Read it as authority to invoke any `inspect` tool.
Create a new tmux session. Check list_sessions first to avoid name conflicts. A new session starts with one window and one pane. Values in ``environment`` are stored in the tmux session environment, so future panes inherit them too.
Delete an MCP-owned paste buffer.
Get information about the tmux server. Use to verify the tmux server is running before other operations. For session-level details, use list_sessions instead.
Kill the tmux server and all its sessions. Destroys ALL sessions, windows, and panes on this server. Use kill_session to remove a single session instead. Self-kill protection prevents killing the server running this MCP process.
Output schemas not documented. Tools return structured results (BufferRef, HookListResult, etc.) but LLMs cannot see field definitions. Agents cannot plan downstream calls or extract required IDs without guessing.
Destructive/sensitive tools lack permission scope declarations. kill_server, set_environment, set_option, and paste_buffer can modify or destroy state but do not declare required scopes (e.g., 'write:tmux', 'admin:server'). Agents cannot reason about authority or audit trails.
Error handling lacks recovery guidance. Descriptions do not explain what to do if a tool fails (e.g., 'If session not found, call list_sessions first'). Agents receive errors but no actionable next steps.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 68 | 2025-06-18+ | v2 |
List tmux sessions (terminal workspaces) on a tmux server. Use for tmux multiplexer sessions — 'this session', 'my workspace', 'the dev session' — not login sessions or HTTP sessions. The starting point for discovery — call this before targeting specific sessions, windows, or panes.
Load text into a new agent-namespaced tmux paste buffer. Each call allocates a fresh buffer name — two concurrent calls will land in distinct buffers even if they pass the same ``logical_name``. Agents MUST use the returned :attr:`~libtmux_mcp.models.BufferRef.buffer_name` on subsequent paste/show/delete calls.
Paste an MCP-owned buffer into a pane.
Set a tmux environment variable. Use to set variables that will be inherited by new panes and windows. Changes do not affect already-running processes. Some variables control later shell execution. Bash sources the file named by ``BASH_ENV``, POSIX shells may source the file named by ``ENV``, and Bash evaluates ``PROMPT_COMMAND`` before displaying a prompt.
Set a tmux option value. Some option values are executable. tmux runs a ``#(...)`` job inside the status formats when it draws them, and repeats it on the status interval; ``default-command`` and ``default-shell`` decide what every future pane runs, and ``command-alias`` rewrites later commands. The value is stored verbatim, so an option that interprets it later runs what is stored, not what this call did. Use to change tmux behavior at runtime. Common uses: adjusting history-limit, enabling mouse support, changing status bar format.
Read back the contents of an MCP-owned buffer. Output is tail-preserved: when the buffer exceeds max_lines, the oldest lines are dropped and a truncation notice is prepended.
Show tmux environment variables. Use to inspect tmux environment variables that affect child processes.
Look up a specific tmux hook by name. Returns a :class:`~libtmux_mcp.models.HookListResult` with zero or more :class:`~libtmux_mcp.models.HookEntry` rows — zero if the hook is unset, one if it is a scalar hook, and multiple if it is an array hook with sparse indices.
List configured tmux hooks at the given scope. ``scope="server"`` enumerates hooks installed via ``tmux set-hook -g ...``. tmux splits those globals across two options trees by hook category: session-level hooks (``session-closed``, ``client-*``, etc.) live in the global-session tree enumerated by ``show-hooks -g``, while pane/window-level hooks (``pane-focus-in``, ``window-resized``, etc.) live in the global-window tree enumerated by ``show-hooks -gw``. This tool consults both trees and merges the results so the enumeration matches what a name-targeted :func:`~libtmux_mcp.tools.hook_tools.show_hook` call would return.
Show a tmux option value. Use to check tmux configuration values such as history-limit, mouse support, or status bar settings.
Parameter descriptions are generic. Many params (e.g., 'socket_name', 'target', 'scope') lack format/constraint details. 'socket_name' does not explain default behavior or valid formats; 'target' does not clarify what identifier type is expected (name vs ID).
Confirmation/dry-run pattern missing for irreversible operations. kill_server and delete_buffer are destructive but lack a dry-run or confirmation step. Agents can accidentally destroy state without a safety gate.