From d9eb09721308a654688b63b9a81f6cd94d215dc6 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Fri, 8 May 2026 22:36:39 +0000 Subject: [PATCH 1/2] docs(prompting) document activation, alwaysLoad, and bias template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit why: the most-frequent question this server gets is "when does the agent actually pick libtmux-mcp on bare 'pane' / 'window' / 'session' without me saying tmux?". The existing docs/topics/prompting.md covers server-injected instructions and prompt patterns but didn't explicitly answer the activation/discovery question or document the Claude Code-specific `alwaysLoad` lever. This belongs alongside the other prompting guidance, not in the README. The README stays focused on quickstart + setup; the agent prompting guide is where activation mechanics, alwaysLoad opt-in, and project-instructions templates live. what: - New "## Activation and discovery" section in docs/topics/prompting.md with positive/anti-trigger prose and an "Always-on tool listing" subsection covering the Claude Code v2.1.121+ `alwaysLoad: true` JSON snippet and its ~3-5K token cost. - New "### To bias activation on bare 'pane' / 'window' / 'session'" template under the existing "## System prompt fragments" section. Notes that AGENTS.md / CLAUDE.md / equivalent project-instructions files compose into the system prompt at higher priority than the MCP server's `instructions` block. - Cross-reference to the existing concepts.md "Agent self-awareness" section for the inside-tmux $TMUX_PANE auto-detection note — avoids duplicating content already in the docs. - {toolref}`...` markers used for tool references so they resolve to rendered tool docs in Sphinx. --- docs/topics/prompting.md | 40 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/docs/topics/prompting.md b/docs/topics/prompting.md index e31c81c..3f1fed9 100644 --- a/docs/topics/prompting.md +++ b/docs/topics/prompting.md @@ -28,7 +28,33 @@ pane for 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`) +- **Caller pane awareness**: If the server runs inside tmux, it tells the agent which pane is its own (via `TMUX_PANE`). See {ref}`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. + +### Always-on tool listing (Claude Code only) + +[Claude Code](https://code.claude.com/docs/en/mcp) defers loading MCP tool schemas when they exceed ~10% of your context window. By default, the three discovery anchors ({toolref}`list-panes`, {toolref}`list-windows`, {toolref}`snapshot-pane`) carry an `anthropic/alwaysLoad: true` hint so bare *"pane"* / *"window"* prompts surface this server without a `ToolSearch` hop. + +To force libtmux-mcp's *full* schema list to load upfront — useful if you also want {toolref}`send-keys`, {toolref}`capture-pane`, {toolref}`select-window` etc. preloaded — add `"alwaysLoad": true` at the server entry level (requires Claude Code v2.1.121+): + +```json +{ + "mcpServers": { + "tmux": { + "command": "uvx", + "args": ["libtmux-mcp"], + "alwaysLoad": true + } + } +} +``` + +Cost: ~3-5K tokens of permanent context budget. Use only if libtmux-mcp is one of your top-3 most-used MCPs. ## Effective prompt patterns @@ -90,6 +116,18 @@ Use wait_for_text to know when a server is ready before running tests that depend on it. ``` +### To bias activation on bare "pane" / "window" / "session" + +```{code-block} text +:class: system-prompt + +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. +``` + +This is the lever closest to the failure mode for *"current window"* / *"this session"* anaphora — a project-level instructions file (`AGENTS.md`, `CLAUDE.md`, or whichever your host honors) lives one prompt-layer above the MCP server's `instructions` and your host composes it into the system prompt with higher priority. + ## Tool selection heuristics When an agent is unsure which tool to use, these rules help: From 2ea6203dfb2cdae626059de6d5f1ec008df0ef1d Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 9 May 2026 09:04:46 -0500 Subject: [PATCH 2/2] docs(CHANGES) note prompting-guide activation section Adds an unreleased "Documentation" bullet for the new "Activation and discovery" section in docs/topics/prompting.md and the project-bias template under "System prompt fragments". --- CHANGES | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGES b/CHANGES index 36355b8..1f850ec 100644 --- a/CHANGES +++ b/CHANGES @@ -40,6 +40,11 @@ _Notes on upcoming releases will be added here_ as visual chrome. Title is NOT in BM25's search corpus (verified vs FastMCP's `_extract_searchable_text`); this is pure catalog polish, no activation impact. (#38) +- {ref}`prompting` gains "Activation and discovery" + (positive/anti-trigger prose, the Claude Code `alwaysLoad: true` + JSON snippet for full schema preload, ~3-5K token cost + noted) and a project-bias template under "System prompt + fragments" for `AGENTS.md` / `CLAUDE.md`. (#39) ## libtmux-mcp 0.1.0a5 (2026-05-06)