|
| 1 | +(prompting)= |
| 2 | + |
| 3 | +# Agent prompting guide |
| 4 | + |
| 5 | +How to write effective instructions for AI agents using libtmux-mcp. |
| 6 | + |
| 7 | +## What the server tells your agent automatically |
| 8 | + |
| 9 | +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. |
| 10 | + |
| 11 | +```text |
| 12 | +libtmux MCP server for programmatic tmux control. tmux hierarchy: |
| 13 | +Server > Session > Window > Pane. Use pane_id (e.g. '%1') as the |
| 14 | +preferred targeting method - it is globally unique within a tmux server. |
| 15 | +Use send_keys to execute commands and capture_pane to read output. All |
| 16 | +tools accept an optional socket_name parameter for multi-server support |
| 17 | +(defaults to LIBTMUX_SOCKET env var). |
| 18 | +
|
| 19 | +IMPORTANT — metadata vs content: list_windows, list_panes, and |
| 20 | +list_sessions only search metadata (names, IDs, current command). To |
| 21 | +find text that is actually visible in terminals — when users ask what |
| 22 | +panes 'contain', 'mention', 'show', or 'have' — use search_panes to |
| 23 | +search across all pane contents, or list_panes + capture_pane on each |
| 24 | +pane for manual inspection. |
| 25 | +``` |
| 26 | + |
| 27 | +The server also dynamically adds: |
| 28 | +- **Safety tier context**: Which tier is active and what tools are available |
| 29 | +- **Caller pane awareness**: If the server runs inside tmux, it tells the agent which pane is its own (via `TMUX_PANE`) |
| 30 | + |
| 31 | +## Effective prompt patterns |
| 32 | + |
| 33 | +These natural-language prompts reliably trigger the right tool sequences: |
| 34 | + |
| 35 | +| Prompt | Agent interprets as | |
| 36 | +|--------|-------------------| |
| 37 | +| "Run `pytest` in my build pane and show results" | {tool}`send-keys` → {tool}`wait-for-text` → {tool}`capture-pane` | |
| 38 | +| "Start the dev server and wait until it's ready" | {tool}`send-keys` → {tool}`wait-for-text` (for "listening on") | |
| 39 | +| "Check if any pane has errors" | {tool}`search-panes` with pattern "error" | |
| 40 | +| "Set up a workspace with editor, server, and tests" | {tool}`create-session` → {tool}`split-window` (x2) → {tool}`set-pane-title` (x3) | |
| 41 | +| "What's running in my tmux sessions?" | {tool}`list-sessions` → {tool}`list-panes` → {tool}`capture-pane` | |
| 42 | +| "Kill the old workspace session" | {tool}`kill-session` (after confirming target) | |
| 43 | + |
| 44 | +## Anti-patterns to avoid |
| 45 | + |
| 46 | +| Prompt | Problem | Better version | |
| 47 | +|--------|---------|---------------| |
| 48 | +| "Run this command" | Ambiguous — agent may use its own shell instead of tmux | "Run `make test` in a tmux pane" | |
| 49 | +| "Check my terminal" | Which pane? Agent must discover first | "Check the pane running `npm dev`" or "Search all panes for errors" | |
| 50 | +| "Clean up everything" | Too broad for destructive operations | "Kill the `ci-test` session" | |
| 51 | +| "Show me the output" | Capture immediately? Or wait? | "Wait for the command to finish, then show me the output" | |
| 52 | + |
| 53 | +## System prompt fragments |
| 54 | + |
| 55 | +Copy these into your agent's system instructions (`CLAUDE.md`, `.cursorrules`, or MCP client config) to improve behavior: |
| 56 | + |
| 57 | +### For general tmux workflows |
| 58 | + |
| 59 | +```text |
| 60 | +When executing long-running commands (servers, builds, test suites), |
| 61 | +use tmux via the libtmux MCP server rather than running them directly. |
| 62 | +This keeps output accessible for later inspection. Use the pattern: |
| 63 | +send_keys → wait_for_text (for completion signal) → capture_pane. |
| 64 | +``` |
| 65 | + |
| 66 | +### For safe agent behavior |
| 67 | + |
| 68 | +```text |
| 69 | +Before creating tmux sessions, check list_sessions to avoid duplicates. |
| 70 | +Always use pane_id for targeting — it is globally unique. Never run |
| 71 | +destructive operations (kill_session, kill_server) without confirming |
| 72 | +the target with the user first. |
| 73 | +``` |
| 74 | + |
| 75 | +### For development workflows |
| 76 | + |
| 77 | +```text |
| 78 | +When the user asks you to run tests or start servers, use dedicated |
| 79 | +tmux panes. Split windows to run related processes side-by-side. |
| 80 | +Use wait_for_text to know when a server is ready before running tests |
| 81 | +that depend on it. |
| 82 | +``` |
| 83 | + |
| 84 | +## Tool selection heuristics |
| 85 | + |
| 86 | +When an agent is unsure which tool to use, these rules help: |
| 87 | + |
| 88 | +1. **Discovery first**: Call {tool}`list-sessions` or {tool}`list-panes` before acting on specific targets |
| 89 | +2. **Prefer IDs**: Once you have a `pane_id`, use it for all subsequent calls — it never changes during the pane's lifetime |
| 90 | +3. **Wait, don't poll**: Use {tool}`wait-for-text` instead of repeatedly calling {tool}`capture-pane` in a loop |
| 91 | +4. **Content vs. metadata**: If looking for text *in* a terminal, use {tool}`search-panes`. If looking for pane *properties* (name, PID, path), use {tool}`list-panes` or {tool}`get-pane-info` |
| 92 | +5. **Destructive tools are opt-in**: Never kill sessions, windows, or panes unless the user explicitly asks |
0 commit comments