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: ``` mcp__plugin_terminal_mux__send-keys({ slot, keys, literal, enter }) literal: true (default) — text sent byte-for-byte; special chars NOT interpreted Use for: typing commands, text to insert, query strings literal: false — text interpreted as a named key Use for: control sequences, navigation keys, any non-printable key enter: true — append an Enter keystroke after the keys (default false) Examples: mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "Escape", literal: false }) mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: ":wq", literal: true }) mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "Enter", literal: false }) mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "C-c", literal: false }) ``` Every call returns `{ slot, created }`; `created: true` means the slot was opened by this call, `false` means the pane already existed. **To type text then press Enter**, one call with `enter: true`: ``` mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "ls -la", enter: true }) ``` **Named keys** (`literal: false`). This is the whole vocabulary the contract guarantees: | What you want | Keys string | literal | |--------------|-------------|---------| | Enter / Return | `"Enter"` | `false` | | Escape | `"Escape"` | `false` | | Tab | `"Tab"` | `false` | | Space | `"Space"` | `false` | | Backspace | `"BSpace"` | `false` | | Arrow Up / Down / Left / Right | `"Up"`, `"Down"`, `"Left"`, `"Right"` | `false` | | Page Up / Page Down | `"PageUp"`, `"PageDown"` | `false` | | Home / End | `"Home"`, `"End"` | `false` | | F1–F12 | `"F1"`, `"F2"`, ..., `"F12"` | `false` | | Ctrl+x (any letter) | `"C-x"` — e.g. `"C-c"`, `"C-d"`, `"C-l"`, `"C-z"` | `false` | | Alt+x (any letter) | `"M-x"` | `false` | | Type plain text | `"my text here"` | `true` (default) | Any other name passes through to tmux unmapped and is not portable. --- ## General Terminal Controls These work in almost any terminal context: | Action | Keys | literal | |--------|------|---------| | Interrupt running process | `"C-c"` | `false` | | Send EOF / exit shell | `"C-d"` | `false` | | Suspend process (move to background) | `"C-z"` | `false` | | Clear screen (redraw) | `"C-l"` | `false` | | Kill current line (clear input) | `"C-u"` | `false` | | Delete word before cursor | `"C-w"` | `false` | ``` mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "C-c", literal: false }) // interrupt a stuck process ``` --- ## vim **Modes**: Normal mode (default), Insert mode (`i`), Visual mode (`v`), Command mode (`:`) ### Essential Navigation | Action | Keys | Context | |--------|------|---------| | Enter insert mode | `i` | Normal mode | | Enter insert mode at end of line | `A` | Normal mode | | Return to normal mode | `Escape` | Any mode | | Save and quit | `:wq` + `Enter` | Normal mode | | Save without quitting | `:w` + `Enter` | Normal mode | | Quit without saving | `:q!` + `Enter` | Normal mode | | Open file | `:e {filename}` + `Enter` | Normal mode | | Move to start of file | `gg` | Normal mode | | Move to end of file | `G` | Normal mode | | Move to line N | `:{N}` + `Enter` | Normal mode | | Delete current line | `dd` | Normal mode | | Copy (yank) current line | `yy` | Normal mode | | Paste | `p` | Normal mode | | Undo | `u` | Normal mode | | Redo | `C-r` (literal: false) | Normal mode | | Search forward | `/pattern` + `Enter` | Normal mode | | Search backward | `?pattern` + `Enter` | Normal mode | | Next search result | `n` | Normal mode | | Previous search result | `N` | Normal mode | | Page down | `C-f` (literal: false) | Normal mode | | Page up | `C-b` (literal: false) | Normal mode | ### vim Workflow Example ``` // Launch vim in an isolated slot mcp__plugin_terminal_mux__start-and-watch({ slot: 2, isolated: true, command: "vim myfile.ts", pattern: "~", // vim blank line tildes indicate loaded timeout: 10 }) → WatchResult mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "G", literal: true }) // end of file mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "o", literal: true }) // insert on new line below mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "// Added by Claude", literal: true }) mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "Escape", literal: false }) // back to normal mode mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: ":wq", enter: true }) // save and quit // Wait for shell prompt to return mcp__plugin_terminal_mux__watch-pane({ slot: 2, triggers: "shell,idle:2", timeout: 10 }) → WatchResult mcp__plugin_terminal_mux__close-pane({ slot: 2 }) ``` --- ## nano nano is simpler than vim — no mode switching. Ctrl shortcuts are shown in the bottom bar. | Action | Keys | literal | |--------|------|---------| | Save file | `"C-o"` then `"Enter"` | `false` | | Exit | `"C-x"` | `false` | | Search | `"C-w"` then type pattern + `"Enter"` | `false` / `true` / `false` | | Cut current line | `"C-k"` | `false` | | Paste cut line | `"C-u"` | `false` | | Page down | `"C-v"` | `false` | | Page up | `"C-y"` | `false` | ``` // Edit a file in nano, save, and exit mcp__plugin_terminal_mux__start-and-watch({ slot: 2, isolated: true, command: "nano myfile.txt", pattern: "GNU nano", timeout: 10 }) // Type some content mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "Hello from Claude", literal: true }) // Save: Ctrl+O mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "C-o", literal: false }) // Confirm filename with Enter mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "Enter", literal: false }) // Exit: Ctrl+X mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "C-x", literal: false }) mcp__plugin_terminal_mux__watch-pane({ slot: 2, triggers: "shell,idle:2", timeout: 10 }) mcp__plugin_terminal_mux__close-pane({ slot: 2 }) ``` --- ## htop / btop System monitors. Read-only — never send destructive keys unless the user approved them (in person on the main thread; in the dispatching prompt for a subagent). ### htop | Action | Keys | literal | |--------|------|---------| | Quit | `"q"` | `true` | | Sort by column | `"F6"` | `false` | | Kill selected process | `"F9"` (requires user confirmation) | `false` | | Toggle tree view | `"F5"` | `false` | | Search processes | `"F3"` | `false` | | Filter processes | `"F4"` | `false` | | Help | `"F1"` | `false` | | Navigate processes | `"Up"`, `"Down"` | `false` | | Scroll right | `"Right"` | `false` | ### btop | Action | Keys | literal | |--------|------|---------| | Quit | `"q"` | `true` | | Navigate between panels | `"Tab"` | `false` | | Kill selected process | `"k"` | `true` | | Sort options | `"f"` | `true` | | Toggle CPU core graph | `"1"` | `true` | | Help | `"h"` | `true` | ``` // Read system stats from htop mcp__plugin_terminal_mux__start-and-watch({ slot: 2, isolated: true, command: "htop", pattern: "CPU\\[", timeout: 10 }) // pattern: CPU bar header mcp__plugin_terminal_mux__capture-pane({ slot: 2 }) // read CPU/memory // Quit cleanly mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "q", literal: true })