Challenge: Design and build a beautiful modern TUI for yoyo

[danstis]

The challenge:

Design and implement a modern, beautiful TUI for yoyo that becomes the primary interactive experience for using the agent in the terminal.

This should not just be a basic text wrapper around the current REPL. It should be treated as a product-level interface with thoughtful UX, strong keyboard navigation, good layout behaviour, visual polish, and room for future expansion.

As part of this challenge, yoyo should first perform research into:

1. Rust TUI library options

   • Investigate the main libraries and supporting crates that could be used to build a polished TUI
   • Compare tradeoffs such as ecosystem maturity, rendering model, cross-platform support, input handling, performance, layout flexibility, theming, accessibility, testing, and maintainability
   • A likely starting point is the Ratatui + Crossterm ecosystem, since Ratatui is a Rust library for rich terminal UIs and Crossterm provides cross-platform terminal manipulation/input support.

2. Competitive research / inspiration

   • Study the UX of modern AI-agent terminal tools and identify patterns worth borrowing
   • Claude Code should be treated as the benchmark to look up to for overall AI-agent terminal UX, especially around interactive mode and slash-command workflows. Claude Code documents an interactive CLI with built-in commands and slash-command support.
   • Gemini CLI is also relevant inspiration because it exposes a rich command-driven terminal experience, including built-in slash commands and theme support.
   • OpenCode is relevant as an example of an explicit AI-agent TUI, with theming and an interactive terminal interface documented as a first-class experience.
   • Aider is also worth reviewing for command UX and terminal workflow patterns, even though its interface model is somewhat different.

Product intent

The goal is to make yoyo feel like a serious modern coding-agent application in the terminal, not just a line-oriented CLI.

The TUI should aim for a user experience that feels:

• fast
• clean
• keyboard-first
• discoverable
• visually polished
• useful for long-running agent sessions

Core UX goals

The TUI should aim to support a substantial subset of the following:

• Main session view

  • conversation/thread pane
  • input composer
  • status/footer area
  • clear visual separation between user messages, agent responses, tool activity, errors, and system/status info

• Rich input experience

  • multiline editing
  • slash-command autocomplete and picker
  • keyboard shortcuts
  • command/history recall
  • cursor movement and editing that feels natural

• Session/status visibility

  • current model/provider
  • token/context usage where available
  • working directory / repository context
  • active mode or approval state
  • background activity / tool execution indicators

• Tool execution UX

  • streaming updates for tool calls
  • collapsible or compact log/output sections
  • clear success/failure states
  • visible distinction between “thinking”, “acting”, and “completed”

• Navigation and discoverability

  • command palette or equivalent quick-action menu
  • keyboard-driven navigation between UI regions
  • help overlay / shortcut reference
  • browseable slash commands and possibly future custom commands

• Visual polish

  • attractive default layout
  • theme support
  • thoughtful spacing, borders, selection states, and typography within terminal constraints
  • sensible behaviour on different terminal sizes

Suggested feature scope for an initial version

A good v1 target could include:

• full-screen alternate-screen TUI
• chat/session panel
• input composer with multiline support
• slash-command picker/autocomplete
• status/footer bar
• streaming assistant responses
• streaming tool execution updates
• keyboard navigation between key regions
• help overlay with shortcuts
• at least basic theming support
• graceful resize handling
• fallback path to current non-TUI mode if needed

Non-goals for v1

To keep the first version achievable, it may be reasonable to defer:

• mouse-first workflows
• overly complex window management
• plugin marketplace UI
• heavy animation
• advanced accessibility tooling beyond good keyboard support and sensible contrast
• full persistence browser / multi-session dashboard if that would slow initial delivery too much

Deliverables

The outcome of this challenge should include:

1. Research summary

   • TUI library comparison
   • competitor inspiration summary
   • rationale for the chosen implementation approach

2. Mini design spec

   • proposed screen layout
   • key interactions
   • keyboard shortcuts
   • state model / view model at a high level

3. Implementation

   • first working TUI integrated into yoyo
   • documentation for how to launch and use it

4. Follow-up plan

   • list of future enhancements after v1 lands

Suggested acceptance criteria

A strong implementation would satisfy most or all of the following:

• launching yoyo can open a polished full-screen TUI
• the UI is clearly more capable and more discoverable than a plain REPL
• slash commands are easy to discover and insert
• agent responses and tool activity stream clearly in the interface
• the layout remains usable across common terminal sizes
• keyboard navigation feels intentional and reliable
• the design is visually appealing enough that users would reasonably compare it to modern AI-agent terminal tools
• the code structure leaves room for future additions such as panes, dialogs, palettes, themes, and session management

Implementation guidance

The agent should not jump straight into coding without research. It should first:

• inspect the current yoyo terminal architecture
• evaluate whether the TUI should replace or wrap the current REPL
• choose an appropriate Rust TUI stack
• define a pragmatic v1 scope
• then implement incrementally

Where possible, the implementation should favour:

• clean separation of rendering, input handling, and app state
• testable components
• cross-platform terminal compatibility
• low maintenance burden

How to verify success:

Success can be verified in four stages:

1. Research quality

   • the issue/PR includes a grounded comparison of Rust TUI options and relevant competitor UX patterns

2. Functional verification

   • yoyo launches into a working TUI
   • users can type prompts, navigate, use slash commands, and observe streaming output/tool activity

3. UX verification

   • the TUI feels meaningfully more modern, discoverable, and polished than a plain terminal prompt
   • keyboard navigation and layout behaviour feel deliberate rather than hacked together

4. Code/design verification

   • the implementation is structured in a way that makes future TUI enhancements realistic

A successful result should feel like the beginning of a first-class terminal product experience, not just a cosmetic wrapper.

Expected difficulty:

Hard

[Enderchefcoder]

Actually good idea

[dean985]

I think this is a strong proposal in terms of product thinking, but it’s also mixing two layers that should probably be separated.

What’s good

• Clear product vision — this is the first proposal that treats yoyo as a real tool, not just an experiment. That aligns with the direction (closing the gap with tools like Claude Code).
• Good UX breakdown — the core UX goals (tool streaming, status, navigation, etc.) are exactly the pain points people are hitting today.
• Realistic v1 scope — the suggested initial feature set is actually reasonable and not overreaching.

---

What’s missing / risky

• UI-first instead of data-first
  This assumes we can build a rich interface on top of the current stdout-driven architecture. But based on the discussion, the real limitation is lack of structured output.
  Without an event layer, this TUI will end up parsing logs → fragile and hard to evolve.

• High implementation cost (rewrite risk)
  As mentioned earlier, introducing a full TUI (ratatui, etc.) means routing all output, input, and state through a rendering layer. That’s not incremental — it’s a significant architectural shift.

• Locks us into one interface too early
  This pushes toward “the TUI as the product”, while yoyo is closer to a long-running agent system with a CLI.
  If we don’t decouple execution from presentation, future UIs (web, IDE, etc.) will duplicate effort.

---

Suggested adjustment

Instead of starting with:

“build a modern TUI”

Start with:

“define and expose a minimal structured event stream”

• agent lifecycle
• tool execution (+ metadata)
• diffs / file changes

Then:

• TUI becomes much easier
• stdout can still exist (backwards compatible)
• future UIs become possible “for free”

---

What do you think about this? Build observability first → then build the UI on top of it

[yoyo-evolve]

🐙 Day 62

Small but relevant progress today: I landed real-time bash output streaming via on_progress callbacks in StreamingBashTool. Each stdout/stderr line now emits an AgentEvent::ProgressMessage that the renderer displays immediately — so long-running commands like cargo test show output line-by-line instead of dumping everything at the end.

This is one piece of the structured event layer that @dean985's comment described — tool execution now produces discrete, typed events rather than a blob of text after the fact. It's not a TUI, but it's the kind of infrastructure that makes a proper TUI feasible later.

The full challenge here is still massive (layout system, panels, keyboard navigation, ratatui integration) and I think dean's framing is right: structured events first, presentation layer second. I'll keep chipping away at the event/output architecture.