Skip to content

The one and only agent harness for complex codebases. Project memory, planning, execution, and verified completion inside Codex.

1.8 KB
Raw Blame

Codex Sessions

Codex has two useful surfaces:

  • $CODEX_HOME/state_*.sqlite stores thread metadata.
  • $CODEX_HOME/sessions/**/rollout-*.jsonl and archived rollout files store event transcripts.

Use the broad finder for Codex discovery:

python3 -B scripts/find-agent-sessions.py list --platform codex --limit 10
python3 -B scripts/find-agent-sessions.py search "deploy" --platform codex
python3 -B scripts/find-agent-sessions.py search --query "deploy" --query "token usage" --platform codex --workers 32
python3 -B scripts/find-agent-sessions.py get <session-id> --platform codex

Important filters: --from, --to, --cwd, --model, --root, --limit, and --include-subagents.

Spawned (subagent) threads

Codex subagent threads are ordinary rows in threads with their own rollout files. Two linkage sources:

  • thread_spawn_edges(parent_thread_id, child_thread_id, status) — authoritative parent→child table.
  • threads.source — cli / exec / vscode for user-started threads, or JSON for spawned ones:
    • {"subagent": "review"}, {"subagent": "memory_consolidation"} — built-in side threads.
    • {"subagent": {"thread_spawn": {"parent_thread_id": "...", "depth": 1, "agent_nickname": "Tesla", "agent_role": "explorer"}}} — collab/multi-agent spawns (depth can exceed 1: children spawn grandchildren).

threads also carries agent_nickname, agent_role, model, first_user_message, tokens_used. Without the SQLite DB, the same linkage is in each rollout file's first line: type: "session_meta" whose payload has id, cwd, model_provider, forked_from_id, and the same source.subagent.thread_spawn object.

The finder maps these to parent_id and agent = "nickname (role)"; get <parent-thread-id> lists children under subagents, and get <child-thread-id> returns the child's rollout events.