# UI Module (src/tunacode/ui)

> src/tunacode/ui/ - User interface layer for the TunaCode TUI application.

- Skill: `tools-only/ui-module-src-tunacode-ui` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/ui-module-src-tunacode-ui`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/ui-module-src-tunacode-ui/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/ui-module-src-tunacode-ui

---


# UI Module (`src/tunacode/ui`)

## Where
`src/tunacode/ui/` - User interface layer for the TunaCode TUI application.

## What
Implements the complete **Textual-based Terminal User Interface** for TunaCode, featuring:
- **TUI Application**: Main app loop and lifecycle management (`app.py`)
- **REPL Interface**: Read-eval-print loop for agent interaction (`main.py`)
- **Screens**: Modal dialogs and full-screen views (setup, model picker, etc.)
- **Widgets**: Custom Textual widgets for specialized rendering
- **Renderers**: Tool output formatting and display logic
- **Headless Mode**: Non-interactive execution path
- **Styling**: NeXTSTEP-inspired theme and CSS definitions

## Directory Structure
```
ui/
├── app.py                  # Main Textual application class
├── main.py                 # Entry point and REPL orchestration
├── logo_assets.py          # Pre-rendered ANSI logo loader
├── shell_runner.py         # TUI shell execution wrapper
├── repl_support.py         # REPL utilities and helpers
├── styles.py               # Style definitions and constants
├── commands/               # UI command handlers
│   └── (slash commands, REPL commands)
├── components/             # Reusable UI components
├── screens/                # Full-screen modal dialogs
│   ├── setup_screen.py
│   ├── model_picker.py
│   └── (other screens)
├── widgets/                # Custom Textual widgets
│   └── (specialized widgets)
├── renderers/              # Output formatting by tool type
│   └── tools/              # Tool-specific renderers
├── headless/               # Non-interactive execution
├── assets/                 # UI assets (pre-rendered ANSI art)
└── styles/                 # CSS and theme files
```

## How
The UI module follows a **layered component architecture**:

### Application Layer
- **`app.py`**: `TunaCodeApp` extends `textual.App`
  - Manages application lifecycle (startup, shutdown, screen switching)
  - Handles global state and event routing
  - Integrates with core agent system

### Presentation Layer
- **`screens/`**: Full-screen views for focused interactions
  - Setup wizard screens
  - Model picker with search/filter
  - Configuration dialogs
  - Session management views

### Component Layer
- **`widgets/`**: Reusable Textual widgets
  - Custom input widgets with validation
  - Specialized display widgets
  - Interactive controls

- **`components/`**: Composite UI patterns
  - Reusable widget combinations
  - Layout patterns
  - Interaction handlers

### Rendering Layer
- **`renderers/`**: Tool output formatting
  - `tools/` subdirectory contains renderer per tool type
  - Converts raw tool output to Rich/textual markup
  - Handles truncation, pagination, syntax highlighting

### Interaction Layer
- **`commands/`**: User command handlers
  - Slash command implementations
  - REPL command routing
  - Input parsing and validation

### Styling Layer
- **`styles.py`**: Programmatic style definitions
- **`styles/`**: CSS files for Textual styling
  - NeXTSTEP-inspired bevel and shadow effects
  - Color scheme definitions
  - Responsive layout rules

### Headless Layer
- **`headless/`**: Non-interactive execution path
  - Bypasses Textual app for CI/CD or scripting
  - Streams output to stdout/stderr
  - Simplified rendering for logs

## Why
**Separation of Concerns**: The UI module isolates all presentation logic from business logic:
- **Core Independence**: `tunacode.core` has no UI dependencies
- **Testability**: UI components can be tested in isolation
- **Flexibility**: Multiple frontends (TUI, headless, future GUI) can coexist
- **Theme Consistency**: Centralized styling ensures uniform appearance

**NeXTSTEP Design Philosophy**:
- **Uniformity**: Consistent interaction patterns across all screens
- **User Informed**: Real-time feedback for all agent actions
- **Clarity**: Clean, professional, retro-modern aesthetic
- **Object-Oriented**: Component-based architecture mirroring NeXTSTEP's design

**Design Principles**:
1. **Component Reusability**: Widgets and components are composable
2. **Lazy Loading**: Heavy UI components loaded on-demand
3. **Event-Driven**: Textual's event system for responsive updates
4. **Graceful Degradation**: Headless mode for environments without TTY

## Integration Points
- **Core Agent System**: `tunacode.core.agents` provides agent responses to display
- **Tool Execution**: `tunacode.tools` outputs are rendered by `renderers/tools/`
- **Configuration**: `tunacode.configuration` provides settings for UI initialization
- **Constants**: `tunacode.constants` provides UI_COLORS and theme definitions

## Code Quality Notes
- **Type Hints**: Full Textual type annotation for widget properties
- **CSS Organization**: Separate `.tcss` files for maintainable styling
- **Widget Testing**: Components designed for isolated unit testing
- **Performance**: Virtual scrolling for large outputs, lazy screen loading