read-codex-history
Reads, searches and exports local OpenAI Codex history without continuing work: session inventory, timelines, verbatim user input, indexed search, and rollout identity/fork lineage
Install / Use
npx skills add daymade/claude-code-skills --skill read-codex-historyInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
MarketingSupported Platforms
Tags
Our assessment of read-codex-history
read-codex-history scores 93/100 on our quality scale, 148th of 642 Marketing skills we index (top 24%).
Its SKILL.md is 17 KB long, well organised into 18 sections with 8 code examples: a thorough specification that gives an agent plenty to work with.
With 1,426 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so read-codex-history is actively maintained.
- Our last check on 2026-10-26 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
read-codex-history compared with similar skills
All 4 of these similar skills score higher than read-codex-history; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| read-codex-history (this skill)by daymade | 93 | 1.4k | 53d ago | SKILL.md |
| x402by browser-use | 100 | 121.0k | 3d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| pptxby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| designby nextlevelbuilder | 100 | 149.0k | 6d ago | SKILL.md |
Frequently asked questions
- How do I install read-codex-history?
- Run
npx skills add daymade/claude-code-skills --skill read-codex-history. The install tabs above show the steps for each supported agent. - Which AI agents does read-codex-history work with?
- It is written for Claude Code and OpenAI Codex, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is read-codex-history safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is read-codex-history still maintained?
- The repository was last updated about 2 months ago, so read-codex-history is actively maintained.
Skill content
View source on GitHubname: read-codex-history description: >- Reads, searches and exports local OpenAI Codex history without continuing work: session inventory, timelines, verbatim user input, indexed search, and rollout identity/fork lineage. Use when the user asks what they told Codex, wants a Session ID, or evidence of what a run did. Not for Claude Code (use read-claude-code-history); with no platform named, start at local-conversation-history. argument-hint: "[session-id | keywords | workspace-path]"
Read Codex History
Read Codex evidence only. Do not continue the old task or change its project. If
the user wants execution after the read is complete, pass the verified evidence
to daymade-claude-code:continue-codex-work.
Codex has three different history surfaces
| Surface | Authority | Use |
|---|---|---|
| <codex-home>/history.jsonl | What the user submitted, keyed by Session ID and internal epoch timestamp | Exact recent user-input tables |
| state_*.sqlite | Inventory metadata such as cwd, title, update time, and rollout path | Fast listing and candidate discovery |
| sessions/**/rollout-*.jsonl and archived_sessions/** | Full user/assistant/tool/compaction/fork event stream | Exact-session evidence and keyword verification after indexed or physical preselection |
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. A rollout can exist without a prompt-ledger
row, and a /fork prompt can exist without a child rollout.
Read references/storage_and_portability.md for source discovery, timestamps, writer-lock semantics, legacy Kimi compatibility, and storage failures. Read references/codex_rollout_format.md before interpreting fork snapshots, compaction, event streams, or end reasons.
Route by the requested result
| User wants | Use |
|---|---|
| Recent Codex sessions, titles, IDs, or positive writer-lock evidence | scripts/list_local_history.py --source codex --index-only; an unavailable index leaves inventory unknown |
| Find the Session containing a pasted quote, with a known project, date, or title clue | Locate a quoted exchange below: inventory candidates, then verify the original messages |
| Exact recent user inputs from newest to oldest, grouped by Session | scripts/list_codex_user_inputs.py |
| Whole-conversation original-input counts and quotations, including inherited history | scripts/reconcile_codex_inputs.py --session <ID> |
| Locate one exact rollout by internal identity | scripts/analyze_sessions.py locate-codex <ID> |
| Reconstruct one Session and its declared parent snapshots | scripts/read_codex_session.py --session <ID> |
| Verify a tool return, a comment ID, or external messages already read in a known Session | The Original tool and record evidence command below; briefing previews are not complete tool evidence |
| Find a rollout containing a topic or phrase | read-claude-code-history/scripts/history_index.py recall --provider codex, then verify the exact rollout |
| Content remembered but whose wording drifted | The same indexed recall in hybrid mode, if vectors are complete |
| Continue after evidence is complete | Stop reading and invoke daymade-claude-code:continue-codex-work |
The requested output wins over the motivation. “Show my recent original inputs” means a chronological raw-input table, not feedback classification, topic mining, an interactive app, or all historical sessions.
For “how many messages/feedback did I give in this conversation; list them
verbatim,” read references/user_input_reconciliation.md.
Use the reconciler to compose the existing ledger and strict lineage readers.
It preserves occurrences, original strings, and source coordinates. Treat exit 2
or complete: false as an incomplete result: scope_input_count: null is not
zero, and verified inputs are not a complete total. Review unmatched records
against their actual source before supplying any hash-bound injection exclusion.
State the counting unit and cutoff; do not call message counts a count of
distinct criticisms. Keep ordinary recent-input requests on the ledger-only route.
Commands
Resolve scripts relative to this SKILL.md. Do not rebuild the join with ad-hoc
SQLite, Node, jq, or recursive grep.
Recent inventory
<skill-dir>/scripts/list_local_history.py \
--source codex --index-only --cwd <workspace> --limit 20 --language zh
Writer-lock output is positive-only: a held lock proves that exact advisory lock was held during the snapshot. It does not identify the process or prove liveness; an unmarked row does not prove the Session stopped.
Locate a quoted exchange
For “which Session was this?” with a project, date, or title clue, use the existing inventory first. Select the strongest candidate by title and scope; a title match is only a lead. Do not begin with a full-corpus scan or a cross-provider index when these clues already bound discovery.
<skill-dir>/scripts/list_local_history.py \
--source codex --index-only --cwd <workspace> --include-archived \
--from-date <YYYY-MM-DD> --to-date <YYYY-MM-DD> --limit 20
<skill-dir>/scripts/read_codex_session.py --session <CANDIDATE_ID> --full
Omit unknown date bounds; replace --cwd with --all-projects when the workspace
is unknown. A date describes when the quoted exchange happened, not when the
Session was created. Inventory checks the created/updated interval for overlap,
so an older Session resumed that day remains a candidate. Never restrict rollout
directories to that day's creation folder. An asset's date is not a message date.
Exclude the current Session from candidate selection. Require the reader's
verified identity and the quoted text in the original speaker's timeline entry
(for a pasted assistant reply, ASSISTANT with a record coordinate). A user
quoting that reply, a tool result, or a compacted summary alone does not prove
where it was originally said. For a large briefing, use the private-file path
below and inspect the matching entry with its role and record heading; a Session
lookup does not require reading unrelated history or continuing the old task.
Stop once the quote and identity are verified; return the ID and source coordinate. If a candidate misses, try the remaining plausible candidates. A truncated listing, missing timestamps, an unavailable inventory, or no matching candidate is not absence: refine indexed recall and state its coverage. Do not fall back to raw corpus search.
Exact original inputs
# Global recent window, then group by Session
<skill-dir>/scripts/list_codex_user_inputs.py --recent 200 --language zh
# Expand exact Sessions already shown, preserving their order
<skill-dir>/scripts/list_codex_user_inputs.py \
--session-id <ID-1> --session-id <ID-2> \
--per-session 100 --language zh
Markdown is the human surface; JSON preserves the stored string value for forensic or machine use. Preserve duplicates, line order, timestamps, wording, and Session boundaries. Do not invent titles or split one Session into semantic categories.
Reconciled whole-conversation inputs
<skill-dir>/scripts/reconcile_codex_inputs.py --session <EXACT_ID> --format json
Use --through-record for an explicit inclusive cutoff in the selected session,
and --omit-first / --omit-last only for exclusions the user actually requested.
Neither option decides whether a message is an opening instruction or feedback.
Use --format markdown for literal numbered quotations after resolving gaps.
Read the linked reconciliation reference for result fields, reviewed exclusions,
partial results, and deterministic fixture-only validation.
Exact Session evidence and lineage
<skill-dir>/scripts/read_codex_session.py --session <SESSION_ID> --full
Expected output: # Codex Session Evidence Briefing, verified selected identity,
root-to-child fork lineage, exact parent byte boundaries, chronological handoff,
compacted context, latest plan, tool calls, files, errors, end reason, and workspace
state. If the state DB points to a rollout with the wrong identity, the reader must
reject it and try the exact session_meta.id locator; never continue from the wrong
file because its title or filename looked close. When live and archived copies share
an ID, the reader accepts byte-identical copies or a strict append-only superset and
otherwise fails as ambiguous. Every selected and inherited JSONL record is parsed
strictly; malformed lines cannot become a complete-looking receipt.
If the complete briefing is too large for one model context, materialize it once to a private temporary file and record its SHA-256 plus line count before reading. That one immutable file is still the single briefing; “one briefing” does not mean one stdout payload or one monolithic context load. Read bounded, non-overlapping ranges using its existing headings or exact record coordinates, keep coverage against the recorded line count, and report every unread range as a gap. Do not rerun the reader with different truncation and fuse the outputs into a complete-looking chronology.
Original tool and record evidence
After selecting a Session by identity or indexed recall, read stored tool results with the bundled reader rather than writing another JSONL parser:
<skill-dir>/scripts/read_codex_session.py --session <ID> --tools --contains '<literal clue>' --format json
<skill-dir>/scripts/read_codex_session.py --session <ID> --record <ORDINAL> --format json
Repeat --record for several 1-based nonblank-record ordinals. --tools selects
tool calls and returns; --contains is a literal substring filter within that
selected rollout. Combining the selectors intersects them. This mode preserves
the original stored record, including every output string and field, with no
content redaction or preview truncation. paired_call locates the preceding call
for a result; inspect both coordinates before attributing an external message.
It does not expand ancestry; inherited records must be read from the identified
parent when necessary. Role labels do not establish human authorship.
Expected output reports identity, records_examined, matched_records, source
coordinates, and truncated: false. Missing requested ordinals fail visibly.
Zero matches apply only to this selected rollout. --full still governs prose
briefing clipping; it does not turn a briefing into complete tool evidence.
Indexed content search
The index returns candidates from stored prose. Read the exact rollout to check tool outputs, thinking, compaction, and the speaker of a quoted line.
<read-claude-code-history-dir>/scripts/history_index.py status
<read-claude-code-history-dir>/scripts/history_index.py recall '<keyword>' \
--mode bm25 --provider codex --exclude-session <CURRENT_ID>
Start with an exact ID, known date, or indexed content lead. Verify candidate
rollouts by their session_meta.id. A timeout and the old --from-date filter
do not prevent the raw command from reading every rollout; that command now
rejects live sources.
Alternative indexed full-text lookup
The separate ~/.claude-flow-viewer/search.sqlite FTS index can also locate
candidate sessions. Check its provider coverage and freshness before using it,
then verify each hit with the exact-session reader. A hit is a lead, not evidence.
sqlite3 ~/.claude-flow-viewer/search.sqlite "
SELECT s.source, s.session_id, s.project_encoded, substr(c.text, 1, 600)
FROM search_chunks_fts fts
JOIN search_chunks c ON c.rowid = fts.rowid
JOIN indexed_sessions s ON s.session_id = c.session_id
AND s.source = c.source AND s.project_encoded = c.project_encoded
WHERE f
Truncated for display — read the full file on GitHub.
Related Skills
x402
121.0kSet up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
pptx
177.9kUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an em…
design
149.0kComprehensive design skill: brand identity, design tokens, UI styling, logo generation (55 styles, Gemini, Atlas Cloud, or MuAPI AI), corporate identity program (50 deliverables, CIP mockups), HTML presentations (Chart.js), banner design (22 styles, social/ads/web/print), icon design (15 styles, SVG…
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
