Skip to main content
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 use bold
"Header".bold()

​
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

// Simple spans
"text".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:
  • 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: 
// Use textwrap::wrap for plain text
use textwrap::wrap;
let lines = wrap(text, width);
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