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

read-claude-code-history

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

Reads, searches, and exports local Claude Code history without resuming work. Covers recent session inventory, exact session timelines, verbatim human input including queued mid-turn prompts, full-event keyword search, hybrid recall when wording changed, end-state triage, and deleted-file recovery across active Claude homes plus registered archives. Use whenever the user asks what they or Claude said, wants a Claude Code session ID or original context, remembers prior work vaguely, needs an old file from a transcript, or must prove what a Claude session contained before continuing it. Also owns the only Kimi CLI surface, via its Kimi inventory and search flags. For Codex history use read-codex-history; when the request names no platform at all or spans providers, start at local-conversation-history.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit

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

1How It Works & Mechanism

Implemented as 6 local Python CLIs (list_local_history / read_claude_session / extract_user_messages / analyze_sessions / history_index / recover_content), respectively covering inventory, exact session reconstruction, human input export, keyword search, hybrid recall, triage, and file recovery; invoked by the agent according to the SKILL routing table, with resuming old processes explicitly prohibited.

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

| Recent Claude Code sessions, titles, dates, or IDs | `scripts/list_local_history.py --source claude` |

SKILL.md maps 'what result the user wants' to specific scripts and parameters; guardrails explicitly hardcode 'Do not run `claude --resume` or `claude --continue`', ensuring this remains a read-only evidence layer that must hand over evidence to continue-claude-code-work before any action is taken.

