Skip to content

TUI-ENHANCEMENT-PLAN.md

Latest commit

 

History

History
221 lines (165 loc) · 14.2 KB

TUI-ENHANCEMENT-PLAN.md

File metadata and controls

221 lines (165 loc) · 14.2 KB

TUI Enhancement Plan — Claw Code (rusty-claude-cli)

Executive Summary

This plan covers a comprehensive analysis of the current terminal user interface and proposes phased enhancements that will transform the existing REPL/prompt CLI into a polished, modern TUI experience — while preserving the existing clean architecture and test coverage.

1. Current Architecture Analysis

Crate Map

Crate Purpose Lines TUI Relevance
rusty-claude-cli Main binary: REPL loop, arg parsing, rendering, API bridge ~3,600 Primary TUI surface
runtime Session, conversation loop, config, permissions, compaction ~5,300 Provides data/state
api Anthropic HTTP client + SSE streaming ~1,500 Provides stream events
commands Slash command metadata/parsing/help ~470 Drives command dispatch
tools 18 built-in tool implementations ~3,500 Tool execution display

Current TUI Components

Component File What It Does Today Quality
Input input.rs (269 lines) rustyline-based line editor with slash-command tab completion, Shift+Enter newline, history ✅ Solid
Rendering render.rs (641 lines) Markdown→terminal rendering (headings, lists, tables, code blocks with syntect highlighting, blockquotes), spinner widget ✅ Good
App/REPL loop main.rs (3,159 lines) The monolithic LiveCli struct: REPL loop, all slash command handlers, streaming output, tool call display, permission prompting, session management ⚠️ Monolithic
Alt App app.rs (398 lines) An earlier CliApp prototype with ConversationClient, stream event handling, TerminalRenderer, output format support ⚠️ Appears unused/legacy

Key Dependencies

  • crossterm 0.28 — terminal control (cursor, colors, clear)
  • pulldown-cmark 0.13 — Markdown parsing
  • syntect 5 — syntax highlighting
  • rustyline 15 — line editing with completion
  • serde_json — tool I/O formatting

Strengths

  1. Clean rendering pipeline: Markdown rendering is well-structured with state tracking, table rendering, code highlighting
  2. Rich tool display: Tool calls get box-drawing borders (╭─ name ─╮), results show ✓/✗ icons
  3. Comprehensive slash commands: 15 commands covering model switching, permissions, sessions, config, diff, export
  4. Session management: Full persistence, resume, list, switch, compaction
  5. Permission prompting: Interactive Y/N approval for restricted tool calls
  6. Thorough tests: Every formatting function, every parse path has unit tests

Weaknesses & Gaps

  1. main.rs is a 3,159-line monolith — all REPL logic, formatting, API bridging, session management, and tests in one file
  2. No alternate-screen / full-screen layout — everything is inline scrolling output
  3. No progress bars — only a single braille spinner; no indication of streaming progress or token counts during generation
  4. No visual diff rendering — /diff just dumps raw git diff text
  5. No syntax highlighting in streamed output — markdown rendering only applies to tool results, not to the main assistant response stream
  6. No status bar / HUD — model, tokens, session info not visible during interaction
  7. No image/attachment preview — SendUserMessage resolves attachments but never displays them
  8. Streaming is char-by-char with artificial delay — stream_markdown sleeps 8ms per whitespace-delimited chunk
  9. No color theme customization — hardcoded ColorTheme::default()
  10. No resize handling — no terminal size awareness for wrapping, truncation, or layout
  11. Dual app structs — app.rs has a separate CliApp that duplicates LiveCli from main.rs
  12. No pager for long outputs — /status, /config, /memory can overflow the viewport
  13. Tool results not collapsible — large bash outputs flood the screen
  14. No thinking/reasoning indicator — when the model is in "thinking" mode, no visual distinction
  15. No auto-complete for tool arguments — only slash command names complete

2. Enhancement Plan

Phase 0: Structural Cleanup (Foundation)

Goal: Break the monolith, remove dead code, establish the module structure for TUI work.

