codex

Documentation

Overview

Package codex is the Source adapter for OpenAI Codex CLI transcripts under $CODEX_HOME/sessions (default ~/.codex/sessions): date-partitioned rollout-<ts>-<uuid>.jsonl files, each a self-contained session whose first record is a session_meta header.

Every JSONL line is a {type,timestamp,payload} wrapper. The header's lineage fields (thread_source, parent_thread_id, forked_from_id) tag subagent/forked threads so the index hides them by default and collapses fork families to their root — the same treatment Claude subagents get. Codex message records carry NO per-message id, so this adapter mints a deterministic uuid from the session id + ordinal, stable across reindex.

Index

• func ConfigDir() string
• func Registration() source.Registration
• func SessionsRoot() string
• type Adapter
  • func New() *Adapter
  • func (a *Adapter) Discover() ([]source.Container, error)
  • func (a *Adapter) DiscoverRoot(root string) ([]source.Container, error)
  • func (a *Adapter) Messages(c source.Container) ([]model.Message, error)

Functions

func ConfigDir

func ConfigDir() string

ConfigDir is the Codex config dir: $CODEX_HOME if set, else ~/.codex. Returns "" only when the home directory cannot be resolved (no CODEX_HOME and no resolvable user home) — same "resolve the path, don't require it to exist" contract as paths.ConfigDir for Claude Code, so a writer (e.g. `rawclaw setup`) can compute the target path before anything is on disk yet.

func Registration

func Registration() source.Registration

Registration wires the Codex adapter into the source registry. Call source.Register(codex.Registration()) explicitly at start-up.

func SessionsRoot

func SessionsRoot() string

SessionsRoot is $CODEX_HOME/sessions, or ~/.codex/sessions when CODEX_HOME is unset. Returns "" only when the home directory cannot be resolved.

Types

type Adapter

type Adapter struct{}

Adapter reads Codex CLI transcripts. Stateless; the zero value is usable.

func New

func New() *Adapter

New returns a ready Codex adapter.

func (*Adapter) Discover

func (a *Adapter) Discover() ([]source.Container, error)

Discover walks the sessions tree and returns one Container per rollout file, reading only each file's session_meta header for lineage + cwd. A file whose header is unreadable is skipped (logged, grouped). Returns (nil, nil) when the tree is absent — an empty corpus is not an error.

func (*Adapter) DiscoverRoot

func (a *Adapter) DiscoverRoot(root string) ([]source.Container, error)

DiscoverRoot is Discover against an EXPLICIT sessions tree — the same walk, pointed at a replicated tree (another machine's rollouts synced onto this disk) instead of this machine's $CODEX_HOME. "" yields (nil, nil).

func (*Adapter) Messages

func (a *Adapter) Messages(c source.Container) ([]model.Message, error)

Messages flattens one rollout into normalized messages in file order. It maps the response_item records (message / reasoning / function_call[_output]) and skips headers, telemetry (event_msg, token_count), and control records (turn_context, world_state, compacted, …). Message records carry no id, so a deterministic uuid is minted from the session id + ordinal.