Claude Code历史文件查找器：恢复丢失代码、搜索会话历史、分析文件操作的工具

claude-code-history-files-finder by daymade/claude-code-skills

170 周安装量

713 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/daymade/claude-code-skills --skill claude-code-history-files-finder

开发自动化文件管理

🇨🇳中文介绍

Claude Code 历史文件查找器

从存储在 ~/.claude/projects/ 中的 Claude Code 会话历史文件中提取和恢复内容。

功能

从之前的会话中恢复已删除或丢失的文件
在对话历史中搜索特定的代码或内容
分析过去会话中的文件修改
跟踪工具使用情况和文件操作随时间的变化
查找包含特定关键词或主题的会话

会话文件位置

会话文件存储在 ~/.claude/projects/<normalized-path>/<session-id>.jsonl。

关于 JSONL 结构和提取模式的详细信息，请参阅 references/session_file_format.md。

核心操作

1. 列出项目的所有会话

查找特定项目的所有会话文件：

python3 scripts/analyze_sessions.py list /path/to/project

显示最近的会话，包括时间戳和大小。

可选：--limit N 仅显示 N 个会话（默认值：10）。

2. 在会话中搜索关键词

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

3. 恢复已删除的内容

从会话历史中提取文件：

python3 scripts/recover_content.py /path/to/session.jsonl

提取所有 Write 工具调用，并将文件保存到 ./recovered_content/。

按关键词过滤：

python3 scripts/recover_content.py session.jsonl -k ModelLoading FRONTEND deleted

仅恢复路径匹配任何关键词的文件。

自定义输出目录：

python3 scripts/recover_content.py session.jsonl -o ./my_recovery/

4. 分析会话统计信息

获取详细的会话指标：

python3 scripts/analyze_sessions.py stats /path/to/session.jsonl

消息数量（用户/助手）
工具使用情况细分
文件操作数量（Write/Edit/Read）

可选：--show-files 列出所有文件操作。

关于文件恢复、跟踪文件演变和批量操作等详细工作流示例，请参阅 references/workflow_examples.md。

recover_content.py 自动仅保留每个文件的最新版本。如果一个文件在会话中被多次写入，则只保存最终版本。

选择出现在以下位置的独特关键词：

文件名或路径
函数/类名
代码中的唯一字符串
错误消息或注释

创建描述性的输出目录：

# 不佳
python3 scripts/recover_content.py session.jsonl -o ./output/

# 良好
python3 scripts/recover_content.py session.jsonl -o ./recovered_deleted_docs/
python3 scripts/recover_content.py session.jsonl -o ./feature_xy_history/

恢复后，务必验证内容：

# 检查文件列表
ls -lh ./recovered_content/

# 阅读恢复报告
cat ./recovered_content/recovery_report.txt

# 抽查内容
head -20 ./recovered_content/ImportantFile.jsx

可以恢复的内容

✅ 使用 Write 工具写入的文件 ✅ 在 markdown 代码块中显示的代码（部分提取） ✅ Edit/Read 操作中的文件路径

无法恢复的内容

❌ 从未写入磁盘的文件（仅讨论过） ❌ 在会话开始前已删除的文件 ❌ 二进制文件（图像、PDF）- 仅路径可用 ❌ 未在会话中捕获的外部工具输出

仅捕获调用 Write 工具时的状态
Write 调用之间的中间编辑内容会丢失
Edit 操作显示差异，而非完整内容

# 验证项目路径规范化
ls ~/.claude/projects/ | grep -i "project-name"

# 检查实际项目目录
ls -la ~/.claude/projects/

文件被编辑（Edit 工具）但从未写入（Write 工具）
关键词与会话中的文件路径不匹配
会话早于文件创建时间

尝试使用 --show-edits 标志查看 Edit 操作
扩大关键词搜索范围
搜索相邻的会话

对于大于 100MB 的会话：

脚本使用流式处理（逐行处理）
内存使用量保持恒定
处理可能需要 1-2 分钟

共享恢复内容前

会话文件可能包含：

包含用户名的绝对路径
API 密钥或凭据
公司特定信息

共享前务必清理：

# 移除绝对路径
sed -i '' 's|/Users/[^/]*/|/Users/username/|g' file.js

# 验证没有凭据
grep -i "api_key\|password\|token" recovered_content/*

恢复的内容继承了原始会话的敏感性。请安全存储，并遵循组织处理会话数据的政策。

🇺🇸English

Claude Code History Files Finder

Extract and recover content from Claude Code's session history files stored in ~/.claude/projects/.

Capabilities

Recover deleted or lost files from previous sessions
Search for specific code or content across conversation history
Analyze file modifications across past sessions
Track tool usage and file operations over time
Find sessions containing specific keywords or topics

Session File Locations

Session files are stored at ~/.claude/projects/<normalized-path>/<session-id>.jsonl.

For detailed JSONL structure and extraction patterns, see references/session_file_format.md.

Core Operations

1. List Sessions for a Project

Find all session files for a specific project:

python3 scripts/analyze_sessions.py list /path/to/project

Shows most recent sessions with timestamps and sizes.

Optional: --limit N to show only N sessions (default: 10).

2. Search Sessions for Keywords

Locate sessions containing specific content:

python3 scripts/analyze_sessions.py search /path/to/project keyword1 keyword2

Returns sessions ranked by keyword frequency with:

Total mention count
Per-keyword breakdown
Session date and path

Optional: --case-sensitive for exact matching.

3. Recover Deleted Content

Extract files from session history:

python3 scripts/recover_content.py /path/to/session.jsonl

Extracts all Write tool calls and saves files to ./recovered_content/.

Filtering by keywords :

python3 scripts/recover_content.py session.jsonl -k ModelLoading FRONTEND deleted

Recovers only files matching any keyword in their path.

Custom output directory :

python3 scripts/recover_content.py session.jsonl -o ./my_recovery/

4. Analyze Session Statistics

Get detailed session metrics:

python3 scripts/analyze_sessions.py stats /path/to/session.jsonl

Reports:

Message counts (user/assistant)
Tool usage breakdown
File operation counts (Write/Edit/Read)

Optional: --show-files to list all file operations.

Workflow Examples

For detailed workflow examples including file recovery, tracking file evolution, and batch operations, see references/workflow_examples.md.

Recovery Best Practices

Deduplication

recover_content.py automatically keeps only the latest version of each file. If a file was written multiple times in a session, only the final version is saved.

Keyword Selection

Choose distinctive keywords that appear in:

File names or paths
Function/class names
Unique strings in code
Error messages or comments

Output Organization

Create descriptive output directories:

# Bad
python3 scripts/recover_content.py session.jsonl -o ./output/

# Good
python3 scripts/recover_content.py session.jsonl -o ./recovered_deleted_docs/
python3 scripts/recover_content.py session.jsonl -o ./feature_xy_history/

Verification

After recovery, always verify content:

# Check file list
ls -lh ./recovered_content/

# Read recovery report
cat ./recovered_content/recovery_report.txt

# Spot-check content
head -20 ./recovered_content/ImportantFile.jsx

Limitations

What Can Be Recovered

✅ Files written using Write tool ✅ Code shown in markdown blocks (partial extraction) ✅ File paths from Edit/Read operations

What Cannot Be Recovered

❌ Files never written to disk (only discussed) ❌ Files deleted before session start ❌ Binary files (images, PDFs) - only paths available ❌ External tool outputs not captured in session

File Versions

Only captures state when Write tool was called
Intermediate edits between Write calls are lost
Edit operations show deltas, not full content

Troubleshooting

No Sessions Found

# Verify project path normalization
ls ~/.claude/projects/ | grep -i "project-name"

# Check actual projects directory
ls -la ~/.claude/projects/

Empty Recovery

Possible causes:

Files were edited (Edit tool) but never written (Write tool)
Keywords don't match file paths in session
Session predates file creation

Solutions:

Try --show-edits flag to see Edit operations
Broaden keyword search
Search adjacent sessions

Large Session Files

For sessions >100MB:

Scripts use streaming (line-by-line processing)
Memory usage remains constant
Processing may take 1-2 minutes

Security & Privacy

Before Sharing Recovered Content

Session files may contain:

Absolute paths with usernames
API keys or credentials
Company-specific information

Always sanitize before sharing:

# Remove absolute paths
sed -i '' 's|/Users/[^/]*/|/Users/username/|g' file.js

# Verify no credentials
grep -i "api_key\|password\|token" recovered_content/*

Safe Storage

Recovered content inherits sensitivity from original sessions. Store securely and follow organizational policies for handling session data.

Weekly Installs

102

Repository

daymade/claude-…e-skills

GitHub Stars

636

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubWarn SocketPass SnykPass

Installed on

claude-code86

opencode78

codex70

gemini-cli68

cursor64

github-copilot62

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

150,000 周安装