Amr Gharbeia
4e9431ec1d
passepartout v0.7.2 (Gate Trace + HITL + Search + 11 more features): - Gate trace visualization with Ctrl+G toggle - HITL inline panels with styled collapse on approve/deny - Agent identity file + /identity command - Safe-tool read-only allowlist - Message search mode with Up/Down nav and highlights - Context budget visibility with section breakdown - Session rewind /sessions /resume /rewind - Undo/redo per operation - Context debugging /context why /context dropped - Tool hardening (timeouts, write verify, read-only cache) - Tag stack severity tiers + trigger counts - Merkle provenance audit + audit-verify - Self-help /help <topic> reads USER_MANUAL.org - Live CONFIG section in system prompts - Pads: Page Up/Down scroll by 10 lines Core 92/92 TUI Main 104/104 TUI View 29/29 Neuro 13/13
6.8 KiB
Comparative TUI Study — SOTA Agent Terminal Interfaces
- Purpose
- Findings Summary
- Claude Code TUI
- OpenCode TUI
- OpenClaw TUI
- Hermes Agent TUI
- What Passepartout Should Adopt
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
- Streaming text — single biggest UX gap. Every competitor does it.
- Ctrl+C 3-level cascade — industry standard. Interrupt → abort → exit.
- Sidebar — Passepartout's unique differentiator (gate trace invisibility → visibility).
- Command palette (Ctrl+P) — single entry point for all actions.
- 8+ TrueColor theme presets — current 4 are insufficient.
- Skin system — personality through customization.
- Adaptive layout — 3 tiers (terminal width-based).
- Full markdown — code blocks with highlighting, bold, italic, links.
- Mouse support — scroll wheel, click to position cursor.
- Unicode width awareness — CJK/emoji rendering correctness.