Concepts

The mental model you need to use libtmux-mcp effectively.

tmux hierarchy

tmux organizes terminals in a strict hierarchy:

Server (tmux server instance)
  └─ Session (named group of windows, e.g. "dev")
      └─ Window (tab within a session, e.g. "editor")
          └─ Pane (terminal split within a window)

libtmux-mcp mirrors this hierarchy. Every tool operates on one of these objects.

Identifiers

Each tmux object has identifiers you can use to target it:

Object

ID format

Name

Index

Session

$1, $2

"dev", "build"

—

Window

@1, @2

"editor", "tests"

0, 1, 2

Pane

%1, %2

—

—

Pane IDs are globally unique within a tmux server and are the preferred targeting method. When you know the pane ID, use it directly — no session or window context needed.

Session names and window names are human-readable but may not be unique. Window indexes are unique within a session.

Targeting

Most tools accept multiple targeting parameters. The resolution order is:

  1. Direct ID — pane_id, window_id, or session_id (fastest, unambiguous)

  2. Name lookup — session_name + optional window_index (convenient but may be ambiguous)

  3. Default — If no targeting parameter is given, tools that need a single object will fail; list tools return everything

For pane tools, you can combine parameters to narrow the search: session_name + window_id → find the pane in that specific window.

Toolsets

Tools belong to four unordered sets:

  • Inspect requests tmux state or terminal output, or renders server-local prompt text. Its built-in operation does not pass caller input as a tmux or shell command.

  • Manage changes tmux-managed structure, presentation, staging, or coordination state.

  • Execute starts or drives pane processes, or stores state that can control later execution.

  • Teardown deletes tmux objects or retained scrollback.

The selected sets determine which MCP tools this server advertises and accepts. Configured tmux aliases and hooks can add effects to any tmux request; see Trust model.

Agent self-awareness

When the MCP server runs inside a tmux pane (detected via the TMUX_PANE environment variable), it:

  • Includes the caller’s pane context in server instructions

  • Annotates the caller’s own pane with is_caller=true in tool results

  • Prevents the teardown tools from killing the caller’s own pane, window, session, or server

These checks prevent the teardown tools from terminating their own MCP pane. They do not constrain tmux aliases, hooks, other clients, or pane processes.

Server caching

Server instances are cached by (socket_name, socket_path, tmux_bin) tuple with thread-safe access. Dead servers are automatically evicted via libtmux.Server.is_alive() checks. This means multiple tool calls reuse the same server connection efficiently.

Filtering

List tools (list_sessions, list_windows, and list_panes) support Django-style filters:

{"session_name__contains": "dev"}

Supported operators: exact, contains, startswith, endswith, regex, icontains, iexact, istartswith, iendswith, iregex.

Resources

In addition to tools, the MCP server exposes tmux:// URI resources for browsing the hierarchy:

  • tmux://sessions — All sessions

  • tmux://sessions/{session_name} — Session detail with windows

  • tmux://sessions/{session_name}/windows — Session’s windows

  • tmux://sessions/{session_name}/windows/{window_index} — Window detail with panes

  • tmux://panes/{pane_id} — Pane details

  • tmux://panes/{pane_id}/content — Pane captured content