›_ Codex Issues
Codex Issues / #25879

Surface codex activity on the terminal tab via iTerm2 OSC 21337 tab status

Open 💬 2 comments Opened Jun 2, 2026 by gnachman
💡 Likely answer: A maintainer (etraut-openai, contributor) responded on this thread — see the highlighted reply below.

What variant of Codex are you using?

CLI (TUI), on macOS / iTerm2.

What feature would you like to see?

Surface a backgrounded codex session's activity on the terminal tab using iTerm2's OSC 21337 tab-status protocol, so a long-running turn is visible without switching to the tab. OSC 21337 paints a colored dot and short label on the tab itself and is ignored silently by other terminals, so it's a no-op everywhere else.

Proposed as three small, independently reviewable pieces:

  1. Base protocol wiring. Emit Working / Waiting / Idle as a colored dot + label. Gated on IsTerminal (so piped codex exec stays clean) and behind a new tui.tab_status config (default on, mirroring tui.terminal_title). Waiting is derived from the existing terminal_title_requires_action signal so the tab status and the action-required title share one source of truth.
  2. Shell-argv hardening. Relax the display-only command extraction so argv flattened past [shell, flag, script] still strips the zsh -lc wrapper; also improves the existing visible exec-history rendering for the same shape. Approval / canonical-identity matching stays strict.
  3. Per-call detail. A detail string ("Run python3 build.py", "Read README.md"), continuity hints ("after: X" while thinking, "last: X" when idle), a 250 ms throttle, and sanitisation (control + Trojan-Source bidi/invisible stripping, shared with the terminal-title sanitiser).

Additional information

For context: I'm the maintainer of iTerm2. OSC 21337 tab-status support currently ships in the iTerm2 beta, so this feature has a visible effect there today; in terminals without OSC 21337 support (including iTerm2 stable) it's a silent no-op. Happy to advise on the protocol details.

Working, tested code is ready as a stacked set of branches in a public fork (gnachman/codex): pr-tab-status-base, pr-shell-command-joined, pr-tab-status-detail, reviewable as PRs https://github.com/gnachman/codex/pull/1 -> https://github.com/gnachman/codex/pull/2 -> https://github.com/gnachman/codex/pull/3 in that order.

Per docs/contributing.md (external code is invitation-only), I tried to open the upstream PR but CreatePullRequest is blocked for my account. If the team is open to this, I'd welcome an invitation to submit the stack, or am happy to have it taken over.

View original on GitHub ↗

2 Comments

etraut-openai contributor · 2 months ago

Thanks for reaching out, and a big thanks for maintaining iTerm2!

The Codex TUI already supports OSC 0 terminal title updates, and it's customizable using the /title slash command. What benefit would users see if we were to also support OSC 21337?

Am I correct in understanding that OSC 21337 is specific to iTerm2? Or is it a cross-terminal standard?

gnachman · 2 months ago

21337 is specific to iTerm2. There's no cross-terminal standard for this yet; if it proves useful I expect others to adopt it. On terminals that don't support it the sequence is silently ignored, so it's safe to emit unconditionally, and unknown keys are ignored too, so it won't break as the spec grows.

The key difference from OSC 0: a title is a single freeform string. OSC 21337 is a separate, structured status channel, a colored dot plus a short machine-readable state (working / waiting / idle) plus a detail line, sitting alongside the title rather than replacing it. Because the state is structured rather than text, the terminal can do things it can't do with a title:

  • Show the status as a tab subtitle without clobbering the title or the user's /title.
  • Session Status tool: one panel showing at a glance which tabs are busy, idle, or waiting on the user, plus what it's waiting for or the last action it took.
  • Length constraints are lessened compared to titles. The status tool reserves three lines for the "detail" text.
  • Notify on waiting: alert the user specifically when the assistant is blocked on their response (most often a permission prompt).
  • Orchestration: a controller can know for certain whether an agent is still working, which makes coordinating across tabs reliable and cheap (e.g. have Codex implement a feature in one tab, then test it in another tab over ssh).

I've been using this for my own development for a few weeks and it solves my main pain point with coding assistants: they're often silently blocked on me to answer a question or grant permission. Now I have a panel that shows me where my attention is needed most. The orchestration piece has also been valuable: I can have a review agent find bugs, hand them to the coding agent, and iterate until it settles, which takes a tedious low-effort loop off my plate. I'm sure Codex will do more of this itself over time, but orchestration stays useful at higher levels of abstraction.

Finally, once Codex can report its status, it unblocks a proper Codex integration in iTerm2. I have already built the coding agent integration feature, so I can show you what it would look like. Adding Codex support is easy once I have status.

Here's the session status panel:
<img width="250" height="346" alt="Image" src="https://github.com/user-attachments/assets/5d3bb068-5138-4edf-97be-15ba8e66d3e2" />

When a coding agent is detected, we can automatically enter a "workspace" mode that adds related subtabs: chat for coding, diff for viewing changes in the repo, and code review for independently analyzing the work.
<img width="1497" height="565" alt="Image" src="https://github.com/user-attachments/assets/53439594-52b0-4bda-be2a-49102048a896" />

Code review findings go into a "Clippings" panel that is shared between the sub-tabs so you can easily paste them into the coding agent:
<img width="565" height="531" alt="Image" src="https://github.com/user-attachments/assets/132bf6fe-f6ea-49b9-a594-933e43b9c48e" />