Codex TUI Parsing

Relevant source files

The following files were used as context for generating this wiki page:

• crates/core/src/codex_tui.rs
• crates/gtk-app/src/session_surface.rs
• crates/core/src/mcp.rs
• crates/cli/src/main.rs
• progress.md

Codex TUI Parsing is a critical system within the Linux Archductor project designed to bridge the gap between raw pseudo-terminal (PTY) output and a structured, app-native user interface. Coding agents like Codex often communicate through text-based user interfaces (TUIs) that include ANSI escape sequences, boxed layouts, and status spinners. The parsing logic extracts specific events—such as tool calls, skill activations, and file changes—while filtering out transient terminal "noise" like MCP server boot messages or loading indicators.

The parser enables the GTK application to render transcript items as rich UI components (e.g., expandable chips for file changes or dedicated bubbles for user messages) rather than a simple scrolling log. It also implements a delta-based update system that tracks screen fingerprints to minimize UI repaints during active agent generation.

Sources: crates/core/src/codex_tui.rs:4-90, crates/gtk-app/src/session_surface.rs:1360-1385, progress.md

Core Data Structures

The parsing logic centers around several key enums and structs that categorize terminal data into semantic objects.

Codex Inline Events

These represent specific actions performed by the agent that appear within the flow of a message or as independent status lines.

Event Type	Description
Tool	Represents a specific function or tool call (e.g., functions.exec_command).
Skill	Announcements of specific "superpower" skills being utilized (e.g., graphify).
FileReference	Direct links to specific files, including line and column numbers.
FileChange	Structured representation of file additions, edits, or deletions including diff lines.

Sources: crates/core/src/codex_tui.rs:4-10, crates/core/src/codex_tui.rs:31-38

Transcript Items

The final output of the parsing process is a sequence of CodexParsedItem objects.

Parsing Architecture and Logic

The parsing process involves multiple stages: normalization, line categorization, and span/block collection.

Line-by-Line Categorization

The function parse_codex_structured_lines iterates through terminal text, attempting to match lines against known patterns for context usage (token counts), inline events, or standard messages.

1. Normalization: Carriage returns (\r\n, \r) are replaced with standard newlines.
2. Context Window Matching: Lines like Context window: 42% or 128k / 200k tokens are converted into CodexContextUsage structs.
3. Marker Detection: The parser looks for markers such as Ran , Read , or Edited to identify the start of tool and file events.

Sources: crates/core/src/codex_tui.rs:155-175, crates/core/src/codex_tui.rs:647-658

Screen Message Spans

Boxed layouts in the terminal (using characters like ╭, │, ╰) are identified by parse_codex_screen_message_spans. This logic determines the role of the speaker (User vs. Agent) by inspecting the box header content (e.g., "You" or "Codex").

State and Readiness Detection

A critical feature for the interactive UI is detecting when the Codex agent is ready for new user input. The terminal output contains transient noise that must be ignored to prevent premature interaction.

Ignorable Noise

The parser explicitly ignores:

• MCP Server Booting: Strings like Booting MCP server or Starting MCP servers.
• Status Indicators: Spinner states like Working (...) or Thinking (...).
• Model Loading: Phrases such as model: loading.

Prompt Detection

The screen is considered "ready for input" only if:

1. The cursor prompt (›) is visible.
2. The live footer (showing model and directory) is fully loaded.
3. No active "Working" or "Thinking" bullets are found in the final 8 lines of the screen.

Sources: crates/core/src/codex_tui.rs:160-185, crates/core/src/codex_tui.rs:1255-1275, crates/core/src/mcp.rs:20-40

GTK Integration

In the GTK application, session_surface.rs consumes these parsed structures to build the visual transcript.

Event Rendering

Parsed events are rendered as custom widgets rather than text blocks. For example, a FileChange event is converted into an expandable chip labeled with + or - and the filename. Clicking the chip reveals the full captured diff.

Context Usage Display

The GTK UI includes a context_usage_widget that displays token consumption percentages. The widget applies CSS classes based on the threshold:

• Normal (0-69%): Default styling.
• Warning (70-89%): Yellow/Orange highlights.
• Danger (90%+): Red highlights.

Sources: crates/gtk-app/src/session_surface.rs:1680-1700

Summary of TUI Markers

The parser identifies various markers to determine event boundaries and types.

Marker Prefix	Resulting Action
Ran	Identifies a Tool call execution.
Read	Identifies a file read or a Skill read (if SKILL.md is mentioned).
• Edited	Starts a FileChange block with line-level diff parsing.
╭─ You	Identifies a message span for the User role.
╭─ Codex	Identifies a message span for the Agent role.
›	Marks the interactive user prompt.

Sources: crates/core/src/codex_tui.rs:620-640, crates/core/src/codex_tui.rs:810-825, crates/gtk-app/src/session_surface.rs:1945-1965

Summary

Codex TUI Parsing transforms the semi-structured, character-cell output of the Codex agent into a state-aware, rich UI. By handling complex terminal scenarios such as scrolled agent tails, overlapping message boxes, and transient status indicators, the parser ensures that developers can review agent actions (tools, skills, and diffs) with high precision and minimal visual distraction. Its integration with the Archcar bridge and GTK surfaces makes it the primary interface layer for managing parallel coding agent sessions.

Sources: crates/core/src/codex_tui.rs, crates/gtk-app/src/session_surface.rs