Back to Details

claude-code-history-files-finder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Claude Code History Files Finder

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/
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/
undefined
python3 scripts/recover_content.py session.jsonl -o ./recovered_deleted_docs/ python3 scripts/recover_content.py session.jsonl -o ./feature_xy_history/
undefined

Verification

验证

After recovery, always verify content:
bash
undefined
恢复完成后，请务必验证内容：
bash
undefined

Check file list

查看文件列表

ls -lh ./recovered_content/
ls -lh ./recovered_content/

Read recovery report

阅读恢复报告

cat ./recovered_content/recovery_report.txt
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"
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
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.
恢复的内容继承了原始会话的敏感性。请安全存储，并遵循组织关于会话数据处理的政策。