TUI Architecture

Terminal user interface implementation using Ratatui

The Codex TUI is a fullscreen terminal interface built with Ratatui, providing an interactive experience for conversing with AI agents.

Overview

The codex-tui crate implements the default interactive mode for Codex CLI, launched when you run codex without subcommands.

Technology Stack

• Ratatui 0.29.0 — Terminal UI framework
• Crossterm — Cross-platform terminal manipulation
• Custom patches — Forked ratatui and crossterm for color query support

Architecture Components

App State Management

The TUI follows a centralized state model:

Rendering Pipeline

1. Event Collection

   Crossterm captures keyboard input, terminal resize, and other events.

2. State Update

   Events are processed and update the app state, potentially triggering codex-core operations.

3. Widget Construction

   Ratatui widgets are built from the current state.

4. Frame Rendering

   The terminal frame is rendered with the new widget tree.

Style System

The TUI follows strict style conventions defined in codex-rs/tui/styles.md:

Color Palette

Headers

// Headers use bold
"Header".bold()

// Default foreground color (no style)
"Primary text".into()

// Use dim for secondary text
"Secondary text".dim()

Semantic Colors

Colors are used semantically, not decoratively:

Cyan

User input, selection, status indicators

"User input".cyan()

Green

Success messages and additions

"+ Added".green()

Red

Errors, failures, deletions

"- Deleted".red()

Magenta

Codex agent identity

"Codex".magenta()

Avoid:

• Custom colors (no guarantee of contrast)
• ANSI black/white as foreground
• ANSI blue/yellow (not in style guide)
• Hardcoded .white() calls

Styling Conventions

The TUI uses Ratatui’s Stylize trait for concise styling:

Basic Patterns

Plain Text

// Simple spans
"text".into()

// Chain style helpers
"text".red().bold()
"url".cyan().underlined()

// Prefer vec![...].into() for obvious types
let line: Line = vec![
    "  └ ".into(),
    "M".red(),
    " ".dim(),
    "tui/src/app.rs".dim()
].into();

Style Helper Priority

1. Prefer Stylize helpers

   Use .dim(), .bold(), .cyan(), .italic(), .underlined() instead of manual Style construction.

2. Simple conversions

   Use "text".into() for spans and vec![...].into() for lines when type is obvious.

3. Explicit types when needed

   Use Line::from(spans) or Span::from(text) when inference is ambiguous.

4. Runtime styles OK

   For computed styles, Span::styled(text, style) is acceptable.

Compactness Guidelines

From AGENTS.md TUI styling rules:

Compactness: prefer one-line forms

• Prefer the form that stays on one line after rustfmt
• If only one of Line::from(vec![...]) or vec![...].into() avoids wrapping, choose that
• If both wrap, pick the one with fewer wrapped lines
• Don’t refactor between equivalent forms without readability gain

Text Wrapping

The TUI uses dedicated wrapping utilities:

Plain Strings

// Use textwrap::wrap for plain text
use textwrap::wrap;
let lines = wrap(text, width);

// Use helpers from tui/src/wrapping.rs
use codex_tui::wrapping::{word_wrap_lines, word_wrap_line};

let wrapped = word_wrap_line(&line, width);

// Use RtOptions for indent control
use codex_tui::wrapping::RtOptions;

let options = RtOptions {
    width: 80,
    initial_indent: "  ",
    subsequent_indent: "    ",
    ..Default::default()
};

Prefix helpers

For prefixing lines (e.g., bullet points), use prefix_lines from line_utils:

use codex_tui::line_utils::prefix_lines;

let prefixed = prefix_lines(
    lines,
    "- ",      // first line prefix
    "  ",      // subsequent lines prefix
);

Key Components

Conversation View

The main conversation rendering:

• Turn items — User messages, agent messages, reasoning
• Tool execution — Command output, file changes, MCP calls
• Approvals — Interactive prompts for commands/file changes
• Streaming — Real-time delta updates

Bottom Pane

Input and status area:

• Input field — Multi-line text input
• Status indicators — Model, sandbox mode, approval policy
• Shortcuts — Quick action hints

See codex-rs/tui/src/bottom_pane/AGENTS.md for implementation details.

Diff Visualization

Syntax-highlighted diffs for file changes:

• syntect integration for syntax highlighting
• similar crate for diff generation
• Inline diff rendering with line numbers
• Collapse/expand for large changes

Testing Strategy

The TUI uses snapshot testing via insta:

Snapshot Tests

Requirement: Any UI change must include corresponding snapshot coverage.

1. Run tests to generate snapshots

   cargo test -p codex-tui
   
2. Check pending snapshots

   cargo insta pending-snapshots -p codex-tui
   
3. Review snapshot diffs

   Review .snap.new files directly or:

   cargo insta show -p codex-tui path/to/file.snap.new
   
4. Accept snapshots

   Only if all changes are intentional:

   cargo insta accept -p codex-tui
   

Why Snapshot Tests?

• Visual regression detection — Catch unintended UI changes
• Review-friendly — Diffs show exactly what changed visually
• Fast feedback — No need for manual UI testing
• Future-proof — Changes are explicit and reviewable

Development Workflow

From AGENTS.md TUI development guidelines:

1. Make code changes

   Implement your TUI feature or fix.

2. Run tests

   cargo test -p codex-tui
   
3. Format code

   just fmt
   

   No approval needed — always run after changes.

4. Fix lints (optional)

   For large changes:

   just fix -p codex-tui
   

Do not re-run tests after fix or fmt unless you made code changes.

Performance Considerations

Efficient Rendering

• Frame diffing — Ratatui only updates changed cells
• Lazy evaluation — Widgets built on demand
• Scroll virtualization — Only render visible content
• Delta streaming — Incremental updates from codex-core

Memory Management

• Bounded buffers — Limit conversation history in memory
• On-demand loading — Load full history from disk when needed
• String interning — Reuse common strings (status indicators, etc.)

Accessibility

Keyboard Navigation

All TUI functionality is keyboard-accessible:

• Arrow keys — Navigation
• Tab/Shift+Tab — Focus cycling
• Enter — Submit/confirm
• Esc — Cancel/back
• Ctrl+C — Interrupt/exit

Screen Reader Support

Terminal content is naturally screen-reader friendly:

• Plain text rendering
• Semantic color usage
• Clear status indicators
• No mouse-only interactions

Platform-Specific Behavior

Windows Terminal (WSL 2)

When WT_SESSION is set:

• Fall back to native Windows toast notifications
• OSC 9 sequences not implemented in Windows Terminal
• Approval prompts surface even when terminal is backgrounded

macOS Notifications

Supports custom notification scripts via config:

[notify]
script = "/path/to/notification-script.sh"

Example using terminal-notifier in docs.

Customization

The TUI respects terminal color schemes:

• Uses ANSI colors (adapt to theme)
• No hardcoded RGB values
• Respects terminal background
• Works with light and dark themes

Custom colors are avoided to ensure compatibility across terminal themes.

Next Steps

Rust Crates

Explore the full workspace structure

Sandboxing

Platform-specific security isolation