Context
A codex-dynamic session can launch durable workflows and receive a callback when
they finish, but the session does not continuously show workflow progress. Stock
Codex currently exposes only predefined TUI status-line fields; plugins cannot add
a custom workflow field or command-backed status item. See
openai/codex#20244.
A window-level tmux indicator is not sufficient because one tmux window may contain
several panes, each running an independent Codex session and separate workflows.
Settled approach
Implement an optional, pane-aware tmux integration.
- Capture the originating
$TMUX_PANE when a workflow is launched.
- Associate each durable run with that pane in workflow metadata or a small derived
registry.
- Add a cheap observational command such as
codex-workflows statusline that reads
durable state and emits a compact summary without making model calls.
- Display the summary in the originating pane border or pane title, not as one
window-global workflow count.
- Show the indicator only while that pane has active workflows by default.
- Aggregate multiple workflows launched from the same pane in a predictable way.
- Clear stale pane state when workflows finish, the pane disappears, or tmux is no
longer running.
Example pane-border text:
codex · WF 6/10 complete · 3 running · 1 failed
A secondary configuration may put the currently active pane summary in the main
tmux status bar, but the pane border is the preferred default because it remains
unambiguous in split windows.
Constraints
- This must be purely observational and must not launch an agent or consume model
tokens.
- It must not replace the app-server completion callback or introduce a polling loop
inside the Codex conversation.
- Workflow execution must continue normally if tmux exits or the display helper
fails.
- Updates should be inexpensive and bounded, approximately once per second at most.
- Do not require a maintained Codex fork. If upstream later supports command-backed
TUI status fields, reuse the same status command for native integration.
Acceptance criteria
- Two Codex sessions in two panes show only their own workflow progress.
- Multiple runs from one pane produce a useful aggregate summary.
- Success, failure, cancellation, and stale runs are visually distinguishable.
- No model calls are made for status updates.
- Pane closure and tmux restart leave no persistent updater process or stale display.
- Users can enable or disable the integration without changing workflow behavior.
- Documentation explains setup, limitations, and the distinction from native Codex
TUI status.
Context
A
codex-dynamicsession can launch durable workflows and receive a callback whenthey finish, but the session does not continuously show workflow progress. Stock
Codex currently exposes only predefined TUI status-line fields; plugins cannot add
a custom workflow field or command-backed status item. See
openai/codex#20244.
A window-level tmux indicator is not sufficient because one tmux window may contain
several panes, each running an independent Codex session and separate workflows.
Settled approach
Implement an optional, pane-aware tmux integration.
$TMUX_PANEwhen a workflow is launched.registry.
codex-workflows statuslinethat readsdurable state and emits a compact summary without making model calls.
window-global workflow count.
longer running.
Example pane-border text:
A secondary configuration may put the currently active pane summary in the main
tmux status bar, but the pane border is the preferred default because it remains
unambiguous in split windows.
Constraints
tokens.
inside the Codex conversation.
fails.
TUI status fields, reuse the same status command for native integration.
Acceptance criteria
TUI status.