Codex sessions

CodexRollout

A rollout found in the codex sessions tree.

Usage

CodexRollout(
    path,
    session_id,
    compressed,
)

Attributes

path: Path: The rollout’s path.
session_id: str: The session id encoded in the rollout filename.
compressed: bool: Whether the rollout is a .jsonl.zst file.

CodexSessionInfo

The identity, lifecycle, and usage of one codex rollout.

Usage

Source

CodexSessionInfo(
    rollout_thread_id,
    session_id,
    parent_thread_id,
    forked_from_id,
    cwd,
    originator,
    cli_version,
    model_provider,
    lifecycle,
    turn_id,
    pending,
    last_event_epoch,
    usage
)

Attributes

rollout_thread_id: str | None: This rollout’s own thread id (the session-meta id).
session_id: str | None: The logical session id; a forked rollout inherits its origin’s.
parent_thread_id: str | None: The spawning thread’s id for a subagent rollout, else None.
forked_from_id: str | None: The origin thread’s id when this rollout is a fork, else None.
cwd: str | None: The working directory recorded in the session meta.
originator: str | None: What launched the session, such as codex_exec.
cli_version: str | None: The codex CLI version that wrote the rollout.
model_provider: str | None: The model provider, such as openai.
lifecycle: Lifecycle: The latest turn’s lifecycle state.
turn_id: str | None: The latest turn’s id, or None before any turn brackets.
pending: tuple[CodexPendingItem, …]: The dangling tool calls in an open turn, in document order.
last_event_epoch: int | None: The latest envelope timestamp as epoch seconds, or None.
usage: CodexUsage | None: The session token totals, or None when no token_count event occurred.

CodexUsage

Session-level token totals lowered from a codex rollout.

Usage

Source

CodexUsage(
    input_tokens,
    cached_input_tokens,
    output_tokens,
    reasoning_output_tokens,
    total_tokens,
    model_context_window,
    token_count_events
)

The totals are the last observed cumulative total_token_usage fields — codex token_count events carry running totals, not per-turn deltas — so this is the session’s final accounting, not a sum.

Attributes

input_tokens: int | None: Total input tokens, or None when never reported.
cached_input_tokens: int | None: Cached input tokens, or None when never reported.
output_tokens: int | None: Output tokens, or None when never reported.
reasoning_output_tokens: int | None: Reasoning output tokens, or None when never reported.
total_tokens: int | None: Total tokens, or None when never reported.
model_context_window: int | None: The model’s context window, or None when never reported.
token_count_events: int: The number of token_count events observed.

CodexPendingItem

A dangling tool call in the rollout’s open turn.

Usage

Source

CodexPendingItem(tool_use_id, name, kind)

Attributes

tool_use_id: str | None: The call’s call_id.
name: str: The tool’s name, such as exec.
kind: str: How the call contributes to the verdict; always mid_tool for codex.

codex.sessions_root()

The codex sessions root, defaulting to ~/.codex/sessions.

Usage

Source

codex.sessions_root(root=None)

Parameters

root: Path | None = None: An explicit root; when None, SESSIONS_ROOT.

Returns

Path: The root that discover() and find_transcript() scan.

codex.discover()

Every codex rollout under root, newest first.

Usage

Source

codex.discover(root=None)

Rollouts live as rollout-<timestamp>-<session_id>.jsonl (or .jsonl.zst) files under the date-sharded sessions tree. Each result preserves its path, session id, and compression state.

Parameters

root: Path | None = None: The sessions root; when None, sessions_root().

Returns

tuple[CodexRollout, …]: The rollouts, newest first; () when the root does not exist.

Example

>>> for rollout in discover():
...     print(rollout.session_id, rollout.path)

codex.find_transcript()

Locates session_id’s rollout under the codex sessions tree.

Usage

Source

codex.find_transcript(session_id, root=None)

Only uncompressed .jsonl rollouts resolve. Compressed rollouts appear in discover() but do not resolve until zstd support lands. The newest wins among same-id uncompressed rollouts.

Parameters

session_id: SessionId: The codex session id, as it appears in the rollout filename.
root: Path | None = None: The sessions root; when None, sessions_root().

Returns

Path | None: The rollout path, or None when no rollout carries that session id.

codex.children_of()

Finds the direct child rollouts spawned by session_id.

Usage

Source

codex.children_of(session_id, *, root=None)

Compressed rollouts are excluded because their session metadata cannot yet be inspected. Results are ordered newest first.

Parameters

session_id: SessionId: The parent rollout’s thread id.
root: Path | None = None: The sessions root; when None, sessions_root().

Returns

tuple[CodexRollout, …]: The direct child rollouts, newest first; () when there are none.

codex.session_info()

The identity, lifecycle, and token usage of the rollout at path.

Usage

Source

codex.session_info(path)

The native extension reads and folds the rollout in one pass, returning the session identity, the turn lifecycle, any dangling calls, and the token totals.

Parameters

path: Path: The .jsonl rollout to inspect.

Returns

CodexSessionInfo: The rollout’s session info.