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:

Any other name passes through to tmux unmapped and is not portable.

General Terminal Controls

These work in almost any terminal context:

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

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.

// 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 without user confirmation.

htop

btop

// 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 })
mcp__plugin_terminal_mux__watch-pane({ slot: 2, triggers: "shell,idle:2", timeout: 5 })
mcp__plugin_terminal_mux__close-pane({ slot: 2 })

less / man (Pagers)

// Read a man page
mcp__plugin_terminal_mux__start-and-watch({ slot: 2, isolated: true, command: "man curl", pattern: "CURL", timeout: 10 })
// Search for "timeout"
mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "/timeout", enter: true })
mcp__plugin_terminal_mux__capture-pane({ slot: 2 })
// Quit
mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "q", literal: true })
mcp__plugin_terminal_mux__close-pane({ slot: 2 })

psql (PostgreSQL CLI)

psql prompts: =# (normal), -# (command continuation)

Prefer run-in-repl for psql interactions — it handles prompt detection and returns clean output. exited is always present in its response: true means the REPL process ended.

// Connect and run queries using run-in-repl
mcp__plugin_terminal_mux__start-and-watch({ slot: 2, isolated: true, command: "psql $DATABASE_URL", pattern: "=#", timeout: 15 })
  → WatchResult

// Run query — output returned directly, no screen scraping
mcp__plugin_terminal_mux__run-in-repl({ slot: 2, input: "SELECT id, email FROM users ORDER BY id LIMIT 10;", promptPattern: "=#", timeout: 10 })
  → { slot: 2, created: false, output: "...", exited: false }

// Quit cleanly
mcp__plugin_terminal_mux__run-in-repl({ slot: 2, input: "\\q", promptPattern: "\\$", timeout: 5 })
mcp__plugin_terminal_mux__close-pane({ slot: 2 })

mongosh (MongoDB Shell)

mcp__plugin_terminal_mux__start-and-watch({ slot: 2, isolated: true, command: "mongosh $MONGO_URI", pattern: ">", timeout: 15 })
mcp__plugin_terminal_mux__run-in-repl({ slot: 2, input: "db.users.find({}).limit(5)", promptPattern: ">", timeout: 10 })
  → { slot: 2, created: false, output: "...", exited: false }
mcp__plugin_terminal_mux__run-in-repl({ slot: 2, input: ".exit", promptPattern: "\\$", timeout: 5 })
mcp__plugin_terminal_mux__close-pane({ slot: 2 })

redis-cli

mcp__plugin_terminal_mux__start-and-watch({ slot: 2, isolated: true, command: "redis-cli", pattern: "127\\.0\\.0\\.1:\\d+>", timeout: 10 })
mcp__plugin_terminal_mux__run-in-repl({ slot: 2, input: "INFO server", promptPattern: "127\\.0\\.0\\.1:\\d+>", timeout: 10 })
  → { slot: 2, created: false, output: "...", exited: false }
mcp__plugin_terminal_mux__run-in-repl({ slot: 2, input: "quit", promptPattern: "\\$", timeout: 5 })
mcp__plugin_terminal_mux__close-pane({ slot: 2 })

turso (Turso DB Shell)

mcp__plugin_terminal_mux__start-and-watch({ slot: 2, isolated: true, command: "turso db shell mydb", pattern: ">", timeout: 15 })
mcp__plugin_terminal_mux__run-in-repl({ slot: 2, input: "SELECT * FROM users LIMIT 5;", promptPattern: ">", timeout: 10 })
  → { slot: 2, created: false, output: "...", exited: false }
mcp__plugin_terminal_mux__run-in-repl({ slot: 2, input: ".quit", promptPattern: "\\$", timeout: 5 })
mcp__plugin_terminal_mux__close-pane({ slot: 2 })

lazygit

lazygit is a popular TUI for git. It uses a panel-based layout.

// Launch lazygit in an isolated slot
mcp__plugin_terminal_mux__start-and-watch({ slot: 2, isolated: true, command: "lazygit", pattern: "Commit list|Files|Branches", timeout: 10 })

// Stage and commit changes
mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "a", literal: true })   // stage all
mcp__plugin_terminal_mux__capture-pane({ slot: 2 })  // verify staged
mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "c", literal: true })   // open commit dialog
mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "fix: update auth flow", enter: true })
mcp__plugin_terminal_mux__capture-pane({ slot: 2 })  // verify commit created
mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "q", literal: true })   // quit
mcp__plugin_terminal_mux__watch-pane({ slot: 2, triggers: "shell,idle:2", timeout: 10 })
mcp__plugin_terminal_mux__close-pane({ slot: 2 })

tig (Text-mode Interface for Git)

tig is an ncurses-based git repository browser.

k9s (Kubernetes TUI)

Docker (docker logs follow mode)

// Follow container logs
mcp__plugin_terminal_mux__start-and-watch({ slot: 2, isolated: true, command: "docker logs -f myapp", pattern: "started|ready|listening", triggers: "error,exit", timeout: 30 })
// Read latest log lines via scrollback
mcp__plugin_terminal_mux__capture-pane({ slot: 2, lines: 50 })
// Stop following
mcp__plugin_terminal_mux__send-keys({ slot: 2, keys: "C-c", literal: false })
mcp__plugin_terminal_mux__close-pane({ slot: 2 })

Node.js / Bun REPL

mcp__plugin_terminal_mux__start-and-watch({ slot: 2, isolated: true, command: "node", pattern: "> ", timeout: 10 })
mcp__plugin_terminal_mux__run-in-repl({ slot: 2, input: "1 + 1", promptPattern: "> ", timeout: 5 })
  → { slot: 2, created: false, output: "1 + 1\n2", exited: false }
mcp__plugin_terminal_mux__run-in-repl({ slot: 2, input: ".exit", promptPattern: "\\$", timeout: 5 })
mcp__plugin_terminal_mux__close-pane({ slot: 2 })

Python REPL

Observed round trip:

mcp__plugin_terminal_mux__start-and-watch({ slot: 2, isolated: true, command: "python3", pattern: ">>>" })
  → { slot: 2, created: true, event: "pattern:>>>", detail: "Ready — matched: >>>", elapsed: 0.51,
      output: "…", paneState: { foregroundCmd: "Python", isAlive: true, waitingForInput: true, … } }
mcp__plugin_terminal_mux__run-in-repl({ slot: 2, input: "1+1", promptPattern: ">>>" })
  → { slot: 2, created: false, output: "1+1\n2", exited: false }
mcp__plugin_terminal_mux__close-pane({ slot: 2 })
  → [{ slot: 2, action: "killed" }]

irb (Ruby REPL)

Application Detection Quick Reference

Use this table to detect what application is running from a capture-pane snapshot, or from the foregroundCmd field of pane-state / list-slots:

Prompt Detection (when waiting for app to be ready)

Use start-and-watch with a pattern matching the app's ready state. For REPLs, then use run-in-repl for subsequent interactions — it handles prompt detection automatically.

For TUI apps: After start-and-watch confirms the app is loaded, use capture-pane (fast, optimistic read) or watch-pane with user_input or idle:N trigger to wait for the app to settle before each subsequent keystroke.