tui

> **IMPORTANT: EXECUTION CONTEXT** > This skill describes *what to do* — domain patterns and decision-making. > It does NOT describe *how* to call the API. > > 1. **If you have `wsh_*` tools** (check your toolkit for `wsh_send_input`, > `wsh_get_screen`, etc.): use them directly. Operation names in this > skill generally map to tool names (e.g., "send input" → `wsh_send_input`). > When in doubt, list your available `wsh_*` tools. > 2. **If you do NOT have `wsh_*` tools**: you are in HTTP/curl fallback mode. > **DO NOT GUESS endpoints or CLI subcommands.** > Load the full API reference first: search your workspace for > `skills/core/` and read `SKILL.md`. It contains every endpoint > with working curl examples and a bootstrap sequence. > 3. **Quick bootstrap**: `curl -sf --unix-socket ${XDG_RUNTIME_DIR:-/tmp}/wsh/default.http.sock http://localhost/health` > — if that fails: `wsh server -L agent-$$ --ephemeral &` and retry. # wsh:tui — Operating Full-Screen Terminal Applications Some programs take over the entire terminal — vim, htop, lazygit, k9s, midnight commander. They use the terminal's "alternate screen buffer," a fixed grid where the program controls every character position. This is a fundamentally different interaction model from command-and-response. ## Detecting Alternate Screen Mode When a TUI is active, the screen response includes: "alternate_active": true This tells you you're in grid mode. The screen is no longer a log of output — it's a 2D canvas the program redraws at will. Scrollback is irrelevant while alternate screen is active; the program owns the entire display. When the TUI exits, `alternate_active` flips back to `false` and the normal scrollback view resumes exactly where it left off. None of the TUI's screen content leaks into scrollback. ## Reading a 2D Grid In a TUI, screen position matters. A line isn't just text — it's a row in a spatial layout. Use `styled` format here; formatting carries critical information: - **Bold or highlighted text** often marks the selected item - **Color differences** distinguish panes, headers, status bars - **Inverse/reverse video** typically indicates cursor position or selection - **Dim or faint text** marks inactive elements Read the full screen and interpret it spatially. The first few lines are often a header or menu bar. The last line or two are often a status bar or command input. The middle is content. ## Navigation TUI programs don't use typed commands — they use keystrokes. Every key does something different depending on context. You need to know the program's keybindings. ### Universal Navigation Keys Arrow keys, Page Up/Down, Home/End, Tab (cycle panes), Enter (confirm/open), Escape (cancel/back). ### Vim-Style Navigation Many TUIs adopt vim conventions: h, j, k, l # left, down, up, right g, G # top, bottom / # search n, N # next/previous match q # quit ### Sending Keystrokes Send one keystroke at a time. Wait briefly between keystrokes to let the TUI redraw — TUIs repaint the screen after each input, and you need the updated screen to know where you are. send: j # move down wait (500ms) read screen # see what's selected now send: j # move down again wait (500ms) read screen # verify position This is slower than blasting keys, but reliable. You're navigating blind if you don't read between keystrokes. ## Understanding TUI Layouts When you first enter a TUI, read the full screen and build a mental map. Most TUIs follow common layout patterns: ### Typical Structure +----------------------------------+ | Menu bar / Title bar | <- rows 0-1 +----------------------------------+ | | | Main content area | <- middle rows | (list, editor, dashboard) | | | +----------------------------------+ | Status bar / Help / Command line | <- last 1-2 rows +----------------------------------+ ### Finding Your Bearings - **Status bar** (usually bottom): shows mode, filename, position, hints. Read this first — it often tells you everything you need to know about current state. - **Help hints**: many TUIs show keybinding hints at the bottom or top. Look for text like `q:quit j/k:navigate ?:help` or `^X Exit ^O Save`. - **The selected item**: look for inverse video, bold, or color-highlighted text in the content area. That's your cursor position. - **Pane borders**: look for `|`, `-`, `+` characters or box-drawing characters. These indicate split panes. Only one pane is active at a time — Tab or Ctrl+W typically switches between them. ### Modals and Dialogs TUIs often pop up confirmation dialogs or input fields over the main content. These appear as a differently-styled block in the middle of the screen. Look for: - A bordered box that wasn't there before - Text like "Are you sure?" or "Enter filename" - Highlighted buttons like `[ OK ] [ Cancel ]` When a modal is active, navigation keys operate on the modal, not the content behind it. ## Common Applications You don't need to memorize every TUI's keybindings. But knowing the basics for frequently encountered programs helps. ### Text Editors **vim/neovim:** Starts in Normal mode. `i` to insert text, `Esc` to return to Normal. `:w` save, `:q` quit, `:wq` both. If lost, press `Esc Esc` then `:q!` to quit without saving. **nano:** Simpler. Just type to edit. Keybindings shown at bottom. `^` means Ctrl. `^X` exits, `^O` saves. ### Git TUIs **lazygit:** Pane-based. Tab switches panes (files, branches, commits). `j/k` navigates, Enter opens, `space` stages, `c` commits, `p` pushes, `q` quits. ### System Monitors **htop/top:** Shows processes. `j/k` or arrows to navigate, `k` to kill a process, `q` to quit. `F` keys for actions (shown at bottom). ### Kubernetes **k9s:** Resource browser. `:` opens command mode for resource type (`:pods`, `:deployments`). `j/k` navigates, `Enter` drills in, `Esc` goes back, `d` describe, `l` logs. ### General Strategy for Unfamiliar TUIs 1. Read the screen — look for help hints at top or bottom 2. Try `?` or `h` — most TUIs open a help screen 3. Try F1 — some use function keys for help 4. Read the help, then press `q` or `Esc` to close it 5. If completely stuck: `q`, `Esc`, `:q`, `Ctrl+C`, `Ctrl+Q` — try these in order to exit ## Exiting a TUI Getting out is as important as getting in. When you're done with a TUI, you need to return to the normal shell prompt. ### Exit Strategies (in order of preference) 1. Use the program's quit command (`q`, `:q`, `Ctrl+X`) 2. Check the status bar for exit hints 3. Press `Esc` to back out of any modal or sub-mode first 4. If the program won't quit cleanly, `Ctrl+C` 5. Last resort: `Ctrl+Z` to suspend, then `kill %1` ### Confirming You're Out After sending a quit command, wait for idle, then check: "alternate_active": false If this is `false`, you're back in normal mode with your shell prompt. If it's still `true`, the TUI is still running — your quit command may not have worked, or the program asked for confirmation before exiting. ## Pitfalls ### Don't type commands into a TUI A TUI is not a shell. If you send `ls -la\n` into vim, you'll get those characters inserted into the document. Always know what mode you're in before sending input. ### Don't blast keystrokes TUIs redraw the screen after each input. If you send 10 `j` keystrokes without reading in between, you won't know where you landed. Navigate one step at a time. ### Watch for mode changes Many TUIs have multiple modes (vim's Normal/Insert/Visual, lazygit's panes). The same key does different things in different modes. Read the screen after each action to confirm you're in the mode you expect. ### Alternate screen within alternate screen If you launch a TUI from within a TUI (e.g., vim from within a file manager), `alternate_active` is still just `true`. You need to track the nesting yourself by remembering what you launched and how many layers deep you are.