This document covers the status line and footer rendering systems in the TUI. The status line is an optional, configurable single-line footer that displays runtime information like the current model, approval policy, git branch, and session ID. The footer encompasses the broader bottom-pane UI elements including mode indicators, context window usage, shortcut hints, and the status line itself when enabled.
For information about the chat composer and input handling within the bottom pane, see Chat Composer and Input System. For details on the overall bottom pane architecture, see BottomPane and Input System.
The status line is a user-configurable footer row that displays runtime metadata about the current session. Users can customize which items appear and their display order via the /statusline command.
Status line behavior is controlled by config.status_line settings:
Supported Item Identifiers (defined in StatusLineItem enum):
| Item ID | Display Content | Data Source |
|---|---|---|
model | Current model name | ChatWidget::current_model() |
approval | Approval policy (Ask/Never/Any) | config.permissions.approval_policy |
sandbox | Sandbox mode (ReadOnly/WorkspaceWrite/FullAccess) | config.permissions.sandbox_policy |
collaboration | Collaboration mode indicator | Active collaboration mask + base mode |
session-id | Thread ID (short form) | thread_id.to_short_string() |
directory | Current working directory | config.cwd with home directory substitution |
branch | Git branch name | Async lookup, cached per CWD |
personality | Active personality | config.settings.personality |
Sources: codex-rs/tui/src/bottom_pane/status_line_setup.rs1-200
The status line is recomputed on-demand when runtime state changes. The refresh process validates configured items, schedules async data fetching when needed, and omits items whose data is not yet available.
Status Line Refresh Flow
Sources: codex-rs/tui/src/chatwidget.rs877-1027
Each status line item is rendered as a Span with specific styling and separator logic. Items are joined with a dim " · " separator and the entire line is right-aligned within the footer area.
Item Rendering Logic:
Parse configured items: status_line_items_with_invalids() splits the comma-separated config.status_line.items string and validates each identifier against the StatusLineItem enum.
Warn on invalid items: Invalid identifiers are collected and a warning is emitted once per session via the status_line_invalid_items_warned atomic latch.
Render available items: For each valid item, attempt to fetch its value from runtime state. If the value is unavailable (e.g., thread ID before session is configured, or branch before async lookup completes), skip the item without rendering a placeholder.
Async branch lookup: When the branch item is configured but data is not cached for the current CWD, spawn_branch_lookup_task() runs git rev-parse --abbrev-ref HEAD in a background task and emits AppEvent::StatusLineBranchUpdated with the result. The lookup is skipped while another is already in flight to avoid redundant spawns.
Sources: codex-rs/tui/src/chatwidget.rs892-1027 codex-rs/tui/src/chatwidget.rs4122-4181
Branch name fetching is asynchronous to avoid blocking the UI on filesystem I/O:
Git Branch Async Lookup Flow
Sources: codex-rs/tui/src/chatwidget.rs4122-4181 codex-rs/tui/src/app.rs1730-1754
Branch Cache Invalidation:
The cached branch and its associated CWD are stored in ChatWidget fields:
status_line_branch: Option<String> - cached branch name or None if unknownstatus_line_branch_cwd: Option<PathBuf> - CWD used for the cached branchstatus_line_branch_pending: bool - true while async lookup is in flightstatus_line_branch_lookup_complete: bool - true after first lookup attemptWhen the CWD changes, the cache is reset and a new lookup is scheduled on the next refresh.
If the git command fails (e.g., not in a git repo), the cache stores None and no branch item is rendered.
Sources: codex-rs/tui/src/chatwidget.rs613-623
The footer encompasses multiple rendering layers within the bottom pane. It includes the status line (when enabled), context window indicators, mode indicators (collaboration, personality), and dynamic shortcut hints.
Bottom Pane and Footer Component Hierarchy
Sources: codex-rs/tui/src/bottom_pane/mod.rs142-222 codex-rs/tui/src/bottom_pane/chat_composer.rs287-339
The footer row is rendered at the bottom of the composer block and adapts its layout based on available width. The rendering logic is centralized in codex-rs/tui/src/bottom_pane/footer.rs.
Layout Modes:
Single-line layout: When width permits, all elements are rendered on one line:
[Mode] [Context Window] [Status Line] [Hints]
Two-line layout: When the single-line content exceeds available width, the mode indicator and context window move to a separate top line:
[Mode] [Context Window]
[Status Line] [Hints]
Hint-only fallback: When even the two-line layout cannot fit the status line, only shortcut hints are rendered on a single line.
Sources: codex-rs/tui/src/bottom_pane/footer.rs1-800
Collaboration Mode Indicator:
When collaboration modes are enabled and a non-default mode is active, a colored mode indicator appears at the left of the footer:
[ Plan ] - Plan mode (yellow)[ Code ] - Code mode (green)[ Agent ] - Agent mode (cyan)The indicator only appears when a collaboration mask is applied; the default mode does not render an indicator.
Sources: codex-rs/tui/src/bottom_pane/footer.rs400-450
Personality Indicator:
When a non-default personality is configured, a gray italic label appears after the collaboration mode indicator:
concise - Concise personalitycreative - Creative personalitytechnical - Technical personalityThe balanced (default) personality does not render an indicator.
Sources: codex-rs/tui/src/bottom_pane/footer.rs200-250
When context_window_percent and context_window_used_tokens are set by ChatWidget, the footer renders a compact context usage summary:
85% • 34k tokens
The percentage and token count are styled in dim gray and positioned after the mode indicators. This element is omitted when context data is unavailable.
Sources: codex-rs/tui/src/bottom_pane/footer.rs500-550
Shortcut hints appear at the right edge of the footer and adapt based on the current input state. The hints are rendered in a compact format with key bindings styled in cyan and descriptions in dim gray.
Dynamic Hint Modes:
| State | Hints Displayed |
|---|---|
| Empty composer | Enter submit, ? shortcuts |
| Non-empty draft | Enter submit, Shift+Enter newline, Tab queue (when steer enabled) |
| Task running | Esc interrupt, Ctrl+C quit |
| Popup active | Popup-specific hints (e.g., Enter select, Esc dismiss) |
| Backtrack hint enabled | Esc backtrack |
| Quit shortcut armed | Ctrl+C again to quit (with timeout) |
The hint mode is computed by esc_hint_mode() based on the composer state, task running flag, and quit shortcut expiration time. The footer_mode field in ChatComposer caches the current mode to avoid redundant recomputation.
Sources: codex-rs/tui/src/bottom_pane/footer.rs600-800
The footer can display transient flash messages that temporarily replace the normal footer content. Flash messages are stored in the footer_flash field as a FooterFlash struct with an expires_at timestamp.
Flash messages are used for:
The flash expires after its timeout and the normal footer rendering resumes. The BottomPane schedules a redraw at the expiration time via frame_requester.request_frame_at(expires_at).
Sources: codex-rs/tui/src/bottom_pane/chat_composer.rs342-345 codex-rs/tui/src/bottom_pane/footer.rs100-150
The /statusline command opens an interactive reordering UI that allows users to customize which items appear and their display order. This UI is implemented as a StatusLineSetupView in the bottom pane view stack.
Status Line Setup UI Flow
Sources: codex-rs/tui/src/bottom_pane/status_line_setup.rs1-400 codex-rs/tui/src/app.rs1800-1850
The setup view renders a scrollable list of all available status line items with checkboxes indicating their enabled state:
┌─ Configure Status Line ─────────────────┐
│ [ ] model │
│ [x] approval │
│ [x] sandbox │
│ [ ] collaboration │
│ [x] session-id │
│ [x] directory │
│ [ ] branch │
│ ... │
└──────────────────────────────────────────┘
Space: toggle ↑/↓: move Shift+↑/↓: reorder
Ctrl+S: save Esc: cancel
The view maintains:
items: Vec<(StatusLineItem, bool)> - all items with enabled flagscursor: usize - current selection positionscroll_state: ScrollState - viewport scrollingReordering moves the selected item up or down in the items vec, and the final ordering is serialized as a comma-separated string when saving.
Sources: codex-rs/tui/src/bottom_pane/status_line_setup.rs50-200
The status line and footer systems are tightly integrated with ChatWidget to reflect real-time session state. Key integration points:
Status Line Refresh Triggers:
EventMsg::SessionConfigured is received, the thread ID becomes available and the status line is refreshed./model or API, the status line is refreshed./approvals or /permissions, the status line is refreshed.Footer Update Triggers:
TokenUsageInfo is received, the context window percentage and token count are updated.Sources: codex-rs/tui/src/chatwidget.rs877-1027 codex-rs/tui/src/chatwidget.rs2300-2400
The following ChatWidget fields are used by status line and footer rendering:
| Field | Purpose |
|---|---|
status_line_invalid_items_warned | Atomic latch to warn once about invalid item IDs |
status_line_branch | Cached git branch name |
status_line_branch_cwd | CWD for cached branch |
status_line_branch_pending | True while async branch lookup is in flight |
status_line_branch_lookup_complete | True after first lookup attempt |
context_window_percent | Token usage percentage for footer display |
context_window_used_tokens | Absolute token count for footer display |
collaboration_mode_indicator | Current collaboration mode for footer display |
These fields are updated by event handlers and accessed by the rendering logic in BottomPane and ChatComposer.
Sources: codex-rs/tui/src/chatwidget.rs613-623
The complete status line and footer rendering pipeline involves multiple layers:
Complete Footer Rendering Pipeline
Sources: codex-rs/tui/src/app.rs600-800 codex-rs/tui/src/chatwidget.rs3500-3600 codex-rs/tui/src/bottom_pane/mod.rs500-700 codex-rs/tui/src/bottom_pane/chat_composer.rs2000-2200 codex-rs/tui/src/bottom_pane/footer.rs1-800
The status line and footer rendering systems provide a flexible, real-time display of session metadata and input affordances:
Status Line: A user-configurable footer row that displays runtime information from multiple data sources (config, session state, async git lookups). Items can be customized via the /statusline command and are rendered only when their data is available.
Footer: A multi-component layout that includes mode indicators, context window usage, status line items, and dynamic shortcut hints. The layout adapts to available width and switches between single-line and two-line modes.
Integration: Both systems are tightly coupled to ChatWidget and BottomPane state, with refresh triggered by session events, config changes, and user actions. Async data fetching (git branch) avoids blocking the UI while still providing up-to-date information.
Extensibility: New status line items can be added by extending the StatusLineItem enum and implementing the corresponding rendering logic in ChatWidget::refresh_status_line().
Sources: codex-rs/tui/src/chatwidget.rs877-1027 codex-rs/tui/src/bottom_pane/footer.rs1-800 codex-rs/tui/src/bottom_pane/chat_composer.rs2000-2300
Refresh this wiki