Changelog¶

libtmux-mcp 0.1.x (unreleased)¶

Notes on upcoming releases will be added here

libtmux-mcp 0.1.0a6 (2026-05-09)¶

libtmux-mcp 0.1.0a6 is the activation and registration cleanup release. It makes the server much easier for MCP clients to discover from ordinary “pane”, “window”, and “session” prompts, standardizes new setup docs around the tmux registration slug, and adds migration guidance for existing libtmux registrations. Existing installs keep working; the release changes defaults and documentation so new installs line up with the tool prefix users actually see.

What’s new¶

Bare tmux prompts now find the server

Agents no longer need the word “tmux” in every prompt before this server becomes relevant. The server instructions now name the positive cases users naturally write, such as “split this pane”, “current window”, and “this session”, while steering clients away from unrelated browser tabs, editor splits, tiling-window-manager panes, and notebook cells. The discovery anchors most likely to answer those prompts - list_panes, list_windows, and snapshot_pane - also carry the preload hint used by clients that keep a small always-available schema set. See Agent prompting guide for the user-facing activation contract. (#37)

New installs are documented as tmux

The recommended registration slug is now tmux, matching the MCP serverInfo.name and the mcp__tmux__* tool-call prefix surfaced by clients. The package name, import name, and existing user-created libtmux registrations are unchanged; only the documented install target moves to the clearer slug. See Migration notes for the walkthrough. (#40)

Documentation¶

Hierarchy-noun tool titles now include a tmux qualifier in catalog-style displays, so entries like “List tmux Sessions” stay understandable when a client shows tools from several MCP servers together. Tmux-specific verbs such as send_keys, pipe_pane, snapshot_pane, capture_pane, and paste_text keep their shorter names because the verb already identifies the tmux operation. (#38)

The Agent prompting guide guide gains an activation and discovery section with positive triggers, anti-triggers, a client-level alwaysLoad example, and a project-instructions fragment for teams that want stronger bias toward tmux when users say “this pane” or “current window”. (#39)

libtmux-mcp 0.1.0a5 (2026-05-06)¶

libtmux-mcp 0.1.0a5 makes layout-relative pane targeting a first-class workflow. Agents can ask for “the bottom-right pane” directly, reason from typed geometry returned on pane models, and avoid parsing tmux format strings for common layout questions. The release also polishes the documentation site after the theme migration and extends the local MCP swap helper so Claude users can choose project-local or user-global config.

What’s new¶

Layout-relative pane targeting via find_pane_by_position

find_pane_by_position resolves a window corner - top-left, top-right, bottom-left, or bottom-right - to a single PaneInfo. This replaces the old workaround of calling display_message with #{pane_at_bottom} / #{pane_at_right} and parsing raw string output. Single-pane and otherwise ambiguous layouts resolve deterministically, so the common “use the only pane” case does not require an extra branch in the agent workflow. (#34)

Pane responses now carry geometry

PaneInfo, PaneContentMatch, and PaneSnapshot now include window-relative coordinates, edge predicates, and the pane TTY. That means an agent can inspect returned data to decide whether a pane is at the left edge, bottom edge, or a specific corner instead of making another tmux query. The older pane_width and pane_height fields intentionally keep their existing string typing in this alpha; changing those fields is left for a later breaking-change window. (#34)

Documentation¶

The docs site moves onto gp-furo-theme with sphinx-vite-builder handling the theme asset pipeline, so the rendered site follows the same gp-sphinx docs stack used by the rest of the project documentation. (#33)

The install widget and above-the-fold typography no longer shift after first paint. Saved install-widget choices now render in the correct panel immediately, and the fonts and logo used on the landing page are loaded early enough to avoid visible swaps. (#36)

The new corner-finder appears anywhere a reader is likely to look for targeting guidance: the homepage tool chain, tools index, pane tools page, prompting guide, recipes, and example responses. Existing display_message guidance now points layout-relative pane selection at find_pane_by_position instead of teaching agents to expand pane-edge format variables by hand. (#34)

Development¶

scripts/mcp_swap.py gains --scope {user,project} for Claude. Project scope keeps the safe local override used while working in this checkout; user scope intentionally changes the fallback used from other projects. Codex, Cursor, and Gemini have only a global layer, so the flag is accepted there without creating a fake per-project mode. (#35)

libtmux-mcp 0.1.0a4 (2026-05-02)¶

libtmux-mcp 0.1.0a4 adds pane recovery and closes the last gap in the core hierarchy’s single-object metadata reads. Agents can restart a stuck pane without losing its identity, fetch known sessions or windows directly, and use a bundled development script to point local MCP clients at a checkout. The respawn_pane parameter name settles on shell before the stable API, replacing the earlier alpha spelling shell_command.

What’s new¶

Restart wedged panes in place with respawn_pane

respawn_pane restarts the process in an existing tmux pane while preserving the pane_id and the window layout. That is the right recovery primitive for long-running agent sessions: kill_pane followed by split_window creates a new pane, invalidates stored handles, and can disturb the surrounding layout. The final alpha API uses shell for the replacement command to match split_window and libtmux’s upstream respawn naming. (#27)

Direct metadata reads for sessions and windows

get_session_info and get_window_info complete the server/session/window/pane metadata pattern alongside get_server_info and get_pane_info. Callers that already have an ID or a scoped index no longer need to call a list tool and filter the response. Buffers, hooks, options, and environment values keep their existing show/load/read tools rather than gaining redundant get_*_info wrappers. (#27)

Documentation¶

Safety tiers now documents respawn_pane as a mutating recovery tool with real process side effects, including the kill=true default and the visibility tradeoffs of passing command or environment data through tmux. The same update refreshes socket-guard notes for macOS, tightens guidance around display_message and pipe_pane, and adds dedicated tool pages for the new recovery and metadata tools. (#27)

Development¶

scripts/mcp_swap.py lands as local dogfooding infrastructure for Claude, Codex, Cursor, and Gemini. It detects installed clients, shows the current libtmux-mcp registration, rewrites config to run this checkout through uv, and reverts from backups. The just mcp-use-local and just mcp-revert recipes wrap that flow for branch QA. (#27)

libtmux-mcp 0.1.0a3 (2026-04-19)¶

libtmux-mcp 0.1.0a3 is a focused correctness release after the FastMCP alignment work. It fixes caller identity across multiple tmux sockets, moves channel waits off the FastMCP event loop, and raises the libtmux floor to pick up upstream pytest-fixture cleanup. The result is less surprising metadata in multi-server setups and fewer stalled clients during long waits.

Dependencies¶

Minimum libtmux>=0.55.1 (was >=0.55.0) for tmux-python/libtmux#661, which fixes pytest-plugin socket cleanup under /tmp/tmux-<uid>/.

Fixes¶

Pane caller identity is socket-aware

The is_caller pane annotation no longer treats pane %0 on every tmux server as the current agent pane just because the pane IDs match. The annotation now compares the caller’s tmux socket as well, matching the self-protection checks used around destructive tools. This fixes PaneInfo, PaneSnapshot, and PaneContentMatch responses in multi-socket environments. (#22, fixes #19)

Channel waits no longer stall the MCP server

wait_for_channel and signal_channel now run their blocking tmux subprocess work outside the event loop. Other tool calls and client keepalives can continue while a wait is pending, matching the async behavior already used by wait_for_text and wait_for_content_change. (#21, fixes #18)

libtmux-mcp 0.1.0a2 (2026-04-19)¶

libtmux-mcp 0.1.0a2 is the FastMCP alignment release. It expands the server from a basic tmux wrapper into a broader agent automation surface with discovery, waits, buffers, hooks, pane/window navigation, prompt recipes, middleware, and bounded terminal output. The release includes one response-shape breaking change: search_panes now returns a paginated SearchPanesResult instead of a bare list. (#15)

Breaking changes¶

search_panes returns SearchPanesResult

search_panes now returns a result object with matches and pagination metadata instead of the earlier list[PaneContentMatch] shape. Existing callers should iterate over .matches; callers that search large tmux workspaces can also inspect truncated, truncated_panes, total_panes_matched, offset, and limit.

# Before
for match in search_panes(...):
    ...

# After
for match in search_panes(...).matches:
    ...

Minimum fastmcp>=3.2.4 (was >=3.1.0). The newer FastMCP release is required for ReadonlyRetryMiddleware and per-parameter input-schema descriptions.

What’s new¶

Discovery and synchronization tools

list_servers discovers live tmux servers, including explicitly provided socket paths. The wait family adds content waits (wait_for_text, wait_for_content_change) and tmux channel synchronization (wait_for_channel, signal_channel) so agents can wait for explicit milestones instead of sleeping or repeatedly capturing panes. (#15)

Buffers, hooks, and richer pane/window control

Agent-namespaced buffer tools - load_buffer, paste_buffer, show_buffer, and delete_buffer - support staged multi-line input without overloading keystroke simulation. Read-only hook tools (show_hook, show_hooks) expose tmux hook state without adding write-hooks that survive process death. The pane and window surface grows with snapshot_pane, pipe_pane, display_message, paste_text, select_pane, swap_pane, select_window, move_window, enter_copy_mode, and exit_copy_mode. (#15)

Prompt recipes for common agent workflows

Four MCP prompts ship for repeatable tmux work: run_and_wait, diagnose_failing_pane, build_dev_workspace, and interrupt_gracefully. Clients that only expose tools can opt into tool-shaped prompt access with LIBTMUX_MCP_PROMPTS_AS_TOOLS=1. See Prompts for the prompt catalog. (#15)

Middleware for safer long-running automation

The middleware stack now includes AuditMiddleware for digest-redacted argument summaries, SafetyMiddleware for safety-tier visibility, ReadonlyRetryMiddleware for transient readonly libtmux failures, and TailPreservingResponseLimitingMiddleware for oversized tool output. Timing and error-handling middleware round out the request path. (#15)

Tail-preserving bounded output

capture_pane, snapshot_pane, and show_buffer accept max_lines and report whether older lines were trimmed. Truncation keeps the newest terminal output, which is usually the active prompt or most recent command result. Pass max_lines=None when a caller intentionally wants the full scrollback or buffer. (#15)

Better schemas and startup failures

Tool input schemas now include parameter descriptions extracted from docstrings, so clients can explain arguments without separate docs lookups. Startup also fails with a clear RuntimeError when tmux is not available on PATH, and active_pane_id tells callers which pane was created by create_session. (#15)

Fixes¶

search_panes neutralizes tmux format-string injection in the regex fast path.
The macOS self-kill guard resolves the live tmux socket before falling back to TMUX_TMPDIR reconstruction.
The build_dev_workspace prompt uses real tool parameter names, avoids waiting for prompts after screen-grabbing commands, and replaces a Linux-specific log default with log_command.
ReadonlyRetryMiddleware logs retry warnings under libtmux_mcp.retry.

Documentation¶

The tools documentation gains category pages for Buffer tools, Hook tools, and Tools. The pane tools docs explain the SearchPanesResult migration, while Safety tiers documents the audit log, socket caveats, pipe_pane, and set_environment. (#15)

libtmux-mcp 0.1.0a1 (2026-04-13)¶

libtmux-mcp 0.1.0a1 expands the tmux control surface around the workflows agents actually perform after they find a pane. It adds richer screen snapshots, waits, navigation, pane/window movement, copy-mode entry points, live logging, and bracketed paste support. The docs also adopt the gp-sphinx visual stack so the generated API and tool pages become easier to scan. (#11)

What’s new¶

Screen snapshots and waits

snapshot_pane returns terminal content together with cursor position, copy-mode state, and scroll position in a single read. wait_for_content_change lets an agent wait for any visible update when it does not know the exact text to expect. PaneSnapshot and ContentChangeResult carry those responses in typed models. (#11)

Pane and window navigation

select_pane, swap_pane, select_window, and move_window let agents navigate within tmux and rearrange panes or windows without asking a user to manually focus the target. Directional window selection is scoped to the requested session, and pane selection handles next/previous relative navigation through concrete pane IDs. (#11)

Terminal I/O helpers

pipe_pane logs live pane output to a file, display_message exposes tmux format expansion as a read-only metadata escape hatch, enter_copy_mode and exit_copy_mode control copy-mode state, and paste_text uses tmux buffers for multi-line input where raw keystroke simulation is fragile. (#11)

Documentation¶

The API docs adopt the gp-sphinx documentation stack: card-style API layouts, safety and scope badges, MyST cross-reference roles, improved CLI-doc section scoping, IBM Plex typography, and FastMCP-aware tool rendering. The docs dependency stack is then refreshed to gp-sphinx 0.0.1a8. (#10, #14)

libtmux-mcp 0.1.0a0 (2026-03-22)¶

libtmux-mcp 0.1.0a0 is the first standalone alpha release, extracted from libtmux’s MCP branch. It packages libtmux-backed tmux control as an MCP server with typed tools, hierarchy resources, safety tiers, and socket-aware server selection. The release establishes the base contract that later alphas expand: inspect tmux state, make scoped mutations, and keep destructive operations behind an explicit safety tier.

What’s new¶

Standalone MCP server for tmux

The package exposes tmux sessions, windows, panes, options, and environment operations through MCP tools backed by libtmux. It includes the console entry point, FastMCP server wiring, and the first set of Pydantic response models for tool output.

Browsable tmux hierarchy

tmux:// resources let MCP clients browse the tmux hierarchy from server to sessions, windows, and panes. Tool resolvers accept the normal tmux identifiers so callers can move between resource browsing and concrete tool calls.

Safety and socket isolation

The initial server ships with readonly, mutating, and destructive safety tiers, controlled by LIBTMUX_SAFETY. Socket selection through LIBTMUX_SOCKET and LIBTMUX_SOCKET_PATH lets the same process target isolated tmux servers, and TMUX_PANE awareness marks the pane that belongs to the calling agent.

Typed implementation baseline

Server caching, resolver helpers, standardized error handling, and strict mypy coverage provide the internal foundation for later tool families. All initial tool responses are typed through Pydantic models rather than ad hoc dictionaries.