Task Description Effort
0.1 Extract LiveCli into app.rs — Move the entire LiveCli struct, its impl, and helpers (format_*, render_*, session management) out of main.rs into focused modules: app.rs (core), format.rs (report formatting), session_manager.rs (session CRUD) M
0.2 Remove or merge the legacy CliApp — The existing app.rs has an unused CliApp with its own ConversationClient-based rendering. Either delete it or merge its unique features (stream event handler pattern) into the active LiveCli S
0.3 Extract main.rs arg parsing — The current parse_args() is a hand-rolled parser that duplicates the clap-based args.rs. Consolidate on the hand-rolled parser (it's more feature-complete) and move it to args.rs, or adopt clap fully S
0.4 Create a tui/ module — Introduce crates/rusty-claude-cli/src/tui/mod.rs as the namespace for all new TUI components: status_bar.rs, layout.rs, tool_panel.rs, etc. S

Phase 1: Status Bar & Live HUD

Goal: Persistent information display during interaction.

Task Description Effort
1.1 Terminal-size-aware status line — Use crossterm::terminal::size() to render a bottom-pinned status bar showing: model name, permission mode, session ID, cumulative token count, estimated cost M
1.2 Live token counter — Update the status bar in real-time as AssistantEvent::Usage and AssistantEvent::TextDelta events arrive during streaming M
1.3 Turn duration timer — Show elapsed time for the current turn (the showTurnDuration config already exists in Config tool but isn't wired up) S
1.4 Git branch indicator — Display the current git branch in the status bar (already parsed via parse_git_status_metadata) S

Phase 2: Enhanced Streaming Output

Goal: Make the main response stream visually rich and responsive.

Task Description Effort
2.1 Live markdown rendering — Instead of raw text streaming, buffer text deltas and incrementally render Markdown as it arrives (heading detection, bold/italic, inline code). The existing TerminalRenderer::render_markdown can be adapted for incremental use L
2.2 Thinking indicator — When extended thinking/reasoning is active, show a distinct animated indicator (e.g., 🧠 Reasoning... with pulsing dots or a different spinner) instead of the generic 🦀 Thinking... S
2.3 Streaming progress bar — Add an optional horizontal progress indicator below the spinner showing approximate completion (based on max_tokens vs. output_tokens so far) M
2.4 Remove artificial stream delay — The current stream_markdown sleeps 8ms per chunk. For tool results this is fine, but for the main response stream it should be immediate or configurable S

Phase 3: Tool Call Visualization

Goal: Make tool execution legible and navigable.

Task Description Effort
3.1 Collapsible tool output — For tool results longer than N lines (configurable, default 15), show a summary with [+] Expand hint; pressing a key reveals the full output. Initially implement as truncation with a "full output saved to file" fallback M
3.2 Syntax-highlighted tool results — When tool results contain code (detected by tool name — bash stdout, read_file content, REPL output), apply syntect highlighting rather than rendering as plain text M
3.3 Tool call timeline — For multi-tool turns, show a compact summary: `🔧 bash → ✓ read_file → ✓
3.4 Diff-aware edit_file display — When edit_file succeeds, show a colored unified diff of the change instead of just ✓ edit_file: path M
3.5 Permission prompt enhancement — Style the approval prompt with box drawing, color the tool name, show a one-line summary of what the tool will do S

Phase 4: Enhanced Slash Commands & Navigation

Goal: Improve information display and add missing features.

Task Description Effort
4.1 Colored /diff output — Parse the git diff and render it with red/green coloring for removals/additions, similar to delta or diff-so-fancy M
4.2 Pager for long outputs — When /status, /config, /memory, or /diff produce output longer than the terminal height, pipe through an internal pager (scroll with j/k/q) or external $PAGER M
4.3 /search command — Add a new command to search conversation history by keyword M
4.4 /undo command — Undo the last file edit by restoring from the originalFile data in write_file/edit_file tool results M
4.5 Interactive session picker — Replace the text-based /session list with an interactive fuzzy-filterable list (up/down arrows to select, enter to switch) L
4.6 Tab completion for tool arguments — Extend SlashCommandHelper to complete file paths after /export, model names after /model, session IDs after /session switch M

Phase 5: Color Themes & Configuration

Goal: User-customizable visual appearance.

Task Description Effort
5.1 Named color themes — Add dark (current default), light, solarized, catppuccin themes. Wire to the existing Config tool's theme setting M
5.2 ANSI-256 / truecolor detection — Detect terminal capabilities and fall back gracefully (no colors → 16 colors → 256 → truecolor) M
5.3 Configurable spinner style — Allow choosing between braille dots, bar, moon phases, etc. S
5.4 Banner customization — Make the ASCII art banner optional or configurable via settings S

Phase 6: Full-Screen TUI Mode (Stretch)

Goal: Optional alternate-screen layout for power users.

Task Description Effort
6.1 Add ratatui dependency — Introduce ratatui (terminal UI framework) as an optional dependency for the full-screen mode S
6.2 Split-pane layout — Top pane: conversation with scrollback; Bottom pane: input area; Right sidebar (optional): tool status/todo list XL
6.3 Scrollable conversation view — Navigate past messages with PgUp/PgDn, search within conversation L
6.4 Keyboard shortcuts panel — Show ? help overlay with all keybindings M
6.5 Mouse support — Click to expand tool results, scroll conversation, select text for copy L

3. Priority Recommendation

Immediate (High Impact, Moderate Effort)

  1. Phase 0 — Essential cleanup. The 3,159-line main.rs is the #1 maintenance risk and blocks clean TUI additions.
  2. Phase 1.1–1.2 — Status bar with live tokens. Highest-impact UX win: users constantly want to know token usage.
  3. Phase 2.4 — Remove artificial delay. Low effort, immediately noticeable improvement.
  4. Phase 3.1 — Collapsible tool output. Large bash outputs currently wreck readability.

Near-Term (Next Sprint)

  1. Phase 2.1 — Live markdown rendering. Makes the core interaction feel polished.
  2. Phase 3.2 — Syntax-highlighted tool results.
  3. Phase 3.4 — Diff-aware edit display.
  4. Phase 4.1 — Colored diff for /diff.

Longer-Term

  1. Phase 5 — Color themes (user demand-driven).
  2. Phase 4.2–4.6 — Enhanced navigation and commands.
  3. Phase 6 — Full-screen mode (major undertaking, evaluate after earlier phases ship).

4. Architecture Recommendations

Module Structure After Phase 0

crates/rusty-claude-cli/src/
├── main.rs              # Entrypoint, arg dispatch only (~100 lines)
├── args.rs              # CLI argument parsing (consolidate existing two parsers)
├── app.rs               # LiveCli struct, REPL loop, turn execution
├── format.rs            # All report formatting (status, cost, model, permissions, etc.)
├── session_mgr.rs       # Session CRUD: create, resume, list, switch, persist
├── init.rs              # Repo initialization (unchanged)
├── input.rs             # Line editor (unchanged, minor extensions)
├── render.rs            # TerminalRenderer, Spinner (extended)
└── tui/
    ├── mod.rs           # TUI module root
    ├── status_bar.rs    # Persistent bottom status line
    ├── tool_panel.rs    # Tool call visualization (boxes, timelines, collapsible)
    ├── diff_view.rs     # Colored diff rendering
    ├── pager.rs         # Internal pager for long outputs
    └── theme.rs         # Color theme definitions and selection

Key Design Principles

  1. Keep the inline REPL as the default — Full-screen TUI should be opt-in (--tui flag)
  2. Everything testable without a terminal — All formatting functions take &mut impl Write, never assume stdout directly
  3. Streaming-first — Rendering should work incrementally, not buffering the entire response
  4. Respect crossterm for all terminal control — Don't mix raw ANSI escape codes with crossterm (the current codebase does this in the startup banner)
  5. Feature-gate heavy dependencies — ratatui should be behind a full-tui feature flag

5. Risk Assessment

Risk Mitigation
Breaking the working REPL during refactor Phase 0 is pure restructuring with existing test coverage as safety net
Terminal compatibility issues (tmux, SSH, Windows) Rely on crossterm's abstraction; test in degraded environments
Performance regression with rich rendering Profile before/after; keep the fast path (raw streaming) always available
Scope creep into Phase 6 Ship Phases 0–3 as a coherent release before starting Phase 6
app.rs vs main.rs confusion Phase 0.2 explicitly resolves this by removing the legacy CliApp

Generated: 2026-03-31 | Workspace: rust/ | Branch: dev/rust