read-claude-code-history

# Read Claude Code History Read Claude Code evidence only. Do not resume the old process, edit its project, or turn a read request into a continuation task. When the user later asks to act, hand the verified evidence to `daymade-claude-code:continue-claude-code-work`. ## Route by the requested result | User wants | Use | |---|---| | Recent Claude Code sessions, titles, dates, or IDs | Indexed metadata only; the bundled `list_local_history.py` currently reads all candidate bodies before date/limit filtering, so do not use it for a broad inventory | | One known Session reconstructed as a chronological evidence briefing | `scripts/read_claude_session.py --session <ID>` | | Original tool input and paired result from one exact Session, selected by tool name, literal text, ordinal or time | `scripts/read_claude_session.py --session <ID> --tool-evidence --contains '<literal>'`; see **Original tool call/result evidence** below | | The exact command behind a hook audit row that records a Session ID and a command SHA-256 instead of the text | `scripts/read_claude_session.py --session <ID> --find-command-sha256 <HEX>`; see **Command behind a hook audit row** below | | Every Agent/Task tool_use in one Session, quoted verbatim (e.g. the exact prompt handed to an independent reviewer agent) | `scripts/read_claude_session.py --session <ID> --agent-prompts` (optionally `--agent-description-prefix TEXT`); a prompt dispatched twice is listed twice | | Which session launched a program in a known time window, across sessions | `scripts/analyze_sessions.py tool-calls --from <ISO> --to <ISO> --pattern <REGEX> [--tool NAME]`; candidates are selected by filesystem metadata before any body is read, then grouped by session; Codex rollouts are out of scope and the gap is stated in the output | | When hook runs happened across sessions — outcome, duration, exit code per run (e.g. "why was session startup slow", "did this guard fire today") | `scripts/analyze_sessions.py hook-events --from <ISO> --to <ISO> [--pattern <REGEX>] [--event NAME]`; same candidate-first narrowing as tool-calls; forked-session copies of a run collapse to one; Codex rollouts are out of scope and the gap is stated in the output | | The user's recent words, including human queued prompts | `scripts/extract_user_messages.py` | | A conversation or quote by keyword | `scripts/history_index.py recall --mode bm25`, then the exact-session reader | | Prior work whose wording may have changed | `scripts/history_index.py recall` after checking index status | | A topic with no known Session ID | `scripts/history_index.py status`, then `recall`; state index coverage and freshness | | How identified sessions or a physically bounded project ended | Follow **Inspect session endings** in `references/workflow_examples.md` | | A deleted/overwritten file preserved in Claude file-history records | `scripts/recover_content.py` | | How often each Skill ran and who started it (user command, model after the user named it, model unprompted), e.g. to decide model-visible vs user-invocable-only | `scripts/skill_usage_ledger.py index`, then `report` (Claude and Codex together); see **Skill usage ledger** below | | Kimi CLI sessions | `history_index.py recall --provider kimi`, then read the named session's `wire.jsonl`; see **Kimi CLI** below | | Continue a verified Claude session | Stop reading and invoke `daymade-claude-code:continue-claude-code-work` | ## 找「我们之前做的那个 X」（产物类目标）的判据 按词搜不到时换这些判据，别扩词硬搜： 1. **时间约束是第一筛子**。用户给了时间窗（「前两天」「本周」）→ 先按 mtime 筛文件系统（`find <root> -newermt '<日期>' -name '*.html'`），候选面缩到几十条再按形态排。全库关键词搜索应该在时间筛之后，不是之前。 2. **session scratchpad 必须在搜索面内**（`/private/tmp/claude-$(id -u)/**/scratchpad/`，macOS 单用户通常是 `claude-501`）。Claude session 的默认产物落点在那，不在 workspace——「我们之前写的 X」有相当概率躺在 scratchpad。找产物类目标时显式包含它。 3. **恢复出的版本 ≠ 最终版**。从 session jsonl 恢复文件（取 Write 的 content）只拿到某次全量写，后续增量 Edit 不会自动合入——恢复产物可能只有真实文件的零头（实测：28KB 恢复片段 vs 2.45MB 完整版）。打开/渲染后觉得「不像目标」时，先怀疑「我拿到的不是完整版」（原路径文件还在不在、session 里还有没有后续 Edit），不要直接排除目标。 战例（2026-09-18）：找「之前做的聚类网页」，十几轮全库关键词搜索无果；目标一直在 9-13 的 session scratchpad（favorites-ledger.html，2.45MB），恢复的 28KB 片段渲染成裸样式被误判排除，用户给出精确路径后才定位。 The requested output wins over the background story. If the user asks for a chronological table of their raw inputs, return that table; do not replace it with a topic analysis because their motivation mentions an incident. ## Evidence surface and completeness By default, discover every active Claude config home and every archive registered in `~/.claude/history-sources.json`. De-duplicate physical copies by Session ID and content identity, and use record timestamps rather than file mtime. A result scoped to one explicit `--home` is a diagnostic slice, not a completeness claim. Treat Claude's record labels as storage metadata, not authorship proof. A top-level `type: user` record can contain a command envelope, hook boilerplate, a whole pasted document, agent-voiced text, or a system placeholder. Human text typed while the assistant was busy can live in `attachment.queued_command.prompt` with `origin.kind: human`; do not lose those corrections by reading only user records. Read [references/session_file_format.md](references/session_file_format.md) when interpreting schemas, authorship, sidechains, attachment records, compaction, or file-history snapshots. Read [references/hybrid_history_recall.md](references/hybrid_history_recall.md) before building or repairing the optional BM25/vector index. Read [references/workflow_examples.md](references/workflow_examples.md) for indexed discovery, triage, and recovery examples. Read [references/claude_session_format.md](references/claude_session_format.md) when you need the layout rather than the message schema — where sessions live on disk, how project paths are normalized into directory names, the `sessions-index.json` fields, and the `compact_boundary` markers that tell you a transcript was summarized rather than truncated. ## Commands Resolve every script relative to this SKILL.md; do not search the machine for a same-named helper or recreate a JSONL parser inline. ### Indexed discovery ```text <skill-dir>/scripts/history_index.py status <skill-dir>/scripts/history_index.py recall '<topic>' --provider claude --mode bm25 ``` Expected output: candidate Session IDs and index coverage. This is topic discovery, not a complete recent-session inventory. If a complete list is needed, report that the current bundled inventory would scan raw bodies. ### Exact Session evidence ```text <skill-dir>/scripts/read_claude_session.py --session <SESSION_ID> # Add this only when the caller intentionally wants to restrict lookup to one workspace. <skill-dir>/scripts/read_claude_session.py --session <SESSION_ID> --project <workspace> ``` Expected output: `# Claude Code Session Evidence Briefing`, session identity, compaction boundary, chronological user/assistant handoff, queued human prompts, end reason, unresolved calls, subagent state, files touched, memory, and current workspace state. The exact reader always parses every physical Session record, including records before compaction. Default display clips long turns and folds only single-text runtime Skill bodies with `isMeta: true` and a unique earlier `sourceToolUseID` matching a Skill call in the same recorded lineage. It labels the Skill and record coordinate; `--full` expands these bodies and removes character clipping. Human pastes, queued prompts, mixed records and uncertain provenance remain visible under the normal clipping limit. Raw records, extracted timeline text and tool-evidence exports remain unchanged. It checks active and registered-archive copies, accepts only identical or strict append-only supersets, and fails visibly on divergent copies, multiple Session identities, a missing record-level Session identity, malformed JSONL, or unreadable bytes. With an exact Session ID and no `--project`, it searches every project across the discovered active homes and registered archives; an explicit `--project` remains a strict scope. A filename alone never proves Session identity. Read [Local runtime and working-directory evidence](references/session_file_format.md#local-runtime-and-working-directory-evidence) before interpreting task endings, local-command output, or cwd receipts. ### Original tool call/result evidence Use this mode for a particular backup, transfer, continuation command or tool receipt. Resolve one exact Session first; do not obtain tool evidence by printing the whole briefing or recreating a raw-history parser. ```text <skill-dir>/scripts/read_claude_session.py --session <SESSION_ID> \ --tool-evidence --tool Bash --contains 'scp' --contains 'backup' <skill-dir>/scripts/read_claude_session.py --session <SESSION_ID> \ --tool-evidence --ordinal 4:6 --from <ISO_WITH_TIMEZONE> --to <ISO_WITH_TIMEZONE> <skill-dir>/scripts/read_claude_session.py --session <SESSION_ID> \ --tool-evidence --subagent-path workflows/<run>/agent-<id>.jsonl --tool Bash # Save the complete selected payload when it exceeds the bounded response. <skill-dir>/scripts/read_claude_session.py --session <SESSION_ID> \ --tool-evidence --tool Bash --contains 'scp' --full > /absolute/path/tool-evidence.json ``` Expect one JSON envelope with original `tool_use` and `tool_result` blocks, the selected source SHA-256, one-based physical line and content-block coordinates, record UUID/parent UUID, timestamp, cwd and recorded agent/sidechain identity. By default this mode reads only the selected main transcript, including its stored sidechains. To read one known subagent leaf, add `--subagent-path agent-<id>.jsonl` or `--subagent-path workflows/<run>/agent-<id>.jsonl`, relative to that Session's `subagents/` directory. Use the full run-relative path: a basename never selects among repeated agent IDs across Workflow runs. Missing, empty, escaping or unknown paths fail without exporting evidence. Selected leaf tool blocks must carry the matching agent identity and parent Session identity. The JSON source scope and `subagent_files_read` name the actual surface; other leaves remain excluded. Neither mode reads current Git state or memory. It validates every physical record in that transcript; its evidence output omits unrelated conversation prose. Global lookup checks only exact `<SESSION_ID>.jsonl` filenames in active homes and registered archives; a renamed archive remains outside that lookup. Pass an explicitly bounded `--project` if its existing discovery can locate that renamed file. Record-level identity, malformed/unreadable input and divergent-copy gates still apply. A source changing during the read fails visibly; repeat only this read. Require at least one selector. Repeat `--tool NAME` for exact, case-sensitive tool-name alternatives. Repeat `--contains TEXT` to require every case-sensitive literal somewhere in that group's original string values, including nested call inputs and result content; an orphan result cannot match a tool-name filter. `--tools` is an alias for `--tool-evidence`. `--ordinal N` or `N:M` selects one-based group ordinals in first physical occurrence order **before** other filters. Time bounds are inclusive and use the first call timestamp, or the first orphan result timestamp. Datetimes require a timezone; date-only bounds use the machine's local day. Missing/invalid timestamps excluded by a time filter are counted. Pair by tool-use ID within recorded agent/sidechain context, independent of which side landed first. Preserve every block for repeated IDs and label `ambiguous`; label absent counterparts `missing_call` or `missing_result`, and missing IDs `missing_id`. These statuses describe evidence availability, not execution success. Read the original result's error/content fields before claiming the action worked. Check `coverage.output_complete` before treating returned matches as complete. `--max-output-bytes` bounds the entire UTF-8 JSON envelope, including its newline; read the [CLI help](scripts/read_claude_session.py) for its current default. Larger matches may return an explicitly incomplete `block_json_prefix` with its original character count instead of a `block`; later groups may be omitted with a count and `first_omitted_ordinal`. Raise the bound or use `--full` redirected to an absolute local output path to obtain full selected payloads; `--full` removes this mode's byte cap. If metadata alone cannot fit, the read fails without emitting evidence. Exit 0 means at least one selected group, 1 means no match or a source/read failure, and 2 means invalid arguments. Read stderr and coverage to distinguish those cases; zero matches with a time gap or excluded source is not proof that the action never happened. ### Command behind a hook audit row Hook audit logs often store `sid=<SESSION_ID> cmd_sha256=<HEX>` rather than the command text. Resolve a row to the tool call that produced it: ```text <skill-dir>/scripts/read_claude_session.py --session <SESSION_ID> --find-command-sha256 <HEX> ``` Expected output: a `# Tool calls whose command has SHA-256 …` heading, the number of transcript files and tool calls examined, the match count, and for each match the file and line, timestamp, record uuid, tool name and id, cwd, and the full command in a fence. Exit 0 means at least one match, 1 no match, 2 a malformed digest or missing `--session`. The digest is SHA-256 over `tool_input.command` as UTF-8. A hook event raised inside a subagent carries the parent Session ID, so the lookup also searches `<SESSION_ID>/subagents/*.jsonl` and `<SESSION_ID>/subagents/workflows/*/agent-*.jsonl`; a main-transcript-only search misses those calls. Agent/Task prompt lookup and the briefing's subagent inventory use the same Session-bounded layouts, without recursive history discovery. Matches and inventory retain the Workflow run in the relative path. Malformed or foreign inventory leaves are reported with unknown coverage, never as completed agents. Only original assistant/user event records count as tool evidence; diagnostic request-shape copies are excluded. Unlike the briefing, the lookup skips and counts unparseable lines so it still works on a Session that is being written; a zero with skipped lines does not prove the call is absent. ### Indexed content search ```text <skill-dir>/scripts/history_index.py status <skill-dir>/scripts/history_index.py recall '<keyword>' \ --mode bm25 --provider claude --exclude-session <CURRENT_ID> ``` Inspect the index's provider coverage and last indexed time. Open only matching Session IDs with the exact-session reader to verify original records. Indexed recall returns ranked prose candidates, not a census of thinking, tool results, attachments, or unindexed records. The raw `analyze_sessions.py search` entry is disabled for live stores: its date flags filter after reading the files. Use `--role user` or `--role assistant` to narrow the stored role, and repeat `--phrase '<literal text>'` to require exact substrings. These filters constrain both BM25 and vector candidates; `--terms` constrains only the FTS leg. Returned `record_key`, `source_kind`, and `human_authorship` describe provenance, not an authenticated human speaker. Inspect the original record before saying “you said”. Codex tool results are outside this prose index; hand a selected Codex candidate to `read-codex-history`'s original tool/record evidence route. Export original values without automatic content redaction. A result about a neighboring fact does not answer the requested proposition. ### Human-input export ```text <skill-dir>/scripts/extract_user_messages.py \ <persistent-output-base> --days 7 --group-by session ``` This produces Markdown and HTML. It separates storage pollution from human prose and recovers queued prompts. Preserve timestamps, duplicates, and Session boundaries; do not add a second thematic classification unless asked. ### Deleted-content recovery Recovery writes files, so keep it separate from ordinary reading. First run the recovery report against the exact Session file, review every proposed destination, then write only after the user asked to recover content. Never restore directly over the current project tree. ### Skill usage ledger Answers "which Skills do we actually use, and who starts them". It is an incremental index (`~/.claude-history-index/skill-usage-v1.db`): the first `index` parses every Claude and Codex session once, later runs re-parse only files whose size or mtime changed. Reports read the ledger, never raw history. ```bash python3 scripts/skill_usage_ledger.py index # --no-codex to skip Codex python3 scripts/skill_usage_ledger.py report --override user-invocable-only python3 scripts/skill_usage_ledger.py report <skill> [<skill> ...] --since 2026-06-01 --until 2026-09-24 python3 scripts/skill_usage_ledger.py status # freshness + what is not covered ``` Columns: `user_command` (user typed `/X`, or Codex `$X`), `model_named` (the model invoked X and the latest human prompt contained X's name), `model_auto` (the model invoked X unprompted), `last_model_use`, `blocked` (Claude refused a model call because X is not model-invocable — the model reached for it and could not use it; not counted as use), and the Skill's current `skillOverrides` value. `--override STATE` also lists Skills in that state with zero recorded use. Rows group by bare name, which is what `skillOverrides` keys on; `identities` lists the qualified forms merged into a row. More than one namespace there (`review`, `suite:review`) means same-named Skills were counted together — rerun with `--exact` to split them. Read these limits into every conclusion: - A Skill that is user-invocable-only cannot be model-invoked, so its `model_auto` count stops at the day it was hidden. Compare use before and after that date, not the lifetime total. - Codex model use is inferred from the model reading one `.../X/SKILL.md`; a session that edits or audits X's SKILL.md with plain shell reads looks the same. Several SKILL.md files read by one command are recorded as `bulk_read` and excluded. - Not covered: Skills invoked inside Claude subagents, Kimi CLI, and Codex Skills followed from memory without a read. Zero recorded use means "not seen in the covered stores", not "never used". ## Read-result contract Every answer must state: 1. **Sources read** — active homes, registered archives, exact Session files. 2. **Coverage** — Session IDs and internal time window. 3. **Result** — raw chronology or matching evidence, in the requested format. 4. **Gaps** — unreadable files, missing parent/attachment bytes, excluded sidechains, or any scope that was not searched. “Not found” means “not found in the stated coverage,” never “never happened.” Indexed recall omits some record types. State that limit and the index frontier; do not present zero ranked hits as a complete label census. Do not call a compact summary verbatim history; it is a continuation aid and must be checked against raw records and the current workspace for load-bearing claims. Before writing any negative or absolute claim ("never said," "never appears," "could not have happened," "impossible to satisfy"), complete this checklist: 1. **Every record type, not only user/assistant text.** A grep for the literal string must also cover `attachment` (`queued_command.prompt`), `tool_result`, and `thinking` — a record's top-level `type`/`isMeta` alone does not prove or disprove human authorship. Classifying hits by `type:user vs assistant` while skipping `attachment` is exactly how a real mid-turn human command gets reported as never having been said. 2. **The cheap next step before "unrecoverable."** Use indexed recall or re-read an already identified Session if that can close the gap. A boundary you have not tested is not evidence of a boundary. 3. **A contradicting firsthand account reopens the question; it does not lose to your reading.** If the user states they did something and your evidence says otherwise, treat the conflict as a signal to redo (1) and (2), not as a result to defend. If a tool result states it was truncated or paginated ("showing lines X-Y of Z... do not answer from this page alone"), that warning is binding: read the remainder before any conclusion that depends on it. ## Guardrails - Keep ordinary read modes read-only. - Do not run `claude --resume` or `claude --continue`. - Do not use file mtime as conversation chronology. - Do not run a raw whole-history scan. Use the index, or first select an exact Session. A date filter applied after reading every file does not bound work. If index coverage is incomplete, report the gap instead of scanning it. - Do not share raw history outside the local machine without explicit user approval; it can contain credentials and private business context. - Do not report a search as complete after a timeout or malformed source. - Do not assert a negative ("never said," "never appears," "impossible to satisfy") without clearing the checklist in Read-result contract. ## Surface contract First use in a session: run `python3 scripts/surface_version.py` once and note