#+TITLE: Comparative TUI Study — SOTA Agent Terminal Interfaces
#+FILETAGS: :notes:comparative-study:tui:ux:

* Purpose

Deep analysis of TUI implementations across Claude Code, OpenCode, OpenClaw, and Hermes Agent. Informs Passepartout's TUI roadmap (v0.7.0–v0.8.3).

* Findings Summary

| Dimension | Claude Code | OpenCode | OpenClaw | Hermes | Passepartout Gap |
|-----------+-------------+----------+----------+--------+------------------|
| Renderer | Custom React/Yoga WASM | SolidJS/@opentui | pi-tui/Croatoan-like | Rich/prompt_toolkit | Croatoan (ncurses) |
| Streaming | Incremental markdown | AI SDK streaming | Streaming watchdog | Always streaming | Not implemented |
| Markdown | StreamingMarkdown lexer | React components | HyperlinkMarkdown | Rich markup | Not implemented |
| Ctrl keys | Full readline + Vim mode | Vim-style + 3-level Ctrl+C | 3-level Ctrl+C | 3-level cascade | Only Enter/Tab/arrows |
| Sidebar | Plugin-slot system (42 col) | Plugin-based sidebar | No sidebar | No sidebar | Planned v0.8.0 |
| Themes | 89 tokens, 6 variants, daltonized | 33 presets, system-theme auto | 2 dark/light with COLORFGBG | 8 skins, YAML, kawaii | 4 presets, 7/27 keys used |
| Mouse | Yes (Mode 1003/1000) | Yes (click, hover) | Scroll wheel only | Yes (curses fallback) | Not implemented |
| Animations | Spinner, shimmer, blink, logo | Animated logo, spinner | Loader + shimmer | KawaiiSpinner, faces | Spinner only |
| Onboarding | 9-dialog first-run flow | Setup wizard in TUI | Web UI setup | Banner + /setup | Bash stdin/stdout |

* Claude Code TUI

**Renderer**: Custom TypeScript React reconciler (~50K lines total in src/ink/). Uses:
- Yoga Layout WASM for Flexbox-based terminal layout
- Double-buffered Screen with CharPool/StylePool/HyperlinkPool interning
- Blit-based diff rendering — unchanged regions copied in bulk via TypedArray.set()
- Output caching with charCache persisting across frames
- 5 React contexts: AppContext, TerminalFocusContext, TerminalSizeContext, StdinContext, ClockContext

**Spinner**: 5-mode state machine (requesting/thinking/responding/tool-input/tool-use). Braille characters ⠋⠙⠹... cycling at variable speeds (50ms requesting, 200ms thinking). Stall detection: color interpolates theme → ERROR_RED {r:171,g:43,b:63}. Reduced motion: slow-pulse ●.

**Keybindings**: 64 actions in 20 contexts, Zod-validated JSON config (`~/.claude/keybindings.json`). Chord shortcuts. Kitty Keyboard Protocol support. Vim mode: 4-mode state machine (Normal/Insert/Visual/Command) with operators, motions, text objects.

**Design system**: 89 color tokens across 6 theme variants (dark, light, dark-daltonized, light-daltonized, dark-ansi, light-ansi). Theme-aware ThemedBox/ThemedText components. ProgressBar using 9 Unicode block characters (▏▎▍▌▋▊▉█) for sub-character precision.

**Component highlights**: PromptInput.tsx (2,339 lines), ScrollBox with 80-row overscan + 40-row scroll quantum, 200ms anti-misclick on permission dialogs.

* OpenCode TUI

**Renderer**: SolidJS with custom @opentui terminal rendering framework. Solid signals/drive terminal updates. Component tree rendered to terminal cells via Yoga Flexbox.

**Slot-based plugin system**: TUIPluginRuntime.Slot. 10+ slots (app, home_logo, home_prompt, sidebar_title, sidebar_content). Modes: replace, single_winner, stack. Plugins have order numbers.

**Layout**: Home screen (centered logo + prompt + tips) + Session screen (chat area + 42-char sidebar + prompt + permissions). Sidebar becomes absolute overlay when terminal < 120 cols.

**Themes**: 33 built-in JSON themes. System theme auto-generates from terminal's 16-color palette via luminance-aware scaling. Preview-on-navigate: theme applies on hover, reverts on cancel.

**Key UX patterns**: Colored left border per agent (┃ Unicode HEAVY VERTICAL BAR). Fuzzy autocomplete with frecency (frequency + recency scoring). Ripple/field interactive logo. Sticky scroll with macOS-style momentum. Paste summary auto-generation. Exit with session resume info.

* OpenClaw TUI

**Renderer**: pi-tui framework with custom component tree. ChatLog component with streaming content, tool execution display, BTW inline messages. 180 component cap with pruning.

**Layout**: Header (accent bold), chat log (flexible), status bar (Loader spinner or text), footer (dim, info pipeline), editor (always focused). No sidebar in TUI — navigation via slash commands + overlays.

**Themes**: 2 palettes (dark/light), 17 semantic tokens. Auto-detection via COLORFGBG + WCAG luminance calculation. Tool states colored by background (pending=blue-tinted, success=green-tinted, error=red-tinted).

**Streaming watchdog**: If response is streaming for >30s without new deltas, auto-resets and injects system message.

**Key UX patterns**: Paste burst coalescer for Windows Git Bash/macOS terminals. OSC 8 hyperlinks in messages. RTL text isolation. Component drop removes all internal reference map entries.

* Hermes Agent TUI

**Renderer**: prompt_toolkit Application + Rich markup. Full CLI is 10,275 lines in cli.py. Bottom-pinned HSplit layout with conditional containers.

**Components**: Welcome banner (Rich Panel with caduceus art, tool/skill/MCP listing), status bar (model, context gauge [████░░], duration), input area (TextArea with SlashCommandCompleter, FileHistory, conditional processors), clarify panel, approval panel, sudo panel, model picker.

**Skin system**: 8 built-in skins in YAML, 40+ color slots, spinner customization (faces, verbs, wings), branding strings, tool emojis. User skins in ~/.hermes/skins/. Hot-swap via /skin. Skin-aware ANSI lazy resolution.

**Responsive design**: 3-tier width adaptation (>76 cols full, >52 cols compact, <52 cols minimal). CJK-aware via prompt_toolkit.utils.get_cwidth. Termux detection.

**Keybindings**: Enter state machine routes to correct handler (sudo/secret/approval/clarify/model_picker/normal). Ctrl+C 3-level cascade. Busy mode: interrupt/queue/steer.

**KawaiiSpinner**: 9 spinner styles, 10 waiting faces, 15 thinking faces, 15 thinking verbs. All overridable per skin. Wing decorations ⟪⚔ ... ⚔⟫.

* What Passepartout Should Adopt

1. **Streaming text** — single biggest UX gap. Every competitor does it.
2. **Ctrl+C 3-level cascade** — industry standard. Interrupt → abort → exit.
3. **Sidebar** — Passepartout's unique differentiator (gate trace invisibility → visibility).
4. **Command palette (Ctrl+P)** — single entry point for all actions.
5. **8+ TrueColor theme presets** — current 4 are insufficient.
6. **Skin system** — personality through customization.
7. **Adaptive layout** — 3 tiers (terminal width-based).
8. **Full markdown** — code blocks with highlighting, bold, italic, links.
9. **Mouse support** — scroll wheel, click to position cursor.
10. **Unicode width awareness** — CJK/emoji rendering correctness.