'Not found' is an expensive answer: full discovery across multiple homes is the foundation of correctness. homes.py enumerates CLAUDE_CONFIG_DIR, ~/.claude, ~/.claude-profiles/*, and ~/.claude-* sibling homes; sources.py then merges archives registered in ~/.claude/history-sources.json; sessions are deduplicated by Session ID and sorted by in-record timestamps rather than mtime.

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

# CLAUDE_CONFIG_DIR wins first when set, then the default home.

The module docstring highlights the rationale: 'A tool that only looks at ~/.claude silently misses every conversation held under a profile, which is the #1 reason a real session is wrongly reported as not found'—meaning multi-home discovery directly determines whether a 'not found' conclusion is trustworthy.

Claude records are processed semantically rather than literally: storage labels (type: user) do not equate to the author; queued commands during busy periods are hidden in attachment.queued_command.prompt (origin.kind: human), and reading only user records misses corrections.

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

Treat Claude's record labels as storage metadata, not authorship proof.

The SKILL applies an entire block of constraints: top-level type: user records may contain command envelopes, hook boilerplate, pasted full documents, agent-persona text, or system placeholders; the companion references/session_file_format.md explains the schema, sidechains, attachments, compaction, and file-history snapshots.

Optional 'hybrid recall' path (history_index.py recall): Chinese tokenization FTS5 (wangfenjin/simple libsimple, pinned to version v0.7.1 + SHA256 verified download) + Qwen3 embeddings (Apple Silicon MLX), blending BM25 and vector search to resolve semantic recall when 'wording has changed'; not part of the default read-only path.

daymade-claude-code/read-claude-code-history/scripts/history_index.py

EMBEDDING_MODEL_ID = "Qwen/Qwen3-Embedding-0.6B"

In the same file, SIMPLE_VERSION = v0.7.1; reference document hybrid_history_recall.md clarifies the division of responsibilities: 'You remember the meaning but not the wording | `history_index.py recall` | Ranked candidate sessions', while exact forensic retrieval still uses analyze_sessions.py search. Installation/downloading is described in the SKILL as a one-time setup.

File recovery (recover_content.py) follows a three-stage gate of 'report-approve-write': a recovery report is first generated against the exact session file, and writing only occurs after manual review of each destination path; directly overwriting the active project tree is prohibited.

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

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.

Recovers deleted or overwritten files preserved in Claude file-history records; isolates 'disk writing' from normal read operations with dedicated rules.

Kimi CLI history is a live surface of this skill: inventory is handled via list_local_history.py --source kimi, and full-text search via analyze_sessions.py search --kimi, parsing state.json/wire JSONL under ~/.kimi-code (home precedence: --kimi-home > KIMI_HOME > ~/.kimi-code).

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

Kimi CLI (kimi-code) stores conversations under ``~/.kimi-code/`` (override with ``KIMI_HOME``).

SKILL.md states: 'Kimi CLI is a live surface of this Skill, not a legacy one. It has no reader of its own'—answering Kimi queries with Claude data would fabricate a false 'never happened'; shared _core indicates this package is a single implementation bundled and replicated across read-*-history skills (SSOT lives in _conversation_core/).

2Core Capabilities

01Recent session inventory across all Claude homes/archives (including profile-isolated sessions, subagent markers, and source diagnostics)

02Exact timeline evidence briefing by Session ID (compaction boundaries, user/assistant alternations, queued commands, end reasons, pending tool calls, subagent statuses, and files/memories/workspaces)

03Full-event keyword search (messages, thinking, tool inputs/outputs, compaction summaries, attachments, queues, and file snapshots), excluding agent prompts and current-session self-matches by default

04Human input export to Markdown/HTML: strips storage pollution, retains queued prompts, and deduplicates while preserving order without arbitrary topical categorization

05Semantic hybrid recall when wording changes (optional libsimple FTS5 + Qwen3 embeddings)

06Triage: categorizes how sessions ended (interrupted/net-error/stuck-on-tool/done) by time window or project

07Deleted/overwritten file recovery from file-history snapshots (report first, write upon approval)

08Kimi CLI inventory and full-text search (the only live surface within the repository)

3External Dependencies

Kind	Dependency / Endpoint
cli	git
cli	rg/grep（可选路径预过滤）
network	github.com 发布物下载（wangfenjin/simple libsimple，固定版本+SHA256 校验，仅混合索引 setup）
network	Hugging Face 模型（Qwen/Qwen3-Embedding-0.6B，仅 --download-model 经 mlx_embeddings.load）
package	可选 Python 依赖 chonkie/transformers（分块）与 mlx-embeddings/mlx（Apple Silicon 向量）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Execute local scripts or commands: runs 6 bundled scripts using python3 (pure standard library by default)
网络端点: Declared external network access: urllib.urlopen downloads from https://github.com/wangfenjin/simple/releases/download/v0
本地工作目录: File read/write and artifact output: extract_user_messages.py writes Markdown/HTML to a user-specified output base path

Audit Notes: The default read path has zero outbound traffic and is strictly local read-only (JSONL read-only, sqlite mode=ro), qualifying as a blue tier by standard guidelines. The yellow classification is assigned due to the existence of real outbound network code paths (non-default trigger): history_index.py setup downloads the native libsimple from github.com/wangfenjin/simple releases (pinned version v0.7.1, SHA256 verified, zip-slip protected) and loads it in-process as an FTS5 extension; when --download-model is specified, it further downloads the HF model Qwen/Qwen3-Embedding-0.6B via mlx_embeddings. The external destinations are predictable (public sources), touch no credentials, and require explicit user invocation, warranting yellow rather than a higher tier. The data plane contains full local session history that may include credentials, which the SKILL protects with built-in sharing gates.

5Second-Pass Verification

[ok] libsimple 下载（github.com/wangfenjin/simple）调用点 — history_index.py url 构造 + urlopen；sha256 校验与 _safe_extract_zip 穿越防护真实存在。
[ok] 无其他网络调用（排除 requests/curl/wget/其他 urlopen） — 全目录扫描仅 history_index.py 引入 urllib.request；其余脚本零网络 import。
[ok] Kimi 表面真实存在且只读 — list_local_history.py argparse choices 含 kimi；analyze_sessions.py search 有 --kimi/--kimi-home；_core/kimi.py 只解析 state.json/wire.jsonl，无 kimi CLI 调用。
[ok] read-only 承诺与写盘面核对 — SKILL guardrails 禁止 resume/continue；写盘仅 extract_user_messages（用户给输出基址）、recover_content（报告后批准）、history_index（可选索引库）。
[unlocatable] Qwen 嵌入模型网络端点 — 静态证据止于 EMBEDDING_MODEL_ID + mlx_embeddings.load(...) 与 ~/.cache/huggingface 路径；HF 实际网络端点由 mlx-embeddings 库行为决定，源码未直写，未运行验证。
[ok] 能力声明夸大检查（exact timelines/verbatim input/full-event search） — read_claude_session.py 严格解析含 compaction 前记录、extract_user_messages 去噪逻辑（NOISE_USER_PATTERNS/IMG_TOKEN_RE）、analyze_sessions 预算超时显式失败——均有代码与测试佐证。

6Verdict & Scenarios

Default path is purely local and read-only, using multi-home + archive discovery to eliminate 'false not found' outcomes

Deep semantic understanding of Claude storage: dedicated handling and references for storage label ≠ author, queued_command corrections, compaction markers, and file-history snapshots

Report-and-approve gating on write/recovery paths, physically isolating reading from writing

High engineering completeness: comprehensive flags, pytest coverage, eval acceptance suites, and explicit failure on abnormal paths (budget timeouts, malformed JSONL, replica divergence) rather than feigning completeness

Best for: Suited for scenarios requiring proof of what was actually said or done in a Claude session: recovering Session IDs, verbatim human inputs, deleted file recovery, and comprehensive search across profiles/archives; ideal as an evidence layer before continuing work (paired with continue-claude-code-work), and for advanced users who treat 'trustworthy local history retrieval' as core infrastructure.

Not for: Not suited for requests that need to resume old processes to continue work or modify past projects (use continue-claude-code-work for that); not suited for environments without local Claude Code history; users who do not need semantic 'forgot the exact wording' recall do not need to enable history_index (avoiding download and MLX dependencies); please use corresponding surfaces for Kimi/Codex queries, as this skill does not replace them.

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload read-claude-code-history.tar.gz

sha256: 646d5ca94bdfe86a…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.