Badge & Role Demo

A showcase of the custom Sphinx roles and visual elements available in libtmux-mcp documentation.

Safety badges

Standalone badges via {badge}:

  • readonly — green, read-only operations

  • mutating — amber, state-changing operations

  • destructive — red, irreversible operations

Tool references

{tool} — code-linked with badge

capture_pane readonly · send_keys mutating · search_panes readonly · wait_for_text readonly · kill_pane destructive · create_session mutating · split_window mutating

{toolref} — code-linked, no badge

capture_pane · send_keys · search_panes · wait_for_text · kill_pane · create_session · split_window

{tooliconl} — icon left, outside code

capture_pane · send_keys · search_panes · wait_for_text · kill_pane · create_session · split_window

{tooliconr} — icon right, outside code

capture_pane · send_keys · search_panes · wait_for_text · kill_pane · create_session · split_window

{tooliconil} — icon inline-left, inside code

capture_pane · send_keys · search_panes · wait_for_text · kill_pane · create_session · split_window

{tooliconir} — icon inline-right, inside code

capture_pane · send_keys · search_panes · wait_for_text · kill_pane · create_session · split_window

{ref} — plain text link

capture_pane · send_keys · search_panes · wait_for_text · kill_pane · create_session · split_window

Badges in context

In a heading

These are the actual tool headings as they render on tool pages:

capture_pane readonly

split_window mutating

kill_session destructive

In a table

Tool

Tier

Description

list_sessions

readonly

List all sessions

send_keys

mutating

Send commands to a pane

kill_pane

destructive

Destroy a pane

In prose

Use search_panes to find text across all panes. If you know which pane, use capture_pane instead. After running a command with send_keys, always wait_for_text before capturing.

Dense inline (toolref, no badges)

The fundamental pattern: send_keys → wait_for_text → capture_pane. For discovery: list_sessions → list_panes → get_pane_info.

Environment variable references

LIBTMUX_SOCKET · LIBTMUX_SAFETY · LIBTMUX_SOCKET_PATH · LIBTMUX_TMUX_BIN

Glossary terms

SIGINT · SIGQUIT · MCP · Safety tier · Pane · Session

Admonitions

Tip

Use search_panes before capture_pane when you don’t know which pane has the output you need.

Warning

Do not call capture_pane immediately after send_keys — there is a race condition. Use wait_for_text between them.

Note

All tools accept an optional socket_name parameter for multi-server support.

Badge anatomy

Each badge renders as:

<span class="sd-badge sd-bg-success"
      role="note"
      aria-label="Safety tier: readonly">
  🔍 readonly
</span>

Features:

  • Emoji icon — 🔍 readonly, ✏️ mutating, 💣 destructive (native system emoji, no filters)

  • Matte colors — forest green, smoky amber, matte crimson with 1px border

  • Accessible — role="note" + aria-label for screen readers

  • Non-selectable — user-select: none so copying tool names skips badge text

  • Context-aware sizing — slightly larger in headings, smaller inline

  • Sidebar compression — badges collapse to colored dots in the right-side TOC

  • Heading flex — h2/h3/h4:has(.sd-badge) centers badge against cap-height