Feature: Semantic narrative view as an alternative to raw execution logs

What variant of Codex are you using?

CLI, App (GUI)

What feature would you like to see?

Problem

As Codex evolves toward harness engineering and multi-agent orchestration, the current output model — raw diffs, tool invocation logs, and line-level patch output — becomes increasingly difficult for developers to reason about at the intent level.

Today, a typical Codex session surfaces output like this:

995 -
996 +
997 -
998 +
...
• Ran cd ~/projects/mcp/outliner && timeout 240s codex exec review --ephemeral
  │ --commit 039c964
  └ mcp: infra ready
    mcp: infra ready
    … +358 lines
        fn read_doc_file_by_path(&self, path: &Path) -> Result<DocFileV1, StorageError> {
            let bytes = fs::read(path)?;

This is useful for debugging, but it forces the developer to mentally reconstruct what the agent was thinking and why from low-level artifacts. Crucially, with raw log output, errors and misguided decisions are often noticed too late — by the time you spot a problem buried in hundreds of diff lines and tool traces, the agent has already gone far down the wrong path. In contrast, when the agent briefly explains its reasoning at each step, the developer can instantly catch illogical actions relative to their original intent and course-correct before wasted work accumulates.

Proposed Solution

Introduce a dual-mode output system with two complementary views:

1. Log view (current behavior) — raw diffs, tool calls, command outputs, and line-level patches.
2. Narrative view (new) — a high-level, human-readable stream of the agent's reasoning, decisions, and progress expressed as short semantic messages.

Example narrative output:

- "Investigated module A — component not found here, root cause likely in module B" - "Creating feature A; implementing sub-component B as a dependency" - "Found inconsistency in config schema — applying migration before proceeding"

The narrative view would surface the agent's chain of reasoning: what it explored, what hypotheses it formed, what decisions it made, and why — rather than just the mechanical trace of commands executed.

Expected Behavior

• A CLI flag (e.g., --output-mode=narrative | log | both) to toggle between views.
• In the Codex GUI (App), a toggle or split-pane that lets users switch between "Narrative" and "Log" in real time.
• Narrative entries should be concise (1–2 sentences), timestamped, and linked to the corresponding log entries for drill-down.
• In multi-agent sessions, sub-agent activity should be surfaced as collapsible narrative summaries within the parent agent's timeline — giving the developer oversight of the entire orchestration in a single unified TUI/GUI without turning the output into an endlessly scrolling event log.

Benefits

• Developer agency: the user becomes an active participant in the process — observing the agent's doubts, reasoning chain, and decision logic — rather than trying to "supervise a black box."
• Early error detection: instead of discovering mistakes after hundreds of lines of output, the developer sees intent-level summaries and can immediately spot when the agent's reasoning diverges from the desired direction.
• Sub-agent visibility: in multi-agent orchestration, narrative summaries from sub-agents roll up into a coherent overview, keeping the developer in control without drowning in per-agent log noise.
• Better UX for Codex App: enables intuitive timeline/flow visualizations of agent actions, oriented around meaning rather than raw system output.
• Scalability: as agent sessions grow longer and involve more tools, narrative summaries become essential for maintaining human oversight without information overload.

Additional information

This feature becomes especially relevant as Codex moves deeper into multi-agent and harness-based workflows. The longer and more complex the agent session, the harder it is to follow raw logs. A narrative layer would also open the door for richer GUI experiences (e.g., collapsible reasoning timelines, intent-based filtering) in Codex App.

Related prior art: chain-of-thought traces in LLM research, structured logging with semantic annotations (e.g., OpenTelemetry span events), and IDE debugger "call narrative" concepts.