Agent prompting guide¶

What the server tells your agent automatically¶

Every MCP client receives these instructions when connecting to the libtmux-mcp server. You do not need to repeat this information — the agent already knows it.

libtmux MCP server for programmatic tmux control. tmux hierarchy:
Server > Session > Window > Pane. Use pane_id (e.g. '%1') as the
preferred targeting method - it is globally unique within a tmux server.
Use send_keys to execute commands, capture_pane for one-shot reads, and
capture_since for repeated observation. All tools accept an optional
socket_name parameter for multi-server support (defaults to
LIBTMUX_SOCKET env var).

IMPORTANT — metadata vs content: list_windows, list_panes, and
list_sessions only search metadata (names, IDs, current command). To
find text that is actually visible in terminals — when users ask what
panes 'contain', 'mention', 'show', or 'have' — use search_panes to
search across all pane contents, capture_since for repeated reads of a
known pane, or capture_pane for a one-shot manual inspection.

The server also dynamically adds:

• Safety tier context: Which tier is active and what tools are available

• Caller pane awareness: If the server runs inside tmux, it tells the agent which pane is its own (via TMUX_PANE). See Concepts “Agent self-awareness” for details.

Activation and discovery¶

This server is designed to fire on bare terminal-surface phrasing — “split this pane”, “what’s in my current window”, “start a session for the build” — without you having to say “tmux”. The server treats pane, session, window, and split as positive triggers; tmux ID prefixes (%1, @1, $1) are unambiguous.

The server stays out of the way when you mean a browser window, an editor split, an i3/Hyprland workspace, or a Jupyter notebook cell — if your phrasing is ambiguous, the agent will ask before acting.

{
  "mcpServers": {
    "tmux": {
      "command": "uvx",
      "args": ["libtmux-mcp"],
      "alwaysLoad": true
    }
  }
}

Effective prompt patterns¶

These natural-language prompts reliably trigger the right tool sequences:

Anti-patterns to avoid¶

System prompt fragments¶

Copy these into your agent’s system instructions (AGENTS.md, CLAUDE.md, .cursorrules, or MCP client config) to improve behavior:

When executing long-running commands (servers, builds, test suites),
use tmux via the libtmux MCP server rather than running them directly.
This keeps output accessible for later inspection.

For command completion, compose `tmux wait-for -S <channel>` into the
shell command and call wait_for_channel — deterministic, no polling.
Use wait_for_text or wait_for_content_change for observation flows
(third-party logs, daemon prompts), and use capture_since when you
need to read the same pane repeatedly. Never capture_pane immediately
after send_keys — the command may still be running.

Before creating tmux sessions, check list_sessions to avoid duplicates.
Always use pane_id for targeting — it is globally unique. Never run
destructive operations (kill_session, kill_server) without confirming
the target with the user first.

When the user asks you to run tests or start servers, use dedicated
tmux panes. Split windows to run related processes side-by-side.
Use wait_for_text to know when a server is ready before running tests
that depend on it.

This project uses tmux for its development workflow. When the user
says "pane", "window", or "session" without further qualification,
prefer the tmux MCP tools (libtmux-mcp) before assuming GUI semantics.

Tool selection heuristics¶

When an agent is unsure which tool to use, these rules help:

1. Discovery first: Call list_sessions or list_panes before acting on specific targets

2. Prefer IDs: Once you have a pane_id, use it for all subsequent calls — it never changes during the pane’s lifetime

3. Wait, don’t poll: For commands the agent authors, prefer wait_for_channel with tmux wait-for -S <channel> composed into the command — deterministic and race-free. Use capture_since for repeated observation, and fall back to wait_for_text or wait_for_content_change for output the agent doesn’t author. Never call capture_pane in a retry loop.

4. Content vs. metadata: If looking for text in a terminal, use search_panes. If looking for pane properties (name, PID, path), use list_panes or get_pane_info

5. Destructive tools are opt-in: Never kill sessions, windows, or panes unless the user explicitly asks