Design & UI
ai-coding-agents-terminal-ui
Designs terminal-first coding-agent UX: REPL, prompt input, status lines, keybindings, display modes. Use when shaping TUI rendering, history, or background-task navigation.
vasilyu1983 · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add vasilyu1983/AI-Agents-public --skill ai-coding-agents-terminal-uiAbout this skill
name: ai-coding-agents-terminal-ui description: "Designs terminal-first coding-agent UX: REPL, prompt input, status lines, keybindings, display modes. Use when shaping TUI rendering, history, or background-task navigation." compatibility: Portable core. Works on Claude Code and Codex. version: "1.1" last_validated: 2026-07-11
AI Coding Agents Terminal UI
Use this skill to design or review the terminal-first user experience of a coding-agent runtime: REPL structure, prompt input, message rendering, command queues, virtualized history, interrupt behavior, notifications, and background-task navigation.
This skill is for terminal interaction patterns, not generic desktop app UX.
ASCII Flow
runtime events
|
v
host-owned REPL state
transcript + prompt input + command queue + background tasks + overlays
|
v
render pipeline
message model + virtualized history + notifications + task surfaces
|
v
input state machine
idle | editing | running | search | overlay | teammate view | remote/viewer
|
v
runtime action
submit, interrupt, foreground task, kill task, search, rewind, resume
Quick Reference
| Question | Read | Outcome |
|---|---|---|
| How should the REPL, prompt, and history work? | references/repl-message-input-and-history.md | Message model, prompt queue, input behavior, interrupt handling |
| How should background work and large histories render? | references/background-work-notifications-and-virtualization.md | Background-task UX, notifications, virtual scroll, and teammate navigation |
| What are the input states and keybindings for background navigation? | references/input-state-machine.md | State machine, transition table, mode-specific keybindings, invariants, failure modes |
| How do ToolSearch deferred-tool results render in the REPL? | references/recipe-toolsearch-render.md | Discovery annotation, collapse behavior, permission-prompt sequencing, scroll rules |
| What OpenAI Codex TUI patterns should be snapshot-tested? | references/openai-codex-tui-status-and-snapshot-patterns.md | Status line/title, approval modals, hook/app-server warnings, narrow terminal states |
| What are Claude Code's real status-line fields, keybinding contexts, and Agent Teams display modes? | references/input-state-machine.md | Verified statusLine JSON fields, keybindings.json contexts/reserved keys, in-process vs split-pane display modes |
When To Use
- Design a terminal-first coding-agent REPL or prompt UI
- Decide how message history, search, rewind, and interrupt should behave
- Add background-task surfaces, teammate navigation, or task detail dialogs
- Improve large-session rendering with virtualization or deferred updates
- Separate interactive UI behavior from headless or SDK behavior
Use Other Skills
| Need | Use Instead |
|---|---|
| Background task runtime design | ../ai-coding-agents-tasks/SKILL.md |
| Remote or bridge runtime | ../ai-coding-agents-remote-runtime/SKILL.md |
| Tool approval architecture | ../ai-coding-agents-permissions/SKILL.md |
Default Workflow
- Keep the REPL as a host-owned state machine. Prompt input, message history, background tasks, and overlays should share one session model.
- Separate transcript data from render strategy. Large histories need virtualization and deferred rendering, not truncated state ownership.
- Use dedicated stores for high-frequency signals. Command queues, scroll state, and background-task counts should not force full-tree re-renders.
- Treat interrupt behavior as first-class UX. Idle escape, active interrupt, teammate-view escape, and remote interrupt are different actions.
- Make background work navigable. Users should be able to inspect, foreground, or kill tasks without losing the main session.
- Model interactive-only features explicitly. Some callbacks and overlays exist only in REPL mode and should not leak into headless paths.
- Test long sessions. Verify search, rewind, virtualization, notification timing, and prompt-input persistence after hundreds of turns.
Host Rules
- The UI should not own semantic session state that the runtime cannot restore.
- Large histories should optimize mounting and scroll math, not just terminal paint.
- Background work deserves a first-class dialog or tree, not a single badge count.
- Prompt input should survive round-trips through overlays, interrupts, and search.
- Interactive UI behavior should degrade cleanly when the runtime is headless, remote, or viewer-only.
Build Order
- Define the host-owned REPL state machine.
- Separate transcript data from render state and scroll math.
- Add prompt input persistence through overlays and interrupts.
- Add background-task navigation and notifications.
- Add virtualization for long histories.
- Add remote, headless, and viewer-only degradation rules.
Core Invariants
- The UI renders runtime state; it does not become the only owner of it.
- Prompt input must survive mode changes and overlays.
- Interrupt semantics must map to explicit runtime actions.
- Background work must be inspectable without destroying main-session context.
- Long-session performance must come from virtualization, not silent truncation of semantic history.
Failure Modes
- Losing prompt input when entering search, overlays, or teammate views.
- Treating idle escape, active interrupt, and exit as one key path.
- Background-task dialogs drifting out of sync with runtime task state.
- Scroll jumps and