tui-navigation-patterns

TUI Navigation Patterns

Key sequences and navigation patterns for common TUI applications. Use with mcp__plugin_terminal_mux__send-keys.

Slot convention

Every tool addresses a pane by slot, an integer 1–64. The same number returns the same pane on every call; a slot is never the agent's own pane.

• Slot 1 is the visible helper pane beside the user. Use it when the user asked to see the app, or when the app needs a fixed screen size (isolated panes have no window and no fixed size — a layout-sensitive TUI belongs on slot 1).
• Slot 2 or higher with isolated: true runs the app where nobody can see it. That is the default for every example below: a REPL or editor the user did not ask to watch should not appear beside them.
• isolated: true needs an explicit slot on every tool. Omitting it produces: isolated needs a slot number, because a pane you cannot see must be addressable later.
• A slot's kind is fixed at creation. Reusing slot 2 without isolated after it was opened isolated errors with slot 2 is an isolated pane; close it or use another slot.
• Finish with mcp__plugin_terminal_mux__close-pane({ slot: 2 }) → [{"slot":2,"action":"killed"}]. Call mcp__plugin_terminal_mux__list-slots first when you may already hold slots (after compaction); it returns a bare array, [] when empty.

The lifecycle every TUI or REPL session below follows:

mcp__plugin_terminal_mux__start-and-watch({ slot: 2, isolated: true, command, pattern, timeout })
  → { slot: 2, created: true, event: "pattern:…", detail, elapsed, output, paneState }
mcp__plugin_terminal_mux__send-keys({ slot: 2, keys, literal })      // or run-in-repl for REPLs
mcp__plugin_terminal_mux__capture-pane({ slot: 2 })                  // read the screen
mcp__plugin_terminal_mux__close-pane({ slot: 2 })

send-keys Parameter Guide

mcp__plugin_terminal_mux__send-keys takes a single keys string (not an array). The literal flag controls interpretation: