UI Layer

UI Layer

Package: src/tunacode/ui/

What

The Textual-based terminal user interface for TunaCode. Handles all user interaction, screen navigation, command routing, and rendering of agent responses, tool outputs, and errors. The UI layer consumes the core agent loop and provides a clean, NeXTSTEP-inspired visual experience.

Key Files

Application Entry Point

REPL Support & Callbacks

Screens (Modal Dialogs)

Widgets (Reusable Components)

Renderers (Rich Panel System)

Command System

All slash commands are implemented as Command subclasses and registered in COMMANDS. handle_command() also routes shell commands (!<cmd>), legacy exit, and slash /exit.

Command Contract

• Each command module (excluding base.py and __init__.py) defines one concrete Command subclass.
• name and description must be set and non-empty; usage is optional.
• execute must be async and accept (app, args).
• Each concrete command must be present in COMMANDS with its name as the key.

This contract is enforced in tests/unit/ui/test_command_contracts.py.

ESC Key Handling

Context Panel

Utilities

How

Application Startup Flow

tunacode (CLI)
    |
    v
main.py typer app
    |
    v
_apply_base_url_override()  (if --baseurl)
    |
    v
_run_textual_cli()
    |
    v
TextualReplApp(state_manager, show_setup)
    |
    v
on_mount()
    |-- Register themes (tunacode, nextstep, builtin)
    |-- Load saved theme from config
    |-- Initialize session metadata (project_id, working_dir, created_at)
    |
    v
if show_setup:
    push_screen(SetupScreen) → _on_setup_complete → _start_repl
else:
    _start_repl()

REPL Request Flow

User types in Editor → Enter
    |
    v
on_editor_submit_requested()
    |
    v
handle_command() checks for /command or !shell
    |
    +-- /help, /model, /theme, etc. → execute command
    |
    +-- !cmd → ShellRunner.start()
    |
    +-- Agent request → request_queue.put(message)
    |
    v
_request_worker() coroutine
    |
    v
_process_request()
    |
    v
process_request(core.agents.main)
    |-- build_textual_tool_callback()
    |-- streaming_callback (throttled UI updates)
    |-- build_tool_result_callback()
    |-- build_tool_start_callback()
    |
    v
Streaming events:
    |-- message_update → _streaming_callback → streaming_output widget
    |-- tool_execution_start → status bar "running: tool_name"
    |-- tool_execution_end → ToolResultDisplay → ChatContainer.write()
    |-- turn_end → update iteration count
    |
    v
Finalized:
    |-- _get_latest_response_text()
    |-- render_agent_response() → ChatContainer.write()
    |-- _update_resource_bar()
    |-- await save_session()

ESC Key Handling

User presses ESC
    |
    v
action_cancel_request()
    |
    v
EscHandler.handle_escape()
    |
    v
Priority 1: cancel current request task
    |
    v
Priority 2: cancel running shell command

UI Behavior on Cancel:

• Completed tool panels already rendered to the chat remain visible
• In-flight tool calls and streaming responses are stopped
• A "Cancelled" notification appears
• Loading indicator and streaming output are cleared
• Status bar updates to show the cancelled action

Rendering Pipeline

Agent/tool output → Renderer function
    |
    v
render_*(args, result, duration_ms, max_width)
    |
    v
Returns (content: RichRenderable, PanelMeta)
    |
    v
ChatContainer.write(content, panel_meta=meta)
    |
    v
CopyOnSelectStatic widget
    |-- Applies CSS classes from PanelMeta
    |-- Sets border_title/border_subtitle
    |-- Enables mouse selection copy

Panel Rendering (NeXTSTEP Style)

RichPanelRenderer.render_tool()
    |
    v
Determine PanelType (TOOL, ERROR, SEARCH, INFO, SUCCESS, WARNING)
    |
    v
Lookup styles from PANEL_STYLES (border, title, subtitle colors)
    |
    v
Build content parts:
    |-- Arguments table (if any)
    |-- Result (truncated to MAX_PANEL_LINES)
    |-- Footer (duration_ms, line count)
    |
    v
Return (Group(*content), PanelMeta(css_class, border_title, border_subtitle))

Why

The UI layer follows NeXTSTEP User Interface Guidelines (see .claude/skills/neXTSTEP-ui/): clear information hierarchy, no hidden state, consistent visual language, and respect for user attention.

Why ChatContainer with insertion anchors?

• Tool results may arrive after the agent response has already rendered.
• Insertion anchors ensure late-arriving content appears in the correct logical position.
• Without tracking, tool panels would always appear at the bottom, breaking conversation flow.

Why ESC handler as separate component?

• ESC has two distinct responsibilities (cancel request, cancel shell).
• Hardcoding logic in TextualReplApp creates tight coupling and makes testing difficult.
• Dependency injection via EscHandler.handle_escape() allows protocol-based testing.

Why throttled streaming updates?

• Textual re-rendering is expensive. Updating on every chunk causes UI lag.
• STREAM_THROTTLE_MS = 100ms batches updates while maintaining perceived responsiveness.

Why mouse selection copy integration?

• Terminal users expect text selection to copy without keyboard shortcuts.
• SelectableRichVisual injects offset metadata that Textual's selection requires but doesn't provide by default.
• CopyOnSelectStatic.selection_updated() debounces and copies on mouse release.

Why separate renderers per tool?

• Generic panels are functional but lack tool-specific formatting.
• render_bash shows exit code and working directory context.
• render_read_file applies syntax highlighting.
• render_diagnostics formats LSP errors with file positions.

Why slash command system?

• Extensible command registration via COMMANDS dict.
• Each command is an isolated Command subclass with clear name, description, usage.
• Easy to add new commands without modifying routing logic.

Why status bar 3-zone layout?

• Left: location context (branch, directory) — always relevant.
• Mid: edited files — operational state, shows what's been modified.
• Right: last/running action — immediate feedback on what just happened.