claude-code-history-files-finder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Code History Files Finder

Extract and recover content from Claude Code's session history files stored in

~/.claude/projects/

从存储在

~/.claude/projects/

中的Claude Code会话历史文件中提取并恢复内容。

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

会话文件存储在

~/.claude/projects/<normalized-path>/<session-id>.jsonl

路径下。

有关JSONL结构和提取模式的详细信息，请参阅

references/session_file_format.md

。

Core Operations

核心操作

1. List Sessions for a Project

1. 列出项目的所有会话

Find all session files for a specific project:

bash

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).

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

bash

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

显示带时间戳和文件大小的最新会话。

可选参数：

--limit N

仅显示N个会话（默认值：10）。

2. Search Sessions for Keywords

2. 按关键词搜索会话

Locate sessions containing specific content:

bash

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.

定位包含特定内容的会话：

bash

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

返回按关键词出现频率排序的会话，包含：

总提及次数
各关键词的详细统计
会话日期和路径

可选参数：

--case-sensitive

启用精确匹配。

3. Recover Deleted Content

3. 恢复已删除内容

Extract files from session history:

bash

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

Extracts all Write tool calls and saves files to

./recovered_content/

Filtering by keywords:

bash

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

Recovers only files matching any keyword in their path.

Custom output directory:

bash

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

从会话历史中提取文件：

bash

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

提取所有Write tool调用记录，并将文件保存到

./recovered_content/

目录。

按关键词过滤：

bash

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

仅恢复路径中包含任意关键词的文件。

自定义输出目录：

bash

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

4. Analyze Session Statistics

4. 分析会话统计数据

Get detailed session metrics:

bash

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.

获取详细的会话指标：

bash

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

生成报告包含：

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

可选参数：

--show-files

列出所有文件操作记录。

Workflow Examples

工作流示例

For detailed workflow examples including file recovery, tracking file evolution, and batch operations, see

references/workflow_examples.md

有关文件恢复、跟踪文件演变和批量操作的详细工作流示例，请参阅

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.

recover_content.py

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

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:

bash

undefined

创建具有描述性的输出目录：

bash

undefined

Bad

不推荐

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

Good

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

undefined

head -20 ./recovered_content/ImportantFile.jsx

undefined

Limitations

局限性

What Can Be Recovered

可恢复内容

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

✅ 使用Write tool写入的文件 ✅ Markdown块中显示的代码（部分提取） ✅ 来自Edit/Read操作的文件路径

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

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

File Versions

文件版本

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

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

Troubleshooting

故障排除

No Sessions Found

未找到会话

bash

undefined

bash

undefined

Verify project path normalization

验证项目路径的标准化处理

ls ~/.claude/projects/ | grep -i "project-name"

Check actual projects directory

检查实际的projects目录

ls -la ~/.claude/projects/

undefined

ls -la ~/.claude/projects/

undefined

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

可能原因：

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

解决方法：

尝试使用
```
--show-edits
```
参数查看Edit操作记录
扩大关键词搜索范围
搜索相邻的会话

Large Session Files

大型会话文件

For sessions >100MB:

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

对于大于100MB的会话文件：

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

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:

bash

undefined

会话文件可能包含：

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

分享前请务必清理内容：

bash

undefined

Remove absolute paths

移除绝对路径

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

Verify no credentials

检查是否存在凭证

grep -i "api_key|password|token" recovered_content/*

undefined

grep -i "api_key|password|token" recovered_content/*

undefined

Safe Storage

安全存储

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

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

claude-code-history-files-finder

Original

Translation

Claude Code History Files Finder

Claude Code History Files Finder

Capabilities

功能

Session File Locations

会话文件位置

Core Operations

核心操作

1. List Sessions for a Project

1. 列出项目的所有会话

2. Search Sessions for Keywords

2. 按关键词搜索会话

3. Recover Deleted Content

3. 恢复已删除内容

4. Analyze Session Statistics

4. 分析会话统计数据

Workflow Examples

工作流示例

Recovery Best Practices

恢复最佳实践

Deduplication

去重

Keyword Selection

关键词选择

Output Organization

输出目录组织

Bad

不推荐

Good

推荐

Verification

验证

Check file list

查看文件列表

Read recovery report

阅读恢复报告

Spot-check content

抽查内容

Limitations

局限性

What Can Be Recovered

可恢复内容

What Cannot Be Recovered

不可恢复内容

File Versions

文件版本

Troubleshooting

故障排除

No Sessions Found

未找到会话

Verify project path normalization

验证项目路径的标准化处理

Check actual projects directory

检查实际的projects目录

Empty Recovery

恢复内容为空

Large Session Files

大型会话文件

Security & Privacy

安全与隐私

Before Sharing Recovered Content

分享恢复内容前

Remove absolute paths

移除绝对路径

Verify no credentials

检查是否存在凭证

Safe Storage

安全存储