For Claude Code and Codex
Any Session
Takes One Command
Search, recover, and account for every Claude Code and Codex session you’ve ever run, straight from the command line.
Compact wipes your context. Your day disappears into forty sessions you can’t tell apart.
The external problem
/compact rolls your conversation away mid-task. The work from three hours ago is gone unless you know exactly which of forty session files it’s buried in.
The internal problem
You end up scrolling through session lists half-remembering what you said, unsure if you’re about to redo work you already finished.
What's at stake
Time spent re-deriving decisions you already made once, and a day you can’t account for when someone asks where the hours went.
Four entry points: recover, search, account, or build your own.
Run the CLI mode that fits, or drop one level down when none does: mode first, then JSON post-processing, then the library itself.
Recover Context
Pull the 40 exchanges before your last /compact, or read the last message before a crash, so you’re not starting from a blank page.
Search Across Sessions
Find a session by keyword, title, or first prompt across every project and both agents, with a bounded per-session summary so a wide search doesn’t blow your context window.
Account for Your Time
See where your day actually went: a merged Claude and Codex timeline with idle gaps, or a real active-time number that never double-counts a parallel chat.
Build a Custom Query
When no mode fits, write a scratch script on the Python library underneath the CLI. It already handles the UTC timestamp and double-count traps for you.
Reference library: What the CLI actually knows about your transcripts.
Every mode traces back to the real Claude Code and Codex .jsonl schemas, the traps each one hides (UTC timestamps, tool-result envelopes, Codex’s mirrored event and response layers), and workflows worked out against real sessions on this machine.
Supporting reference files follow the practical guide. Archived source material and author workflow notes are not a current policy certification.
01 Mode ReferenceEvery CLI mode, its flags, and JSON shape, so you pick a command instead of guessing.
Reference
Mode Reference
CLI grammar
python read_transcript.py [--root <root>] [--cwd <path> | --all-projects | --project <name> | --file <path>]
[--since <spec>] [--until <spec>] [--tz <spec>] [--agent claude|codex|both]
--mode <mode> [mode-specific flags]
[--format json] [--exclude-current] [--include-subagents] [-n N]
[--force-dump]Global flag notes:
--since <spec>/--until <spec>— the time window is half-open[since, until):sinceis inclusive,untilis exclusive, so an event stamped exactly at--untilis not included. This holds for every message-level mode (search,timeline,engagement,session-report,tool-usage). Session-level modes (list,journal,count) instead filter whole sessions by file mtime, so a session last written at or before--untilis shown.--project <name>— case-insensitive substring filter on project directory names (encoded or decoded form). Applies tolist,journal,search,count,find,timeline,engagement,session-report,tool-usage. Exit 1 when nothing matches.--tz <spec>— display timezone: IANA name (America/New_York),UTC, or fixed offset (+5,-4,+05:30,UTC-4). Default is system local time. All displayed timestamps AND--since/--until/--dateinterpretation use this zone.--agent {claude,codex,both}— which agent's history the cross-session modes read. Defaultboth. Applies tolist,journal,timeline,engagement,session-report,count,tool-usage,lookup,find, andsearch. Codex sessions live at~/.codex/sessions(seecodex-history.md); they are folded into the SAME merged stream as Claude for timeline/engagement/session-report, so parallel Claude/Codex chats split the clock rather than double-count.--agentis ignored by Claude-only modes (whoami,resume-cmd,subagent-*) and by single---filemodes (a Codex rollout passed via--fileis auto-detected). JSON output tags every session withsource: "claude"|"codex"; text output prefixes Codex sessions withcodex ▹. Codex discovery is enabled only against the live--root(or whenESTACK_CODEX_SESSIONS_DIRis set) — backups/custom roots have no Codex tree.- Clock format: the report modes (
session-report,engagement,timeline) render every time-of-day as 12-hour with the 24-hour value in parens —7:00pm (19:00)— and date-prefix it (2026-06-19 7:00pm (19:00)) when the window spans more than one day; their headers carry a12h (24h)label. Forensic modes (changelog,tool-calls) keepHH:MM:SSfor density. JSON output is always ISO-8601 (unaffected by the 12-hour rendering). --format json— structured output on every mode. Shapes per mode are listed below.
Single-session modes
last
Last N messages with text, filtered by role.
python read_transcript.py --file <path> --mode last [-n 5] [--role user|assistant|both]
- Default N = 5; default role =
assistant(backwards-compatible). --role useranswers "what was the last thing *I* said" — real typed prompts only: compact continuations and hook/skillisMetainjections are excluded.--role bothinterleaves.- With
--include-subagents, appends each subagent's final assistant message tagged[subagent <id-short> · <agentType>](text output only — onlast/dumpthe JSON shape omits subagents; usebrief --format json --include-subagentsorsubagent-finalsfor structured subagent output). - JSON shape includes a
rolefield per message.
advisor
All advisor responses (the contents of every advisor_tool_result block).
python read_transcript.py --file <path> --mode advisor
pre-compact
40 message-exchanges before the most recent /compact.
python read_transcript.py --file <path> --mode pre-compact
If no /compact marker is present, falls back to mode_last(10) with a note.
dump
Human-readable conversation dump (last 80 messages by default; -n overrides).
python read_transcript.py --file <path> --mode dump [-n N] [--include-subagents] [--force-dump]
Size-aware fallback: transcripts larger than 5 MB auto-degrade to pre-compact (or last if no compact marker), with a stderr note. Override with --force-dump.
debug
Structural diagnostic — prints entry type distribution, content block types, advisor probe, compact-marker probe, and sample signal entries. Use this first when a mode returns empty/unexpected results.
python read_transcript.py --file <path> --mode debug
brief
6-line single-session summary. Designed for fan-out triage: 14 parallel brief calls reproduce a 14-subagent investigation deterministically.
python read_transcript.py --file <path> --mode brief [--include-subagents]
Output format:
<uuid> · <decoded-project> · <mtime> · <status> [*]<if current> intent: <first user prompt, 200ch> last: <last assistant text, 200ch> edits: <N> files — <top-3 paths> tools: Bash=X Edit=Y Read=Z … subagents: <N> spawned [<agentType counts>]
With --include-subagents, appends each subagent's final assistant message.
changelog
HH:MM:SS TOOL one-line-summary, day-grouped.
python read_transcript.py --file <path> --mode changelog
file-edits
Unique file paths touched, sorted alphabetically. Multiple operations on the same file get a count suffix.
python read_transcript.py --file <path> --mode file-edits
tool-calls
Timestamped per-call blocks, with formatted args.
python read_transcript.py --file <path> --mode tool-calls [--tool Bash,Edit]
--tool filters to a comma-separated subset.
Discovery modes
list
Enriched session table.
# Single project python read_transcript.py --cwd <path> --mode list [--since 7d] [--exclude-current] # All projects python read_transcript.py --all-projects --mode list [--since today]
Columns: marker ([*] if current), mtime, size, uuid-short, msg count, flags ([C]=compact, [S]=subagents), status (✓!?●), decoded project name (when multi-project), title.
whoami
Resolve the CURRENT live session (via the CLAUDE_CODE_SESSION_ID env var — the real OS variable Claude Code sets in a live session's process environment, checked first; CLAUDE_SESSION_ID is checked second as a compatibility fallback) to its absolute .jsonl path — no listing, no eyeballing timestamps.
python read_transcript.py --mode whoami [--cwd <path>]
--cwdscopes the lookup to one project first (fast path); if that misses (wrong or nonexistent project dir) or is omitted, it scans every project under--rootuntil the UUID matches — never fails just because--cwddidn't resolve.- Exit 0: prints
<uuid>/<path>/project: <name>(three lines), or the JSON equivalent with--format json. - Exit 1: neither env var is set (not running inside a live session), or one is set but no matching file was found under
--root. - SKILL.md's
${CLAUDE_SESSION_ID}template variable already gives you the raw UUID for free when this skill's Markdown is loaded — that's a *different* mechanism (a text substitution the harness performs on SKILL.md itself, never a real env var). Reach forwhoamiwhen you need the actual file *path* (or a JSON-shaped result), or when resolving from a context (e.g. a subagent) where that substitution isn't visible.
lookup
Resolve a UUID prefix to an absolute path.
python read_transcript.py --mode lookup --uuid <prefix>
- Exit 0: prints absolute path.
- Exit 1: no match.
- Exit 2: ambiguous prefix — prints all matches.
find
Search session metadata by title or first prompt.
python read_transcript.py --mode find --title "supabase" python read_transcript.py --mode find --first-prompt "fix the bug"
resume-cmd
Generate a cd <cwd>; claude --resume <uuid> snippet for a UUID prefix.
python read_transcript.py --mode resume-cmd --uuid <prefix>
The original CWD cannot be unambiguously recovered from the encoded directory name; the snippet includes a <original cwd> placeholder plus the decoded display name as a hint.
Search modes
search
Cross-scope search with role + channel filters.
# Single file python read_transcript.py --file <path> --mode search --query "<q>" # Whole project python read_transcript.py --cwd <path> --mode search --query "<q>" # All projects python read_transcript.py --all-projects --mode search --query "<q>" # Expand a wide search to full match windows python read_transcript.py --all-projects --mode search --query "<q>" --full
Flags:
--role {user,assistant,both}(defaultboth)--in {text,tool_use,tool_result,thinking,all}(defaulttext)--full— wide scope only (see Output below)--since/--until
--in tool_use searches the name + JSON-stringified input of every tool_use block — useful for finding "the session where I ran git push --force".
--in thinking searches thinking blocks (model reasoning).
--in tool_result searches the text content of tool_result blocks (what tools returned). --in all covers text + tool_use + tool_result + thinking.
Output. A single-file search (--file) prints full match windows. A wide search (--cwd / --project / --all-projects) prints a per-session summary by default — one line per session (mtime · uuid8 · project · hit-count · first snippet), sorted newest first, with a header counting total hits and sessions. This keeps cross-project searches well under the harness's ~25k-token Read cap instead of dumping tens of thousands of tokens that the reader then refuses. Add --full to expand a wide search into full windows. In every case the full view (single-file, or wide + --full) is bounded by a character budget (~10k tokens) and degrades back to the summary with a note if it would overflow — so even a single huge session can't blow the Read cap. Sessions past the 200-line summary cap are counted in a footer, never silently dropped. JSON mirrors this: wide scope returns compact per-session metadata (uuid, project, hits, first_snippet) by default, full per-match objects (with window) under --full.
Progress (Searching i/N…) prints to stderr only when stderr is an interactive terminal — captured/piped runs stay clean.
count
Count sessions matching a query.
python read_transcript.py --mode count --query "<q>" [--all-projects] [--since 30d]
stdout: integer session count.
stderr: <N> sessions, <M> total messages, <K> matches.
Subagent modes
subagent-list
List sibling subagents for a parent session.
python read_transcript.py --file <parent> --mode subagent-list
Output: mtime size agent-id type=<agentType> "<description>".
subagent-finals
Every subagent's final assistant message, separated by === agent-<id> (<type>) === headers.
python read_transcript.py --file <parent> --mode subagent-finals
subagent-tools
Tool-call forensics on a single subagent (same output shape as tool-calls).
python read_transcript.py --mode subagent-tools --subagent <subagent-path>
subagent-files
Files touched by a single subagent (same output shape as file-edits).
python read_transcript.py --mode subagent-files --subagent <subagent-path>
Resume modes
resume-prev
Banner + dump-style tail of the last 10 exchanges from the most-recent prior session in a project.
python read_transcript.py --cwd <path> --mode resume-prev [-n 10]
Aggregation modes
journal
Per-session 5-line block: date·uuid·project / prompt / ended / edits / tools.
python read_transcript.py --mode journal --since 7d [--cwd <path> | --all-projects | --project <name>]
JSON shape: array of session-summary objects (same fields as list).
timeline
Block-grouped activity timeline across all sessions in a time window, with idle
gaps. Answers "what was I doing, when?". It is a *map* of session activity —
Claude's work included — and makes no claim about attention time; for "how much
time did this consume?" use engagement. Defaults to all projects and today.
# Yesterday, everything python read_transcript.py --mode timeline --date yesterday # One project, today, stricter idle threshold python read_transcript.py --mode timeline --project keel --date today --gap 5m # Arbitrary window python read_transcript.py --mode timeline --since 2026-06-01 --until 2026-06-03
How it works: every signal-message timestamp in the window is an activity event;
events across all sessions are merged chronologically and grouped into blocks
separated by gaps longer than --gap (default 15m). Each block lists the sessions
active in it with message counts; idle gaps are printed between blocks; a totals
line gives block count, span, and session count.
Flags:
--date <spec>— single-day window (midnight to midnight). Wins over--since/--until.--since/--until— arbitrary window (until defaults to now).--gap <spec>— idle threshold:15m,20,1h.--cwd/--project/--all-projects— scope (default: all projects).--tz— display timezone (timestamps render in it; the window is interpreted in it).
JSON shape: `{since, until, gap_minutes, blocks: [{start, end, duration_minutes,
sessions: [{uuid, project, title, path, events}]}], totals: {blocks,
span_minutes, sessions}}`.
engagement
Attention-time accounting: how much focused time a window, project, or session
actually consumed — *your* time, not Claude's. Answers "how long did X actually
take me?". Defaults to all projects and today; with --file and no time flags,
the window is the session's own first→last prompt.
# Today's real work time, everything python read_transcript.py --mode engagement --date today # One project over a week python read_transcript.py --mode engagement --project keel --since 7d # One session, strict 5-minute break threshold python read_transcript.py --mode engagement --file <session.jsonl> --break 5m
How it works — three deterministic rules over ONE merged stream:
- Real user prompts (typed messages and slash commands — not tool results,
hook/skill injections, or compact continuations) from EVERY project are
merged into a single chronological stream. A gap between consecutive prompts
≤ --break (default 10m) counts fully as active time, attributed to the
session of the *later* prompt — the chat being read/typed in. One stream
means a moment of wall clock is never counted twice across parallel chats.
- A longer gap still counts in full if Claude was working in that session
during the gap and the user replied within --break of Claude's last event
(sitting-there-waiting credit). Long runs you walked away from get nothing.
- Everything else is a break and contributes zero. A session left open with no
prompts accrues nothing.
Output: one row per session (active, ratio = active/elapsed, you/ai message
counts, first–last), a totals line (already interval-merged — safe to quote),
breaks in the merged stream, and (single-session view) median/p90 prompt gaps.
Ratio is capped at 1.0: composing time leading into a chat's first prompt is
credited to that chat, so raw active can slightly exceed its first–last span.
Message counts are honest, not raw entry counts: you (user_messages) is real
typed prompts only — tool-result envelopes, hook/skill isMeta injections, and
compact continuations are excluded; ai (assistant_messages) is assistant
turns bearing visible text — tool-only turns don't count. Both are windowed to
[since, until).
Scoping caveat: --project/--cwd/--file filter which sessions are
*reported*; the stream is always computed across all projects under --root so
parallel-chat math stays correct. A scoped total can be less than the global
total for the same window.
Flags:
--break <spec>— break threshold:5m,20m,1h(default 10m).--date/--since/--until— window (same semantics as timeline).--cwd/--project/--all-projects/--file— reporting scope.--tz— display timezone.--exclude-current— drop the current session from stream and report.
JSON shape: `{since, until, break_minutes, sessions: [{uuid, project, title,
path, first, last, elapsed_minutes, active_minutes, active_seconds, ratio,
user_messages, assistant_messages}], totals: {sessions, active_minutes,
active_seconds, span_minutes}, stream_breaks: [{start, end, minutes}]}`.
session-report
The per-session "what did I do" day review. Same windowed, overlap-safe
attention engine as engagement, but rendered as one numbered block per
session, chronological (oldest first by first prompt), carrying everything a
human review needs in a single call — so a "break down my day" answer doesn't
require stitching timeline + lookup + engagement + raw message counts by
hand.
# Yesterday, every project python read_transcript.py --mode session-report --date yesterday # Just the evening — omit --date so --since/--until take effect python read_transcript.py --mode session-report --since "2026-06-19 19:00" --until "2026-06-20 00:00" # One project python read_transcript.py --mode session-report --project keel --date today
Each block shows: title, project, first–last span with both clocks —
ran (the session's own first→last elapsed, which can overlap other sessions)
and active (deduped attention, parallel chats never double-counted) — then
you/assistant message counts (same honest definitions as engagement),
files edited, the intent (first prompt) and last (final assistant message).
The intent/last are raw inputs for you to synthesize a one-sentence description
from, not the description itself. A totals line closes with deduped active time
and the overlap-inclusive span.
Flags: same as engagement (--break, --date/--since/--until,
--cwd/--project/--all-projects, --tz, --exclude-current). As with
engagement, --date takes precedence over --since/--until; to scope to a
sub-window of a day, pass --since/--until and omit --date.
JSON shape: `{since, until, break_minutes, sessions: [{uuid, project, title,
path, first, last, elapsed_minutes, active_minutes, user_messages,
assistant_messages, edits, intent, last_message}], totals: {sessions,
active_minutes, span_minutes}}`. Sessions are ordered chronologically.
Presentation defaults for a human day-review
When the user asks a natural-language "what did I do" / "review my day" question, lead with session-report and present it this way unless told otherwise:
- Number the sessions into clear blocks; drop UUIDs (noise in a human review — surface them only for resume/lookup).
- One to two sentences per session, synthesized from
intent+last+ files — not a raw dump of either. - Show both clocks and name the overlap once:
activeis deduped attention (parallel chats never double-counted);ran/elapsed is the session's own span and *will* overlap others. - Trust the mode's counts — never hand-count raw
type:user/type:assistantentries (tool-result envelopes inflate "user"; multi-block turns inflate "assistant"). - 12-hour time as the report modes emit it (
7:00pm (19:00)); switch to 24-hour only on request. - Sub-window of a day: pass
--since/--untiland omit--date(--datewins).
For a normal day (16–20 sessions) session-report text output stays well within the read budget; prefer it over --mode list --format json.
tool-usage
Tally tool calls by tool name; Skill calls are sub-tallied by skill name. Answers "which tools / skills do I actually use".
# Every tool across one session python read_transcript.py --file <path> --mode tool-usage # Skill usage across every project (the "what skills do I actually use" question) python read_transcript.py --all-projects --mode tool-usage --tool Skill # One project, last 30 days python read_transcript.py --project keel --mode tool-usage --since 30d
Scope is --file (one session) or --cwd / --project / --all-projects. --tool narrows to a comma-separated subset (e.g. --tool Skill for a skills-only view, --tool Bash,Edit). --since/--until bound the calls by their own timestamp (not file mtime — a session modified after --until is still read so in-window calls are counted). --exclude-current drops the current session so the commands you're running now don't skew the count. --include-subagents folds each session's agent-*.jsonl tool calls into its tally — needed to capture skills invoked inside fan-out subagents (the subagent is not counted as a separate session).
Why this exists: it counts real invocations — a tool_use block whose name is the tool (and, for skills, input.skill). Text-based modes like search --in tool_use and count match the *string* "ast-grep" wherever it appears (a CLAUDE.md instruction, a bash command, even your own search commands this session), so they over-count. tool-usage keys on structure and is immune to that.
Text output: one <count> <ToolName> row per tool, sorted by count descending; under the Skill row, a tree of <count> <skill-name> sub-rows. A leading line gives the grand total and number of sessions with calls.
Tool calls (66 total across 43 session(s)):
66 Skill
├ 38 manage-e-stack
├ 9 commit
└ ...JSON shape: {total, sessions, tools: [{tool, count}], skills: [{skill, count}]} (both lists sorted by count descending; skills is empty unless Skill calls were counted).
Comparison modes
diff
Timestamp-interleaved comparison of two sessions.
python read_transcript.py --mode diff --file-a <s1> --file-b <s2>
For sibling-subagent comparison (when a fan-out spawned multiple agents with similar tasks):
python read_transcript.py --mode diff --subagents-of <parent>
Output is prefixed A> / B> (or with subagent id shorts).
JSON shapes per mode (`--format json`)
| Mode | Shape |
|---|---|
last | [{n_from_end, role, timestamp, text}] |
advisor | [<advisor text>, …] |
pre-compact | {found_compact, messages: [{role, timestamp, is_compact, text}]} |
dump | [{role, timestamp, is_compact, text}] |
debug | {entry_types, block_types, advisor_blocks, compact_markers} |
brief | session-summary object (+ subagent_finals with --include-subagents) |
list / journal / find | array of session-summary objects |
lookup | {prefix, path, matches} (same exit codes as text) |
resume-cmd | {uuid, path, project, encoded, command} |
changelog | [{timestamp, tool, summary}] |
tool-calls / subagent-tools | [{timestamp, tool, summary, input}] |
tool-usage | {total, sessions, tools: [{tool, count}], skills: [{skill, count}]} |
file-edits / subagent-files | [{path, ops}] |
search | single-file or --full: [{session, mtime_iso, role, where, timestamp, window}]; wide scope default: [{session, uuid, project, mtime_iso, hits, first_snippet}] |
count | {sessions, messages, matches} |
subagent-list | [{id, agentType, description, path, size_kb, mtime_iso}] |
subagent-finals | [{id, agentType, text}] |
resume-prev | {session, path, mtime_iso, messages} |
diff | {a, b, messages: [{source, role, timestamp, text}]} |
timeline | see the timeline section above |
engagement | see the engagement section above |
session-report | see the session-report section above |
Session-summary object fields: `path, uuid, mtime, mtime_iso, size, exists, title,
first_prompt, last_assistant, last_activity, msg_count, edit_count, tool_counts,
files_touched, subagent_count, subagent_types, has_compact, has_subagents, cwd,
decoded_project, status, is_current`.
Exit codes
0: success1: missing required flag, no match (including--projectwith zero matches), or file not found2: ambiguous result (e.g. UUID prefix matches multiple sessions)
02 RecipesMulti-step workflows: compact recovery, fan-out triage, deletion recovery, day review.
Reference
Recipes
1. Post-`/compact` recovery
When /compact has rolled the conversation and you need what fell off the back end:
# Step 1: Recover the long version of recent assistant output python "$PY" --file <current-session.jsonl> --mode pre-compact # Step 2: If advisor responses were involved, grab those separately python "$PY" --file <current-session.jsonl> --mode advisor # Step 3: If a search would be faster than reading the whole pre-compact section python "$PY" --file <current-session.jsonl> --mode search --query "<keyword>"
The pre-compact window is 40 message-exchanges before the most recent compact. If multiple /compact events fired, only the most recent is used as the anchor.
2. Find-then-dump (resume work from a session you can't name)
# Step 1: Find by partial title or first prompt python "$PY" --mode find --title "supabase" # → returns a list, including the full session UUIDs # Step 2: Get a 6-line summary to confirm it's the right one python "$PY" --file <picked-session>.jsonl --mode brief # Step 3: Dump the recent context to ground yourself python "$PY" --file <picked-session>.jsonl --mode dump -n 20 # Step 4: Get the resume command for that session python "$PY" --mode resume-cmd --uuid <8-char-prefix>
3. Fan-out triage (you spawned N parallel subagents and want every output)
# Option A: Get all subagent finals in one shot, separated by headers python "$PY" --file <parent-session>.jsonl --mode subagent-finals # Option B: Triage with a brief that includes subagent finals folded in python "$PY" --file <parent-session>.jsonl --mode brief --include-subagents # Option C: List first to see what types of agents ran python "$PY" --file <parent-session>.jsonl --mode subagent-list # Drill into one specific subagent's tools / files python "$PY" --mode subagent-tools --subagent <subagent-path> python "$PY" --mode subagent-files --subagent <subagent-path>
The brief --include-subagents output is the densest form of the standard "what did all my agents do" question and was designed for fan-out reproduction (14 parallel briefs ≡ a 14-subagent investigation).
4. Deletion-incident recovery (March 2026 auto-update bug, GitHub #41591)
When a live .jsonl has been wiped but the backup is intact:
# Step 1: Find what's missing — list live vs snapshot side by side python "$PY" --root live --cwd "C:\Users\2supe\Other Claude Code" --mode list > live.txt python "$PY" --root snapshot-24h --cwd "C:\Users\2supe\Other Claude Code" --mode list > snap.txt diff live.txt snap.txt # Step 2: For each missing UUID, locate it in the snapshot python "$PY" --root snapshot-24h --mode lookup --uuid <prefix> # Step 3: Read it directly from the snapshot path python "$PY" --file <snapshot-path>.jsonl --mode brief python "$PY" --file <snapshot-path>.jsonl --mode dump # Step 4: If the 24h snapshot is also affected, walk back further python "$PY" --root snapshot-1w --mode lookup --uuid <prefix> python "$PY" --root snapshot-1mo --mode lookup --uuid <prefix>
The four backup roots (mirror, snapshot-24h, snapshot-1w, snapshot-1mo) are maintained by a scheduled backup task on this machine.
5. Week-in-review journal
# Every session in every project from the last 7 days python "$PY" --all-projects --mode journal --since 7d # Single project, with a hard upper bound python "$PY" --cwd "C:\Users\2supe\Other Claude Code" \ --mode journal --since 2026-05-13 --until 2026-05-20 # By project name instead of path python "$PY" --project keel --mode journal --since 7d # Count how many sessions touched a topic python "$PY" --all-projects --mode count --query "linkedin"
The output is one 5-line block per session: date·uuid·project / first prompt / last assistant message / N files edited / top tools.
5b. Day accounting ("where did my day go?")
# Block-grouped timeline of yesterday across ALL projects, with idle gaps python "$PY" --mode timeline --date yesterday # How much time on one project today python "$PY" --mode timeline --project keel --date today # Tighter idle threshold (treat >5m quiet as a break between blocks) python "$PY" --mode timeline --date today --gap 5m # Multi-day window python "$PY" --mode timeline --since 2026-06-01 --until 2026-06-03
Reading the output: each block is a contiguous stretch of activity (events ≤ gap
apart); the sessions inside it are listed with message counts; ── idle Xm ──
lines mark the breaks; the totals line gives block count, span, and session count.
Caveat: timeline maps *session* activity (Claude's work included) — it makes no
claim about your attention time. For "how long did this actually take ME?", use
--mode engagement (recipe 5d).
5d. Attention accounting ("how long did X actually take me?")
engagement measures *your* time, not the session's. The full attribution
rules (one merged stream, waiting-credit, breaks) are in modes.md § engagement.
# How much focused time did today actually consume? python "$PY" --mode engagement --date today # One project over a week python "$PY" --mode engagement --project keel --since 7d # One session, window auto-derived from its first→last prompt python "$PY" --mode engagement --file <session.jsonl> # Strict mode: anything over 5 minutes quiet is a break python "$PY" --mode engagement --date today --break 5m
Reading the output: one row per session (active / ratio / msgs / first–last),
a total line (already interval-merged, safe to quote), and the breaks in the
merged stream.
5c. Piping structured output into a next step
Every mode supports --format json. Run pipe chains in Bash (the Bash tool /
git-bash) — they work exactly as written:
# Pull the paths of yesterday's sessions for batch processing python "$PY" --mode list --all-projects --since yesterday --format json \ | python -c "import json,sys; [print(s['path']) for s in json.load(sys.stdin)]" # Machine-readable day totals (attention time → engagement, not timeline) python "$PY" --mode engagement --date yesterday --format json \ | python -c "import json,sys; t=json.load(sys.stdin)['totals']; print(t['active_minutes'], 'min across', t['sessions'], 'sessions')"
PowerShell warnings (5.1):
- Piping between native commands injects a UTF-8 BOM and re-encodes through the
console codepage (can corrupt non-ASCII transcript content). If you must pipe
in PowerShell, read stdin as utf-8-sig:
python -c "import io,json,sys; data=json.load(io.TextIOWrapper(sys.stdin.buffer, encoding='utf-8-sig'))"
>redirection writes UTF-16 — read redirected files withencoding='utf-16'.
Prefer Bash for any JSON chaining; prefer either shell for plain single commands.
5e. Cross-agent day review (Claude Code + Codex together)
The day-accounting modes read both agents by default (--agent both); see
modes.md § --agent for the merge semantics.
# Everything yesterday, both agents, one merged timeline python "$PY" --mode timeline --date yesterday # Real attention time across both agents python "$PY" --mode engagement --date yesterday # Numbered per-session day review (Codex rows tagged "codex ▹") python "$PY" --mode session-report --date yesterday # Narrow to one agent python "$PY" --mode session-report --date yesterday --agent codex python "$PY" --mode timeline --date yesterday --agent claude # Read a single Codex session directly (auto-detected — no --agent needed) ls ~/.codex/sessions/2026/07/15/ # the date folder IS the index python "$PY" --file ~/.codex/sessions/2026/07/15/rollout-*.jsonl --mode brief
Do NOT hand-roll the cross-agent active-time math with grep '"timestamp"' + awk —
you'd re-derive the merge with a hardcoded UTC→local offset and lose the dedup the
modes already do. Codex schema + traps: codex-history.md.
6. Sibling-agent diff
When you ran two subagents on the same task and want to see where they diverged:
# Auto-pick the first two subagents of a session python "$PY" --mode diff --subagents-of <parent-session>.jsonl # Explicit pairing python "$PY" --mode diff \ --file-a <parent-uuid>/subagents/agent-aaa.jsonl \ --file-b <parent-uuid>/subagents/agent-bbb.jsonl
Output is timestamp-interleaved, prefixed A> / B>. Use it to spot disagreement (e.g. one agent recommended X and the other recommended Y) without reading both transcripts in full.
7. "What is this session actually for?" (cold open on a stale UUID)
# Single-shot orientation in under a second python "$PY" --file <unknown-session>.jsonl --mode brief # If you need more than 200 chars of context per line python "$PY" --file <unknown-session>.jsonl --mode last -n 3 python "$PY" --file <unknown-session>.jsonl --mode changelog | tail -30
brief is the recommended default for triaging a session you've never read.
8. Tool-call forensics ("when did I last `git push --force`?")
# Find which sessions contain a matching tool_use, across all projects # (returns a per-session summary by default: one line per session with hit count + snippet) python "$PY" --all-projects --mode search --query "git push --force" --in tool_use # Add --full to expand to match windows instead of the per-session summary python "$PY" --all-projects --mode search --query "git push --force" --in tool_use --full # Get full forensics on the session that matched python "$PY" --file <matching-session>.jsonl --mode tool-calls --tool Bash
Wide-scope search (--all-projects, --cwd, --project) returns a per-session summary by default — one line per matching session with a hit count and first snippet — so the output stays under the harness's Read cap. Add --full to expand to match windows (bounded by a ~10k-token budget; degrades back to summary with a note if it overflows). Single-file search (--file) always returns full windows.
8b. "Which skills (or tools) do I actually use?" — true invocation counts
To decide which skills to keep or prune, you need real usage counts. Use
tool-usage, never search/count — the why (string matches over-count;
tool-usage keys on invocation structure) is in modes.md § tool-usage.
# Skills you actually invoked, ranked, across every project python "$PY" --all-projects --mode tool-usage --tool Skill # All tools (skills broken out under the Skill row) python "$PY" --all-projects --mode tool-usage # One project, last 30 days, excluding this very session python "$PY" --project keel --mode tool-usage --tool Skill --since 30d --exclude-current # Machine-readable: skills sorted by count python "$PY" --all-projects --mode tool-usage --tool Skill --format json \ | python -c "import json,sys; [print(s['count'], s['skill']) for s in json.load(sys.stdin)['skills']]"
A skill missing from the output was never invoked in that scope — a positive
inventory ("here is everything I used, and X isn't in it") is stronger evidence
of non-use than a search that simply returns nothing.
9. Resume previous session in the current project
If you just cd'd into a project and want to pick up where you left off:
python "$PY" --cwd "$(pwd)" --mode resume-prev -n 15
Prints --- Resuming from <uuid> (<mtime>) --- then the last 15 exchanges.
10. Schema drift / silent empty results
When a mode returns nothing and you don't know why:
python "$PY" --file <session>.jsonl --mode debug
Look for:
- Unfamiliar
type:values appearing in the distribution (parser might be dropping them as noise). - An absent
advisor_tool_resultblock when you expected advisor output. - Missing
compactmarkers in a session you know got compacted.
If the drift is real (a new entry type, a changed block shape), document it in jsonl-schema.md at the source repo and adjust lib/parser.py — see SKILL.md § "Update this skill with what you learn".
11. When no recipe fits: the scratch-script pattern
Most real questions don't map to a canned mode ("which sessions edited files under src/ but never ran tests?", "average time between my prompt and Claude's first reply, per project"). Don't approximate them with CLI flags — write the exact query:
# <scratchpad>/query.py
import sys
from pathlib import Path
sys.path.insert(0, str(Path.home() / ".claude/skills/estack-read-agent-history/scripts"))
from lib import parser, paths, search, subagents, tools, codex
since = paths.parse_timespec("7d")
for pd in paths.list_projects(): # or filter_projects(None, "keel")
for f in paths.list_transcripts(pd, since=since):
lines = parser.parse_lines(f) # cached — cheap to re-call
# …exactly the question being asked…Rules of the pattern:
- Script lives in the scratchpad, never the user's project.
- Use the lib for classification, timestamps, and discovery (its docstrings explain the traps each function handles); write only the question-specific logic yourself.
- Print a bounded, per-session summary first; expand details selectively — a raw dump of a cross-project sweep blows the output cap.
- If the script's technique is reusable, promote it into these recipes at the source repo; if the same gap keeps recurring, add a small mode or flag to the CLI instead.
03 Claude SchemaWhat’s actually inside a Claude Code .jsonl: entry types, blocks, timestamps, status.
Reference
Claude Schema
File location
C:\Users\<user>\.claude\projects\<encoded-cwd>\<session-uuid>.jsonl
The <encoded-cwd> is the original working directory with every :, \, /, and whitespace character replaced by -. Examples on this machine:
| Original CWD | Encoded directory |
|---|---|
C:\Users\2supe\Other Claude Code | C--Users-2supe-Other-Claude-Code |
C:\Users\2supe\Other Claude Code\Personal Brand Project | C--Users-2supe-Other-Claude-Code-Personal-Brand-Project |
C:\Users\2supe\AppData\Local\Temp | C--Users-2supe-AppData-Local-Temp |
The encoding is lossy — single hyphens in the original path collapse into the same hyphens that separate segments. Use --mode lookup / --mode find to recover the actual session path; decode_project_name() produces a display-only approximation.
Backup roots
The same encoded-directory layout exists under each .claude-backups\<name>\projects\ root:
C:\Users\2supe\.claude-backups\ ├── mirror\projects\<encoded-cwd>\<uuid>.jsonl ├── snapshot-24h\projects\<encoded-cwd>\<uuid>.jsonl ├── snapshot-1w\projects\<encoded-cwd>\<uuid>.jsonl └── snapshot-1mo\projects\<encoded-cwd>\<uuid>.jsonl
--root mirror|snapshot-24h|snapshot-1w|snapshot-1mo rebases all path resolution to that snapshot. An absolute path argument is also accepted.
Subagent transcripts
When a session spawns subagents (via the Agent / Task tool), each subagent's own transcript is written to:
<project-dir>\<session-uuid>\subagents\agent-<id>.jsonl
A sidecar metadata file lives next to it:
<project-dir>\<session-uuid>\subagents\agent-<id>.meta.json
The meta file contains:
{
"agentType": "Explore",
"description": "Find every reference to X"
}When the meta file is missing, subagents.load_meta returns {"agentType": "unknown", "description": ""}.
Subagent entries inside the parent transcript are marked with isSidechain: true and carry an agentId field.
Entry types
Each line in a .jsonl is a JSON object with a type field. Entry classifications:
type value | Classification | Notes |
|---|---|---|
user | signal (user) | message.content may be string or array. Compact markers live here. |
assistant | signal (assistant) | message.content is always an array of blocks. |
ai-title / custom-title | title | aiTitle / customTitle field carries the session title. |
permission-mode | noise | mode change events |
attachment | noise | file attachments |
last-prompt | noise | cached last prompt |
queue-operation | noise | internal queueing |
file-history-snapshot | noise | file state snapshots |
system | noise | system events |
agent-name | noise | agent name metadata |
pr-link | noise | PR linkage |
The noise and title entries are skipped by get_messages(). debug mode prints the full distribution.
Assistant content block types
The message.content array for assistant entries can hold:
Block type | Field of interest | Meaning |
|---|---|---|
text | text | The actual assistant text output. |
thinking | thinking (or text) | Model internal reasoning. |
tool_use | name, input, id | A regular tool call. id is the matching id for any later tool_result. |
server_tool_use | name, input | Server-side tool call (e.g., advisor invocation). |
advisor_tool_result | content.text | The advisor's reply. Always nested as block.content.text. |
tool_result | tool_use_id, content | Result for a prior tool_use. content is a string or an array of {type:"text", text:"..."}. |
Compact marker
A /compact event appears as a type:"user" entry whose first text content starts with:
"This session is being continued from a previous conversation"
classify_entry returns "compact" for these. Everything before the most-recent compact marker is the pre-compact conversation.
Timestamps
Most entries carry a timestamp field in ISO-8601 form (2026-05-01T10:00:05Z). _parse_timestamp accepts ISO strings, naive ISO, and numeric epoch values, and converts aware values to the display timezone (system local, or --tz) as naive datetimes — the same zone --since/--until are interpreted in, so comparisons line up.
Title entries
Both ai-title and custom-title entries surface a aiTitle / customTitle string. session_summary() prefers aiTitle when both are present.
Truncation behavior
iter_lines drops the final line if it lacks a trailing newline AND fails to parse as JSON, printing [note: dropped truncated trailing line in <name>] to stderr. Malformed mid-file lines are dropped silently.
Status inference
infer_status(lines, mtime, current_session_id, session_uuid) returns one of:
| Status | Glyph | Heuristic |
|---|---|---|
active | ● | current_session_id == session_uuid AND mtime within 5 minutes |
interrupted | ! | Any tool_use block lacks a paired tool_result |
pending-user | ? | Last assistant text message ends with ? |
clean | ✓ | none of the above |
This is heuristic — it's correct for the majority of real sessions on this machine but can be fooled by, e.g., an assistant message that legitimately ends with a question.
04 Codex SchemaCodex’s two-layer event and response schema, and the double-count trap it sets.
Reference
Codex Schema
Where it lives
~/.codex/sessions/YYYY/MM/DD/rollout-<ISO-ts>-<uuid>.jsonl
- One rollout file per session, partitioned by the date the session started
(from the filename timestamp). A session that runs past midnight still lives in
its start-date folder; its file mtime is the last write.
- The date folders ARE the index —
ls ~/.codex/sessions/2026/07/15/lists that
day's sessions with no decoding. (Contrast Claude's lossy encoded-cwd dirs.)
- Filename:
rollout-2026-07-15T13-32-50-<uuid>.jsonl. The uuid is everything
after the hyphenated ISO timestamp (lib.codex.rollout_uuid).
- Other Codex state under
~/.codex/(not read by this skill):history.jsonl
(cross-session command history), session_index.jsonl, archived_sessions/,
and sqlite DBs (state_*.sqlite, memories_*.sqlite, logs_*.sqlite). Rollouts
are the transcript source of truth; the rest is out of scope.
Line schema
Every line is {"timestamp": <UTC-ISO>, "type": <...>, "payload": {...}}. Unlike
Claude, the timestamp is top-level on every line (UTC, e.g.
2026-07-15T17:37:24.816Z). Top-level type:
type | count (typical) | what it is |
|---|---|---|
session_meta | 1 (first line) | session id, cwd, originator, cli_version, model_provider |
event_msg | many | the clean UI event stream (see below) |
response_item | many | the raw model item stream (Responses API) |
turn_context | a few | per-turn context |
world_state | 1–2 | environment snapshot |
compacted / event_msg:context_compacted | 0–1 | compaction marker |
Two layers — the double-count trap
event_msg and response_item are two views of the same conversation. Take
messages from ONE layer or you double every count.
`event_msg` — the clean layer (this is what the adapter uses for messages,
edits, and accounting):
payload.type | fields | meaning | ||
|---|---|---|---|---|
user_message | .message (str) | the real typed prompt | ||
agent_message | .message (str), .phase (commentary\ | final_answer) | assistant-visible text | |
patch_apply_end | .changes (map path→`{type: add\ | update\ | delete}), .success, .stdout` | an applied file edit |
task_started / task_complete | .turn_id | turn boundaries (one final_answer per turn) | ||
token_count | .info.total_token_usage, .rate_limits | cumulative + last-turn usage | ||
thread_settings_applied, context_compacted | — | bookkeeping |
`response_item` — full detail (the adapter uses it only for reasoning + tools,
never messages, to avoid the double-count):
payload.type | fields | meaning | |
|---|---|---|---|
message | .role (user/assistant/developer), .content[] = `{type: input_text\ | output_text, text}` | mirrors the event_msg messages — skipped by the adapter |
reasoning | .summary[] (usually []), .encrypted_content | model reasoning — normally encrypted, so no readable thinking | |
function_call | .name, .arguments (JSON string), .call_id | a built-in tool call (e.g. wait, shell) | |
custom_tool_call | .name (e.g. exec), .input (code/command string), .call_id | the JS-sandbox / MCP tool call | |
function_call_output / custom_tool_call_output | — | tool results — not mapped |
How the adapter normalizes it
lib.codex.normalize_rollout(path) → Claude-shaped entries so
classify_entry / get_messages / extract_tool_calls / files_touched /
_is_real_user_prompt / session_summary all work unchanged:
user_message→{type:"user", message:{role:"user", content:[text]}}agent_message(both phases) →{type:"assistant", message:{role:"assistant", content:[text]}}patch_apply_end→ assistant entry withtool_useblocks (add→Write,
update/delete→Edit, file_path = each changed path) so file-edit modes work
function_call/custom_tool_call→ assistant entry with atool_useblock
(name = the Codex tool; wait, exec, spawn_agent, send_message, …)
reasoningwith non-emptysummary→ athinkingblock (usually dropped, encrypted)- everything else (
session_meta,response_item:message, outputs,turn_context,
world_state, token_count, task_*) → dropped as non-signal
Tool_use blocks are emitted without an `id` on purpose: infer_status treats a
tool_use id with no matching tool_result as a dangling call ("interrupted"), and
Codex outputs aren't mapped back — omitting the id keeps status inference honest.
Gotchas
- Don't `Read` a raw rollout. They run to megabytes and the two-layer schema is
noisy. Use --file <rollout> --mode brief/dump/last/tool-calls/... (auto-detected)
or jq on .payload.
- `jq: error: writing output failed: Invalid argument` on Windows/git-bash is a
harmless SIGPIPE artifact when piping jq into head — ignore it.
- Message counts: 25
user_messageevents ≠ 26response_itemuser messages —
the response layer includes injected developer/permission context. Count from
event_msg. The adapter already does.
- Reasoning is encrypted (
summary: []), so--in thinkingon a Codex session
is usually empty. Expected, not schema drift.
- cwd comes from
session_meta.payload.cwd, not the folder path (the folder is a
date). session_summary derives the project label from it.
- Discovery honors `ESTACK_CODEX_SESSIONS_DIR` (an env override) for tests; in
normal use it reads ~/.codex/sessions. Cross-agent CLI modes only enable Codex
against the live root (or when that override is set) — backups have no Codex tree.
Verifying the schema on a real rollout
CX=~/.codex/sessions/2026/07/15/rollout-*.jsonl jq -r '.type' "$CX" | sort | uniq -c # top-level type mix jq -r 'select(.type=="event_msg")|.payload.type' "$CX" | sort | uniq -c jq -r 'select(.type=="response_item")|.payload.type' "$CX" | sort | uniq -c jq -c 'select(.payload.type=="user_message")|.payload' "$CX" | head -1
If the distribution shows an unfamiliar payload.type, or the message layers stop
mirroring, the schema drifted — update lib/codex.py and this file at the source
repo (see SKILL.md § "Update this skill with what you learn").
Use it now. It's free.
Works on all platforms. Pick yours and get set up in under a minute.
Claude.ai
Download & upload in 60 seconds
Download the zip, then open Claude.ai to upload it.
Download the zip below. With JavaScript enabled, Claude.ai opens in a new tab if your browser allows it. Otherwise, use Open Claude.ai.
Click the + button in the skills column on the left.
Select Create a skill.
Select Upload a skill and upload the zip.
Start your session history recovery by running /estack-read-agent-history.
Claude Code
Run one command in any terminal
Works anywhere Node.js is installed — your project directory, home directory, anywhere.
Open your terminal app and run this command.
npx elliot-stack@latest
Run the command.
Start Claude Code by typing claude in your terminal.
Start your session history recovery by running /estack-read-agent-history.
ChatGPT / Other
Paste a prompt — the AI does the rest
This prompt tells the AI where to fetch current instructions from the live site. No installs. No version lag.
Copy the prompt below.
Preview prompt
# Read Agent Session History
Search, read, recover, and analyze local AI coding-agent session history across **two agents** — **Claude Code** and **Codex** (OpenAI codex-cli): the current session, prior sessions, sibling subagents, all projects, and `.claude-backups` snapshots. One CLI reads both.
## The ladder — how to answer any session-history question
1. **A CLI mode fits** → use it. One deterministic command, done. Cross-agent modes read Claude **and** Codex by default (`--agent claude|codex|both`, default `both`).
2. **A mode almost fits** → run it with `--format json` and post-process the output (a python one-liner, jq, grep). Don't contort the question to fit the flags.
3. **No mode comes close** → write a one-off Python script in your scratchpad importing the primitives in `scripts/lib/` (`paths`, `parser`, `search`, `subagents`, `tools`, `codex` — the docstrings are the API reference). They encode the correctness traps below; never re-derive them.
4. **The same gap keeps recurring** → add a small mode or flag to the CLI itself and record it (see "Update this skill" below).
Never use the Read tool on a raw `.jsonl` (Claude **or** Codex), and never hand-roll parsing without `lib.parser` — both schemas have traps (noise entries, tool-result envelopes, UTC timestamps, and Codex's two-layer event/response streams). `lib.parser.parse_lines` auto-detects a Codex rollout and normalizes it into the same shape Claude emits, so every primitive works on both.
Scratch-script boilerplate:
```python
import sys
from pathlib import Path
sys.path.insert(0, str(Path.home() / ".claude/skills/estack-read-agent-history/scripts"))
from lib import parser, paths, search, subagents, tools, codex
```
## Where sessions live
**Claude Code:**
```
~/.claude/projects/<encoded-cwd>/<session-uuid>.jsonl # one file per session
~/.claude/projects/<encoded-cwd>/<uuid>/subagents/agent-*.jsonl # subagent transcripts (+ .meta.json)
~/.claude-backups/{mirror,snapshot-24h,snapshot-1w,snapshot-1mo}/projects/… # backups, same layout
```
`<encoded-cwd>` = the working directory with `:` `\` `/` and whitespace each replaced by `-`. The encoding is **lossy** — never reconstruct a real path from an encoded name; resolve by UUID or content.
**Codex:**
```
~/.codex/sessions/YYYY/MM/DD/rollout-<ISO-ts>-<uuid>.jsonl # one "rollout" file per session, date-partitioned
```
Codex is date-partitioned (the folder IS the index — `ls ~/.codex/sessions/2026/07/15/`), and each rollout's real cwd/uuid live in its leading `session_meta` line. Both agents' entry schemas: `https://elliotdrel.com/e-stack/read-agent-history/references/jsonl-schema.md`. The full Codex schema + traps: `https://elliotdrel.com/e-stack/read-agent-history/references/codex-history.md`.
The current (Claude Code) session ID is: ${CLAUDE_SESSION_ID}
(In a context where that substitution isn't visible — e.g. a subagent — read the real env var `CLAUDE_CODE_SESSION_ID`, or run `--mode whoami`.)
## Quick lookups (CLI)
```bash
PY="$HOME/.claude/skills/estack-read-agent-history/scripts/read_transcript.py"
```
| Need | Command |
|---|---|
| THIS session's path | `python "$PY" --mode whoami --cwd "<cwd>"` |
| UUID prefix → path (either agent) | `python "$PY" --mode lookup --uuid abc123de` |
| List sessions (both agents) | `python "$PY" --mode list --all-projects --since 7d` |
| Keyword search everywhere | `python "$PY" --mode search --all-projects --query "supabase migration"` |
| 6-line session summary (either agent) | `python "$PY" --file <session-or-rollout.jsonl> --mode brief` |
| Last assistant / **user** message | `python "$PY" --file <s.jsonl> --mode last [--role user\|both]` |
| Pre-/compact recovery | `python "$PY" --file <session.jsonl> --mode pre-compact` |
| All subagent finals | `python "$PY" --file <parent.jsonl> --mode subagent-finals` |
| Day overview / "what did I do" | `python "$PY" --mode session-report --date yesterday` |
| Activity map with idle gaps | `python "$PY" --mode timeline --date yesterday` |
| My real attention time | `python "$PY" --mode engagement --date today` |
| Just one agent | add `--agent codex` (or `--agent claude`) to any cross-agent mode |
| `claude --resume` snippet | `python "$PY" --mode resume-cmd --uuid <prefix>` |
**Both agents by default.** The cross-session modes merge Claude Code **and** Codex over one deduped prompt stream (parallel chats split the clock, never double-count); narrow with `--agent claude|codex`. Single-file modes (`--file`) auto-detect a Codex rollout — no flag needed.
Every mode takes `--format json` (a `source: "claude"|"codex"` field tags each session). Full reference (every mode, flags, exit codes, JSON shapes, the time-accounting semantics, `--agent`, and presentation defaults for day reviews): `https://elliotdrel.com/e-stack/read-agent-history/references/modes.md`. Codex schema + gotchas: `https://elliotdrel.com/e-stack/read-agent-history/references/codex-history.md`. Multi-step workflows: `https://elliotdrel.com/e-stack/read-agent-history/references/recipes.md`.
## Pitfalls
- **Timestamps in both agents' .jsonl files are UTC.** CLI output and `lib.parser` conversions are already local — never mix raw with converted, never hand-add offsets. (Codex conveniently puts a top-level `timestamp` on every line; Claude on every entry.) Report times to the user in 12-hour format unless asked otherwise.
- **Raw entry counts lie — in both agents.** Claude `type:user` includes tool-result envelopes and hook/skill `isMeta` injections; `type:assistant` includes tool-only turns. Codex has TWO parallel layers (`event_msg` vs `response_item`) that mirror the same messages — count from one, not both, or you double. The CLI/`lib.parser` already handle this; never hand-tally.
- **Never hand-roll cross-agent time math.** The shared top-level `timestamp` tempts a `grep`+`awk` hack with a hardcoded UTC offset — `timeline`/`engagement` already merge both agents correctly.
- **A live transcript's last line may be truncated** — `lib.parser.iter_lines` handles it (Claude and Codex); bare `json.loads` per line crashes.
- **Bound your output.** Cross-project/cross-agent sweeps can emit tens of thousands of tokens; summarize per session, expand selectively.
- **Windows:** use `python` (not `python3`); pass Windows-style paths into Python (POSIX paths from Bash cause `FileNotFoundError`); run JSON pipe chains in Bash — PowerShell 5.1 pipes inject a BOM.
- **Empty/weird results** → `--mode debug` prints the entry-type distribution and probes for schema drift. Codex reasoning is usually encrypted (`summary: []`), so `--in thinking` on a Codex session is often empty — that's expected, not drift.
## Backups
Four roots under `C:\Users\2supe\.claude-backups\` survive transcript-deletion incidents (like the March 2026 auto-update bug, GitHub #41591): `mirror`, `snapshot-24h`, `snapshot-1w`, `snapshot-1mo`. Every CLI mode accepts `--root <name>`; recovery playbook in `https://elliotdrel.com/e-stack/read-agent-history/references/recipes.md`.
## Update this skill with what you learn
Every hard use is a field test. If a technique worked well, a documented claim misled you, the schema drifted (Claude **or** Codex), or you hit ladder step 4 (a recurring gap worth a deterministic fix), tell the user and update the skill at its source: the e-stack repo (`C:\Users\2supe\All Coding\E-Stack\e-stack`, `skills/estack-read-agent-history/`), via that repo's `manage-e-stack` flow. Techniques go in `https://elliotdrel.com/e-stack/read-agent-history/references/recipes.md`, Claude schema findings in `https://elliotdrel.com/e-stack/read-agent-history/references/jsonl-schema.md`, Codex schema findings in `https://elliotdrel.com/e-stack/read-agent-history/references/codex-history.md`, new modes in the CLI + `https://elliotdrel.com/e-stack/read-agent-history/references/modes.md`. Don't edit the installed copy under `~/.claude/skills/` — the installer overwrites it. No repo on this machine → offer to file it as a GitHub issue (below).
---
## Skill Feedback
If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
**If `gh` is installed** (`gh --version` succeeds), create the issue directly:
```bash
gh issue create \
--repo ElliotDrel/e-stack \
--title "estack-read-agent-history: <concise summary>" \
--body "<description from user feedback — expected vs. actual behavior and context>"
```
**If `gh` is not installed**, build a pre-filled URL:
```bash
python3 -c "
import urllib.parse
title = 'estack-read-agent-history: <concise summary>'
body = '<description from user feedback — expected vs. actual behavior and context>'
base = 'https://github.com/ElliotDrel/e-stack/issues/new'
print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
"
```
Share the printed URL with the user and offer to open it in their browser.
They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
Open your platform and paste the prompt.
Start your session history recovery.
Read Agent History ships in E-Stack, a set of 21 free skills installed by one command. See the whole stack.