Interactive mode

Use the Codex TUI for real-time AI assistance

Interactive mode provides a rich terminal user interface (TUI) for working with Codex. Launch it by running codex with or without an initial prompt.

Starting interactive mode

Start with prompt

codex "add unit tests for the auth module"

TUI overview

The interactive interface consists of several key areas:

Main conversation view

The primary area displays:

• User messages - Your prompts and inputs
• Agent messages - Responses from Codex
• Command execution - Shell commands with live output
• File changes - Diffs and modifications
• Reasoning - Internal agent reasoning (when available)

Content streams in real-time as the agent works, providing immediate feedback.

Status bar

The bottom status bar shows:

• Current model and provider
• Sandbox mode and approval policy
• Working directory
• Network status
• Token usage for the current turn

Input composer

The input area at the bottom allows you to:

• Type multi-line messages (Shift+Enter for newlines)
• Attach images with --image or drag-and-drop
• Invoke skills with $skill-name
• Reference apps with $app-name

Keyboard shortcuts

Navigation

Shortcut	Action
Ctrl+C	Cancel current operation or exit
Ctrl+D	Exit Codex (when input is empty)
Ctrl+L	Clear screen
↑ / ↓	Navigate command history
PgUp / PgDn	Scroll conversation
Home / End	Jump to start/end of input

Input control

Shortcut	Action
Enter	Send message
Shift+Enter	Insert newline
Ctrl+U	Clear current line
Ctrl+W	Delete word backward
Tab	Autocomplete (when available)

Advanced

Shortcut	Action
Ctrl+R	Resume previous session
Ctrl+P	Open command palette (if enabled)
Esc	Cancel current input

Keyboard shortcuts may vary slightly by terminal emulator and operating system.

Features

Live streaming output

Commands and agent messages stream in real-time. You’ll see:

• Text appearing character-by-character
• Command output as it’s generated
• Diffs as files are modified
• Progress indicators for long operations

Approval prompts

When the agent needs to perform sensitive operations, you’ll see an inline approval prompt:

┌─ Command Approval Required ────────────────────────────────┐
│ codex wants to run:                                        │
│   npm install express                                      │
│                                                            │
│ Working directory: /Users/me/project                       │
│                                                            │
│ [a] Accept once                                            │
│ [s] Accept for session                                     │
│ [p] Accept and add to policy                               │
│ [d] Decline                                                │
│ [c] Cancel turn                                            │
└────────────────────────────────────────────────────────────┘

1. Review the command

   Carefully read what the agent wants to execute

2. Choose approval level

   Select how broadly to approve the operation

3. Monitor execution

   Watch the command output stream in real-time

Command history

Use the up/down arrow keys to cycle through:

• Previous prompts in this session
• Previously executed commands
• Resumed conversation inputs

History persists across sessions.

Session management

Interactive mode automatically:

• Saves your conversation to disk
• Maintains context across turns
• Allows resuming from where you left off

Threads are stored in ~/.codex/sessions/ as JSONL files.

Display options

Alternate screen mode

By default, Codex uses the alternate screen buffer (like vim or less). This:

• Preserves your terminal scrollback
• Cleans up when you exit
• Works well in most terminals

To disable alternate screen mode:

codex --no-alt-screen

This is useful for terminal multiplexers like Zellij that strictly follow xterm specs.

Color output

The TUI automatically detects your terminal’s color support and adapts:

• 24-bit true color (recommended)
• 256 colors
• 16 colors (fallback)

Colors are used to highlight:

• Syntax in code blocks
• Diff additions (green) and deletions (red)
• Status indicators
• Error messages

Working with images

Attach images to your prompts for visual context:

Command line

codex --image screenshot.png "what's wrong with this UI?"

Supported formats:

• PNG, JPEG, GIF, WebP
• Local file paths
• Data URLs (via app-server)

Advanced usage

Resume sessions

Return to a previous conversation:

Resume last session

codex resume --last

Fork conversations

Create a new branch from an existing thread:

codex fork thr_abc123

This copies the conversation history into a new thread, allowing you to explore alternative approaches.

Custom working directory

Change the agent’s working directory:

codex --cd /path/to/project

All file operations and commands will execute relative to this directory.

Configuration profiles

Use predefined configuration profiles:

codex --profile production

Profiles are defined in ~/.codex/config.toml.

Troubleshooting

Screen rendering issues

If you see garbled output or rendering glitches:

1. Try disabling alternate screen mode:

   codex --no-alt-screen
   

2. Check your TERM environment variable:

   echo $TERM  # Should be xterm-256color or similar
   

3. Update your terminal emulator to the latest version

Input not working

If keyboard input seems unresponsive:

• Ensure your terminal supports the required features
• Check that no other process is capturing input
• Try restarting your terminal emulator

Performance issues

If the TUI feels sluggish:

• Large conversation histories can slow rendering
• Consider starting a new thread for unrelated tasks
• Archive old threads to keep your session list manageable

The TUI requires a minimum terminal size of 80x24 characters. Smaller terminals may not render correctly.

Next steps

Non-interactive mode

Learn about headless execution

Approvals

Configure approval policies