analyzing-codex-sessions

Skill Directory

Resolve SKILL_DIR to the absolute directory containing this SKILL.md, as shown by the current host, before using any bundled path below. Before a shell command uses $SKILL_DIR, assign it in that command or replace it with the resolved path. It is not a host-exported environment variable.

Analyzing Codex Raw Sessions

Overview

Codex CLI writes every thread — the root conversation and each subagent alike — as its own JSONL rollout file, one JSON object per line. Each line has a top-level type, and the two types that matter carry a nested payload.type that does the real discriminating.

Core principle: event_msg/item_completed is the digested layer; response_item is the raw layer. Analyze items first — they carry semantic types with timing and exit codes already attached. Drop to response_item only for prompt text and reasoning content.

A CommandExecution item hands you the command, its exit_code, and its duration in a single object. The equivalent question asked of response_item requires correlating a custom_tool_call with its custom_tool_call_output and reconstructing timing from entry timestamps. Start at the digested layer and stay there unless you need something it does not carry.

When to Use

• Analyzing what happened in a Codex run (commands, failures, file changes, cost)
• Reconstructing a thread tree — which subagents a root spawned and what each did
• Extracting metrics (tokens, wall duration, command counts, failure counts) across Codex threads
• Debugging why a Codex subagent failed or produced poor results
• Comparing Codex reviewer roles (code-reviewer, php-tests-reviewer, …) across runs
• Building or maintaining Codex rollout analysis scripts

Before You Start

Your goal	Start here
Understand what a whole Codex run did	codex_session_analyzer.py — it resolves the root and walks its subagent tree for you
Analyze one thread you already have the id for	The rollout file whose name ends -{thread-id}.jsonl, then its item_completed entries
Find sessions for a specific project	Scan line 1 of each rollout in the date window and match session_meta.payload.cwd — there is no per-project directory
Compare metrics across threads or roles	codex_session_metrics.py
Debug a failing command	item_completed → CommandExecution items with non-zero exit_code; stderr and aggregated_output are inline
Recover the prompt text or the model's reasoning	response_item entries of type message and reasoning — items do not carry full prompts
Attribute cost to a thread	The last event_msg/token_count entry's info.total_token_usage