docs: DX improvements — docstrings, recipes, gotchas, prompting guide#3
Merged
docs: DX improvements — docstrings, recipes, gotchas, prompting guide#3
Conversation
why: Repo default branch is main but 4 locations still referenced master, breaking Edit-on-GitHub links, redirect detection, and source code links. what: - docs/conf.py: source_branch, rediraffe_branch, linkcode_resolve URL - src/libtmux_mcp/__about__.py: __changes__ URL
why: "Use when / Avoid when" guidance existed only in Markdown docs, invisible to agents at runtime. FastMCP exposes function __doc__ as MCP tool descriptions — enriching docstrings directly improves agent tool selection and workflow composition. what: - Add 2-3 line behavioral summary to each of 22 tool docstrings - Covers: use case, common next step, side effects, race conditions - Key addition: send_keys warns about capture_pane race condition - Destructive tools note self-kill protection and alternatives - Max ~100 words per tool to manage context window token cost - Existing docstring content (params, returns) unchanged
why: When SafetyMiddleware blocks a tool, agents had no prior context about why. The instructions mentioned tier names but not the hiding behavior. what: - Add sentence to _build_instructions(): "Tools outside the active tier are hidden and will not appear in tool listings."
why: Quickstart showed natural-language prompts but never explained the
tool sequence agents execute. The send → wait → capture pattern is the
fundamental workflow and should be taught on the first page.
what:
- Add "How it works" section between "Try it" and "Next steps"
- Shows the 3-step pattern: send_keys → wait_for_text → capture_pane
- Links to individual tool docs via {ref}
why: The tools index showed a flat catalog grouped by safety tier,
but didn't help users select the right tool for their intent.
what:
- Add intent-based decision guide above the Inspect/Act/Destroy grid
- Groups by task: reading content, running commands, creating structure
- Uses {tool} role for badged links, {envvar} for env var ref
why: 15 of 27 tools had no response examples, making it hard for agents and humans to predict output shapes without trial calls. what: - panes.md: get_pane_info, set_pane_title, clear_pane, resize_pane, kill_pane - sessions.md: get_server_info, kill_session, kill_server - windows.md: list_panes, rename_window, select_layout, resize_window, kill_window - options.md: show_environment, set_environment - All responses derived from real MCP outputs, anonymized
why: Tool docs explained atoms but never showed molecules. The send_keys → wait_for_text → capture_pane pattern — the fundamental workflow — appeared nowhere as a complete sequence. what: - Run a command and capture output (the core pattern + race condition warning) - Start a service and wait for readiness (Playwright/web server use case) - Search for errors across all panes (two-phase: search broad, capture narrow) - Set up a multi-pane workspace (create, split, layout, label) - Interrupt a hung command (Ctrl-C with enter=false) - Clean capture without prior output (clear, send, wait, capture) - Added to "Use it" toctree between tools/index and configuration
why: Troubleshooting is symptom-based (after something breaks). Gotchas are preventive — things you should know before they bite. what: - Metadata vs. content (list_panes vs search_panes) - send_keys sends Enter by default (enter=false for C-c) - capture_pane race condition after send_keys - Window names not unique across sessions (use IDs) - Pane IDs globally unique but ephemeral (reset on server restart) - suppress_history requires HISTCONTROL=ignorespace - clear_pane is two tmux commands with a brief gap - Added to topics/ toctree and grid cards
why: No MCP server docs help humans write effective agent instructions. The server's _BASE_INSTRUCTIONS are invisible in the docs, and there is no guidance on prompt patterns, anti-patterns, or system prompt fragments. what: - Print _BASE_INSTRUCTIONS verbatim with explanation of each part - Document dynamic context: safety tier, caller pane awareness - 6 effective prompt patterns with expected tool sequences - 4 anti-patterns with better alternatives - 3 copy-pasteable system prompt fragments (general, safe, dev) - 5 tool selection heuristics for agent decision-making - Added to topics/ toctree and grid cards
…badge
why: {ref} renders as plain text (Sphinx hardcodes nodes.inline in
build_reference_node). {tool} renders as code+badge. Needed a middle
ground: code-formatted linked tool names without badges for dense
contexts like tables and inline prose.
what:
- Add {toolref} role: resolves same labels as {tool}, renders as
<code> inside <a>, no safety badge
- Reuse _tool_ref_placeholder with show_badge=False
- Update prompting.md tables and heuristics to use {toolref}
why: CI has docutils type stubs that expose General/Inline/Element as Any, causing "Class cannot subclass" mypy errors on node subclasses. what: - Add type: ignore[misc] to _safety_badge_node and _tool_ref_placeholder
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #3 +/- ##
==========================================
- Coverage 74.46% 73.01% -1.46%
==========================================
Files 20 20
Lines 1214 1371 +157
Branches 159 175 +16
==========================================
+ Hits 904 1001 +97
- Misses 267 325 +58
- Partials 43 45 +2 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
why: Recipes showed raw JSON tool calls that didn't reflect how
developers actually use the tools. Real usage is scenario-driven:
discover existing state, decide what to do, then act.
Refined through brainstorm-and-refine session (9 originals from
Claude/Gemini/GPT, 3 refinement passes, converged at pass 3).
what:
- Replace 10 JSON-heavy recipes with 6 scenario-driven workflows
- Lead with real ~/work/cv Vite/Playwright discovery example
- Each recipe: Situation → Discover → Decide → Act → The non-obvious part
- Tool calls embedded in reasoning narrative, not standalone JSON
- Uses {tool} for badged refs, {toolref} for inline prose refs
- All params verified against source across 3 refinement passes
- Closes with "What to read next" linking to prompting and gotchas
why: Titles read cleaner without ordinal numbers. The page order already implies sequence.
why: tmuxp should link to its docs. "CV project" is too specific — "React project" is more relatable to the general audience. what: - Link tmuxp to https://tmuxp.git-pull.com - "CV project" → "React project" - session_name "cv" → "myapp"
why: The interrupt recipe references SIGINT and SIGQUIT without
explaining them. Glossary terms with {term} cross-references let
readers hover or click for definitions.
what:
- Add SIGINT and SIGQUIT to docs/glossary.md with send_keys usage
- Link 4 occurrences in docs/recipes.md via {term} role
why: Provides a single-page reference for all custom roles, badges,
and visual elements — useful for contributors and design review.
what:
- Orphaned page at /demo/ (not in any toctree)
- Showcases: {badge}, {tool}, {toolref}, {ref}, {envvar}, {term}
- Shows badges in headings, tables, prose, and dense inline context
- Documents badge HTML anatomy and accessibility features
…ions
why: {ref} renders as plain text. {toolref} renders as code-formatted
linked text, matching how tool names appear elsewhere in the docs.
why: Badge sat slightly higher/lower than the adjacent code element
inside {tool} cross-reference links.
what:
- Add vertical-align: middle to both .sd-badge and code inside
a.reference:has(.sd-badge)
- No inline-flex on the <a> — avoids inflating line box height
why: Standalone {badge} in prose text was misaligned with surrounding
text. The heading flex and link rules handled their contexts, but the
base rule had no vertical-align.
tony
force-pushed
the
2026-03-27-doc-improvements
branch
from
422b6fd to
d78392b
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documentation DX improvements based on a multi-model brainstorm-and-refine session (9 originals from Claude/Gemini/GPT, 3 refinement passes).
Bug fix
"master"references inconf.py+ 1 in__about__.py(broke Edit links, redirects, source links)Runtime guidance (code changes)
_build_instructions()in server.pyDocumentation improvements
Extension improvements
{toolref}role — code-formatted linked tool names without safety badge (for dense contexts like tables)Test plan
uv run ruff check . && uv run mypy && uv run pytest— all passjust build-docs— builds with no new warningspython -c "from libtmux_mcp.tools.pane_tools import send_keys; print(send_keys.__doc__[:200])"