Workflow & Core Tools · daymade/claude-code-skills

read-codex-history

Name: read-codex-history
Author: daymade/claude-code-skills

Reads, searches, and exports local OpenAI Codex history without continuing the old task. Lists recent Codex sessions, extracts exact prompt-ledger inputs by Session, locates a rollout by verified session_meta identity, reconstructs one chronological user/assistant timeline with fork and compaction lineage, and performs bounded keyword search across live and archived rollouts. Use whenever the user asks what they told Codex, wants recent original inputs, a Codex Session ID, full prior context, fork ancestry, or evidence of what a Codex run did. For Claude Code history use read-claude-code-history.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandDual-pass Audit

Author daymadeGitHub daymade/claude-code-skills ↗Stars 1385License MIT（仓库根 LICENSE；GitHub API spdx MIT）Commit d5c4678cb5

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Reads across three non-interchangeable Codex history surfaces: history.jsonl (prompt ledger, raw user submissions), state_*.sqlite (manifest metadata), and rollout-*.jsonl under sessions|archived_sessions (full event streams); routes each query to dedicated scripts and forbids ad-hoc join re-inventions.

daymade-claude-code/read-codex-history/SKILL.md

| `<codex-home>/history.jsonl` | What the user submitted, keyed by Session ID and internal epoch timestamp | Exact recent user-input tables |

The SKILL declares: 'Do not substitute one surface for another. A prompt-ledger row proves what was submitted, not what the Agent answered. A state DB path is only a candidate until the rollout's session_meta.id matches.'—this is the core of this skill's correctness model.

Identity and lineage gating: before establishing any behavioral conclusion, the agent must (1) verify prompt-ledger Session IDs, (2) locate rollouts by internal session_meta.id rather than filename, (3) require parsed session_meta.id == requested ID, and (4) require declared parent IDs + exact history_base.end_byte_offset on fork edges, rejecting missing, ambiguous, cyclic, or mismatched ancestors.

daymade-claude-code/read-codex-history/SKILL.md

Locate rollout candidates by their internal `session_meta.id`, not filename alone.

The SKILL explicitly notes that this fixes two real-world incidents: 'a prompt-ledger Session whose state DB pointed at another rollout, and a /fork input with no child rollout'.

SQLite reads are enforced as read-only: _core/codex.py connects using file: URI ?mode=ro and sets PRAGMA query_only=ON, falling back to raw rollout JSONL scans if schemas are incompatible.

daymade-claude-code/read-codex-history/scripts/_core/codex.py

return "file:" + quote(path.resolve().as_posix(), safe="/:@") + "?mode=ro"

Both inspect_codex_database and collect_codex_from_database in the same file execute connection.execute("PRAGMA query_only = ON"), enforcing 'read tools must not write to databases' directly at the SQLite engine level.

Writer-lock observations are positive-only: performs non-blocking reads of the .coordination.lock file; holding a lock only proves that a process held a Codex canonical thread lock at snapshot time, without identifying processes or proving ongoing liveness.

daymade-claude-code/read-codex-history/scripts/list_local_history.py

A held lock proves only that some process owns the advisory lock; it does not

Lines 251-283 of list_local_history.py acquire the coordination lock non-blockingly before inspecting admitted thread locks to avoid competing with an actively writing Codex instance; output semantics explicitly declare 'absence is not proof of inactivity'.

Input reconciliation (reconcile_codex_inputs.py): combines the existing ledger and a strict lineage reader to produce raw input counts and citations for an entire session, preserving occurrence, verbatim text, and source coordinates; exit 2 or complete:false is treated as incomplete, and scope_input_count: null ≠ 0.

daymade-claude-code/read-codex-history/SKILL.md

Use the reconciler to compose the existing ledger and strict lineage readers. It preserves occurrences, original strings, and source coordinates.

The SKILL also mandates 'Treat exit 2 or complete: false as an incomplete result', prohibiting unverified records from being counted toward the total.

Context budget discipline for oversized briefings: when a full briefing exceeds model context, it is materialized once to a private temporary file with recorded SHA-256 and line count; reads are performed in bounded intervals by header/coordinate, unread sections are explicitly reported as gaps, and piecing together a false 'complete' view via fragmented reruns is forbidden.

