← Docs hub

Codex CLI adapter

Status: Production Module: llmwiki.adapters.codex_cli Source: llmwiki/adapters/codex_cli.py

What it reads

OpenAI's Codex CLI stores session transcripts as .jsonl under:

~/.codex/sessions/
    YYYY/MM/DD/rollout-*.jsonl
~/.codex/projects/
    <project>/
        <session-id>.jsonl

The adapter checks both roots. Override with adapters.codex_cli.roots in config.json.

Enable it

Core adapter — included on a bare llmwiki sync when either root exists. No --adapter flag required.

python3 -m llmwiki adapters | grep codex_cli
python3 -m llmwiki sync

Project slug derivation

Codex date-buckets sessions under ~/.codex/sessions/YYYY/MM/DD/, so the directory path is not the project. The adapter reads the first session_meta record's cwd and uses its basename (lowercased, spaces → dashes). If cwd is missing, it falls back to the parent directory name.

Schema versions supported

SUPPORTED_SCHEMA_VERSIONS = ["v0.x", "v1.0"]

Codex-native record types (response_item, event_msg, …) are normalized into the shared Claude-style format used by the converter.

Automated (headless) sessions

filters.exclude_headless (default on) applies to every coding-agent adapter. Codex has no verified automation-launch markers in the store today, so Codex sessions are treated as not headless. Interactive chats stay eligible; turn the filter off only if you need other agents' automated runs included. See Multi-agent setup — What “automated” means.

Tokens capture

When a Codex session JSONL includes event_msg payloads with payload.type == "token_count", sync maps measured usage into the shared Analytics Tokens buckets (input, cache creation, cache read, output) and writes nonempty token_totals / usage/session-tokens.json the same way as other agents (#324).

Verified fields (prefer the last cumulative snapshot):

Native field Role
info.total_token_usage Session cumulative — use the last token_count only (do not sum successive totals)
info.last_token_usage Per-turn delta — sum once across the session when totals are absent
input_tokens, cached_input_tokens, cache_write_input_tokens, output_tokens Mapped into the four Tokens buckets (cache subsets are not double-counted as input)
reasoning_output_tokens When present, subtracted from output so reasoning is not counted toward Tokens

Not Tokens: model_context_window (occupancy / window size) and rate_limits / plan percentages. Sessions without measurable token_count fields stay missing — they are never written as measured zero.

Historical backfill: if ~/.codex/sessions (or configured roots) still exist, re-run llmwiki migrate session-tokens after upgrading so older Codex sessions fill in; fingerprint-changed sync covers new or changed sessions. Prefer a fast Codex-only pass when you do not need Claude/Cursor origins yet:

llmwiki migrate session-tokens --vault /path/to/vault --adapter codex_cli --skip-raw
llmwiki build --vault /path/to/vault

See UPGRADING — session Tokens.

Configuration

{
  "adapters": {
    "codex_cli": {
      "roots": ["~/.codex/sessions", "~/.codex/projects"]
    }
  }
}

Privacy

Redaction is the same as for Claude Code — API keys, tokens, and emails are scrubbed at convert time, and home-path usernames too when redaction.redact_username: true. Add Codex-specific path patterns to redaction.extra_patterns if needed.

Testing

python3 -m llmwiki adapters
python3 -m pytest tests/ -k codex -q

See also

Keyboard shortcuts

⌘K / Ctrl+KOpen command palette
/Focus search
g hGo to home
g pGo to projects
g sGo to sessions
j / kNext / prev row (tables)
?Show this help
EscClose dialogs

Structured queries

Mix key:value filters with free text in the palette:

type:sessionOnly session pages
project:llm-wikiFilter by project name (substring)
model:claudeFilter by model name (substring)
date:>2026-03-01Sessions after a date
date:<2026-04-01Sessions before a date
tags:rustPages mentioning a tag/topic
sort:dateSort results by date (newest first)

Example: type:session project:llm-wiki date:>2026-04 sort:date