codex-terminal-progress is a Codex CLI plugin that uses OSC 9;4 escape sequences to display your agent's status in the terminal tab header. Works with iTerm2, WezTerm, Ghostty, and Windows Terminal.

Inspired by opencode-terminal-progress.

✨ Features

• 👀 At-a-glance agent status — no need to switch to the Codex TUI to know what's happening
• 🔄 Real-time updates — progress changes as your agent thinks, acts, and responds
• 🛑 Error detection — turns red when a tool fails
• ⏸️ Permission awareness — shows paused state when waiting for your approval
• 🔌 Zero-config setup — single command to configure hooks
• 🪟 tmux compatible — works transparently inside tmux sessions
• 🎯 Lightweight — no dependencies, runs as a subprocess and exits immediately

📋 Supported Terminals

| Terminal | Detection | | --------------------------------------------------------- | ----------------------------------------------------------- | | iTerm2 | TERM_PROGRAM=iTerm.app, LC_TERMINAL, ITERM_SESSION_ID | | WezTerm | TERM_PROGRAM=WezTerm, WEZTERM_EXECUTABLE | | Ghostty | TERM_PROGRAM=ghostty | | Windows Terminal | WT_SESSION |

🚦 Progress States

| Tab Indicator | What It Means | | ------------------- | ---------------------------------------- | | 🔄 Spinner | Agent is thinking or executing a tool | | ⏸️ Paused at 50% | Agent is waiting for your approval | | 🔴 Red bar | A tool reported a non-zero exit code | | (cleared) | Agent is idle, waiting for your input |

📦 Installation

npm install -g codex-terminal-progress

⚙️ Setup

Auto-setup (recommended)

codex-terminal-progress setup

This appends the required hook entries to ~/.codex/config.toml.

Manual configuration

Add the following to ~/.codex/config.toml:

[[hooks.SessionStart]]
[[hooks.SessionStart.hooks]]
type = "command"
command = "codex-terminal-progress hook session-start"

[[hooks.UserPromptSubmit]]
[[hooks.UserPromptSubmit.hooks]]
type = "command"
command = "codex-terminal-progress hook user-prompt-submit"

[[hooks.PreToolUse]]
matcher = ".*"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "codex-terminal-progress hook tool-use"

[[hooks.PostToolUse]]
matcher = ".*"

[[hooks.PostToolUse.hooks]]
type = "command"
command = "codex-terminal-progress hook post-tool-use"

[[hooks.PermissionRequest]]
matcher = ".*"

[[hooks.PermissionRequest.hooks]]
type = "command"
command = "codex-terminal-progress hook permission-request"

[[hooks.Stop]]
[[hooks.Stop.hooks]]
type = "command"
command = "codex-terminal-progress hook stop"

🔐 Trust the hooks

Codex requires you to review and trust new hooks before they run:

1. Start Codex: codex
2. Type /hooks in the Codex CLI prompt
3. Review each hook and press t to trust it
4. Restart Codex

Progress indicators will now appear in your terminal tab.

🛠️ CLI Reference

Usage:
  codex-terminal-progress hook <event>     Handle a Codex hook event
  codex-terminal-progress write <state>    Write a progress state directly
  codex-terminal-progress setup            Add hooks to ~/.codex/config.toml
  codex-terminal-progress status           Check if your terminal is supported

States: busy, idle, error, paused

Examples

# Check if your setup is working
codex-terminal-progress status

# Manually test each state
codex-terminal-progress write busy
codex-terminal-progress write paused
codex-terminal-progress write error
codex-terminal-progress write idle

🧩 How It Works

This package leverages Codex Hooks, Codex CLI's built-in extensibility framework. When you configure the hooks, Codex invokes the appropriate script at each lifecycle event. The script writes an OSC 9;4 escape sequence to /dev/tty, which tells your terminal emulator to update the progress indicator in the tab header.

sequenceDiagram
    participant User
    participant CodexCLI
    participant Hook as codex-terminal-progress
    participant Monitor as parent watchdog
    participant Terminal

    User->>CodexCLI: Sends prompt
    CodexCLI->>Hook: fires UserPromptSubmit hook
    Hook->>Terminal: writes busy progress
    Hook->>Monitor: watches CodexCLI process

    CodexCLI->>Hook: fires PreToolUse hook
    Hook->>Terminal: writes busy progress

    CodexCLI->>Hook: fires PostToolUse hook
    Hook->>Terminal: writes idle progress

    User->>CodexCLI: Ctrl+C
    Monitor->>Terminal: writes idle progress

🛡️ Safety & Resilience

• Debounce protection — rapid tool transitions don't cause flickering
• Parent watchdog — clears progress when Codex exits before it can fire the stop hook
• Stale session detection — the next session also clears any previously orphaned progress indicator
• SIGINT/SIGTERM handlers — clean up progress on abrupt termination
• Graceful degradation — silently exits if /dev/tty is unavailable or the terminal is unsupported

⚙️ Configuration

| Environment Variable | Effect | | --------------------------- | ------------------------------- | | CODEX_TERMINAL_PROGRESS=0 | Disables terminal progress |

📄 License

MIT