daymade-claude-code/read-codex-history/SKILL.md

materialize it once to a private temporary file and record its SHA-256 plus line count before reading

read_codex_session.py --full output can reach several megabytes; this rule enforces reading discipline for the agent: 'A single briefing can be read in bounded chunks, but completeness must never be faked.'

2Core Capabilities

01Recent Codex session inventory across live and archived rollouts (including positive writer-lock evidence and source origin tags)

02Verbatim prompt-ledger user input export: global window or session-expanded, JSON-faithful storage representations

03Full-session raw input reconciliation (including inherited history counts, citations, and hash-bound exclusion cross-checks)

04Pinpoint rollout localization via internal identity (sub-second, avoiding full-corpus scanning)

05Single-session timeline reconstruction: fork lineage, parent byte offsets, compaction, plans, tool calls, and end reasons

06Bounded full-event search (--codex-only constrained to Codex surfaces, explicitly failing upon budget timeout instead of faking completeness)

3External Dependencies

Kind	Dependency / Endpoint
cli	git（工作区状态上下文，read_codex_session 中 subprocess）
cli	rg/grep（text.py 可选路径预过滤，与 claude 版共享 core）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Local script or command execution: runs 5 bundled scripts via python3 (pure standard library)

Audit Notes: Operates strictly read-only on local Codex history (history.jsonl / state_*.sqlite opened with mode=ro + PRAGMA query_only / rollout JSONL), with zero network exfiltration, credential reading, or standard file modifications; local execution is limited to git and rg/grep subprocesses, along with agent-materialized private temporary briefing files per instruction. Highly sensitive data with built-in self-defense (identity gating, explicit gap accounting, zero-exfiltration constraints).

5Second-Pass Verification

[ok] sqlite 只读强制 — _core/codex.py: sqlite_uri 加 ?mode=ro；inspect/collect 均 PRAGMA query_only=ON。
[ok] 无任何网络外发 — 全 scripts 目录扫描无 requests/urllib/socket/curl/wget；本 skill 不含 history_index 类下载器。
[ok] 凭证读取检查 — 全目录无 auth.json/API key/.env/密钥 env 访问；只读 rollout 与 ledger。
[ok] SKILL 声明的 flag 与脚本存在性 — reconcile --through-record/--omit-first/--omit-last、list_codex_user_inputs --recent/--session-id/--per-session、analyze_sessions search --codex-only、read_codex_session --full 均核对到 argparse。
[unlocatable] rollout 格式跨版本声明（0.142.2–0.149.0） — codex_rollout_format.md 自述 'Verified against ~2,600 real rollouts'；源码内无法复核该实测声明，未运行 Codex 验证。
[ok] writer-lock 观测语义 — list_local_history.py 251-283 非阻塞取协调锁 + 输出 positive-only 语义字符串，与 SKILL 描述一致。

6Verdict & Scenarios

Three-surface separation + identity gating: prevents real-world failure modes such as 'state DB pointing to wrong rollout' and 'fork inputs lacking child rollouts'

Database reads enforced strictly at the SQLite layer (mode=ro + query_only), offering stronger guarantees than documentation promises alone

Dual-source reconciliation between prompt-ledger and rollout preserves occurrence, raw text, and coordinates, ensuring input counts are never conflated with critique counts

Enforced context budget discipline: single-pass materialization + SHA accounting + explicit gap reporting prevents hallucinated completeness from fragmented chunks

Best for: Ideal for scenarios requiring verified Codex session evidence: retrieving original user inputs and Session IDs, auditing fork lineage, comparing states before/after compaction, and pre-deployment behavioral auditing; pairs naturally with continue-codex-work to implement a read-only investigation -> execution relay, especially for privacy-sensitive environments requiring zero data exfiltration.

Not for: Not intended for resuming/continuing Codex sessions or modifying their target projects (use continue-codex-work for that); useless in environments without local Codex rollouts; not suited for semantic fuzzy recall where wording has shifted (use indexed search skills instead)—this skill supports exact search only, without hybrid retrieval.

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload read-codex-history.tar.gz

sha256: c30dd57b4165452f…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.