chat-history

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Chat History Extractor

会话历史提取器

Extract user inputs from Claude Code session history (

~/.claude/projects/

) and organize them into a project's

.chats

directory with daily markdown files.

从Claude Code会话历史（

~/.claude/projects/

）中提取用户输入，并按日期整理到项目的

.chats

目录下的Markdown文件中。

When to Use This Skill

何时使用该技能

Use this skill when the user wants to:

Extract session history from Claude Code sessions
Document conversations for future reference
Create instruction logs organized by date
Export user inputs from
```
.jsonl
```
session files
Maintain a changelog of Claude interactions

当用户需要以下操作时使用本技能：

提取会话历史：从Claude Code会话中提取记录
记录对话：用于未来参考
创建按日期分类的指令日志
从
.jsonl
会话文件导出用户输入
维护与Claude交互的变更日志

How It Works

工作原理

Claude Code stores session data in

~/.claude/projects/{project-path-encoded}/

.jsonl

files. Each file contains messages with:

```
type: "user"
```
- User messages
```
userType: "external"
```
- External user (not system/agent)
```
message.content
```
- The actual message content

This skill extracts meaningful user instructions (filtering out system commands, tool results, and session continuations) and organizes them by date into

.chats/{YYYYMMDD}.md

files.

Claude Code将会话数据存储在

~/.claude/projects/{project-path-encoded}/

路径下的

.jsonl

文件中。每个文件包含的消息具有以下属性：

```
type: "user"
```
- 用户消息
```
userType: "external"
```
- 外部用户（非系统/代理）
```
message.content
```
- 实际消息内容

本技能会提取有意义的用户指令（过滤掉系统命令、工具结果和会话续接消息），并按日期整理到

.chats/{YYYYMMDD}.md

文件中。

Instructions

操作步骤

Step 1: Identify the Project Session Directory

步骤1：确定项目会话目录

The session directory is derived from the current working directory path:

Replace
```
/
```
with
```
-
```
in the path
Prefix with
```
-
```
Location:
```
~/.claude/projects/{encoded-path}/
```

bash

undefined

将路径中的
```
/
```
替换为
```
-
```
前缀添加
```
-
```
完整路径：
```
~/.claude/projects/{encoded-path}/
```

bash

undefined

Example: /Users/tchen/projects/tubi/titc

示例：/Users/tchen/projects/tubi/titc

Becomes: -Users-tchen-projects-tubi-titc

转换后：-Users-tchen-projects-tubi-titc

Full path: ~/.claude/projects/-Users-tchen-projects-tubi-titc/

完整路径：~/.claude/projects/-Users-tchen-projects-tubi-titc/

undefined

undefined

Step 2: Find Session Files by Date

步骤2：按日期查找会话文件

List session files and filter by modification date:

bash

undefined

列出会话文件并按修改日期过滤：

bash

undefined

List all main session files (excluding agent-* files) for a specific date

列出指定日期的所有主会话文件（排除agent-*文件）

ls -la ~/.claude/projects/{project-dir}/*.jsonl | grep "Dec 25" | grep -v agent-

undefined

ls -la ~/.claude/projects/{project-dir}/*.jsonl | grep "Dec 25" | grep -v agent-

undefined

Step 3: Extract User Inputs

步骤3：提取用户输入

Extract user messages from jsonl files using jq:

bash

cat {session-file}.jsonl | jq -r '
  select(.type == "user" and .userType == "external" and (.isMeta | not)) |
  .message.content |
  if type == "string" then . else empty end
' | grep -v "^Caveat:" \
  | grep -v "^<command" \
  | grep -v "^<local-command" \
  | grep -v "^This session is being continued" \
  | grep -v "^<user-prompt-submit-hook>" \
  | grep -v "^Analysis:" \
  | grep -v "^$"

使用jq从jsonl文件中提取用户消息：

bash

cat {session-file}.jsonl | jq -r '
  select(.type == "user" and .userType == "external" and (.isMeta | not)) |
  .message.content |
  if type == "string" then . else empty end
' | grep -v "^Caveat:" \
  | grep -v "^<command" \
  | grep -v "^<local-command" \
  | grep -v "^This session is being continued" \
  | grep -v "^<user-prompt-submit-hook>" \
  | grep -v "^Analysis:" \
  | grep -v "^$"

Step 4: Create/Update .chats Files

步骤4：创建/更新.chats文件

Create markdown files in

.chats/

directory with format:

markdown

undefined

在

.chats/

目录下创建Markdown文件，格式如下：

markdown

undefined

Instructions

指令

{task title}

{任务标题}

{user instruction}

{用户指令}

{another task title}

{另一任务标题}

{another user instruction}

undefined

{另一用户指令}

undefined

Step 5: Commit Changes

步骤5：提交变更

After creating/updating chat files, commit with:

bash

git add .chats/*.md
git commit -m "docs(chats): add session history for {date range}"

创建/更新聊天文件后，执行以下提交命令：

bash

git add .chats/*.md
git commit -m "docs(chats): add session history for {date range}"

File Format

文件格式

Each

.chats/{YYYYMMDD}.md

file should:

Start with
```
# Instructions
```
header
Use
```
##
```
for each major task/instruction
Include the actual user input text
Group related instructions under the same heading
Preserve code blocks and formatting

每个

.chats/{YYYYMMDD}.md

文件应满足：

以
```
# 指令
```
开头
使用
```
##
```
标记每个主要任务/指令
包含实际的用户输入文本
将相关指令分组到同一标题下
保留代码块和格式

Example Output

输出示例

.chats/20251225.md

markdown

undefined

.chats/20251225.md

：

markdown

undefined

Instructions

指令

implement feature X

实现功能X

based on @specs/feature-x.md implement all phases entirely

commit the code and test

基于@specs/feature-x.md完整实现所有阶段

提交代码并测试

fix bug Y

修复Bug Y

investigate why component Z is not working

use sub agents to analyze the issue in parallel

undefined

调查组件Z无法正常工作的原因

使用子代理并行分析问题

undefined

Filtering Rules

过滤规则

Include:

Direct user instructions and requests
Questions about the codebase
Task specifications and requirements

Exclude:

System commands (
```
<command-name>
```
,
```
<local-command-stdout>
```
)
Session continuation messages
Tool results and agent responses
Hook notifications (
```
<user-prompt-submit-hook>
```
)
Empty lines and caveat messages

包含：

直接的用户指令和请求
关于代码库的问题
任务规范和需求

排除：

系统命令（
```
<command-name>
```
、
```
<local-command-stdout>
```
）
会话续接消息
工具结果和代理响应
钩子通知（
```
<user-prompt-submit-hook>
```
）
空行和警告消息

Workflow Summary

工作流程总结

Get current working directory
Compute encoded project path
Find session directory:
```
~/.claude/projects/{encoded-path}/
```
List sessions grouped by date
For each date with sessions:
- Extract user inputs from all sessions
- Create
```
.chats/{YYYYMMDD}.md
```
- Organize inputs with descriptive headers
Create
```
.chats/
```
directory if it doesn't exist
Optionally commit the changes

获取当前工作目录
计算编码后的项目路径
查找会话目录：
```
~/.claude/projects/{encoded-path}/
```
按日期列出会话
对每个有会话的日期：
- 从所有会话中提取用户输入
- 创建
```
.chats/{YYYYMMDD}.md
```
  文件
- 使用描述性标题组织输入内容
若
```
.chats/
```
目录不存在则创建
可选：提交变更

Helper Script

辅助脚本

You can use this bash snippet to quickly find the project session directory:

bash

undefined

你可以使用以下bash片段快速查找项目会话目录：

bash

undefined

Get encoded project path

获取编码后的项目路径

PROJECT_PATH=$(pwd | sed 's|/|-|g' | sed 's|^|/|' | sed 's|^/|-|') SESSION_DIR="$HOME/.claude/projects/$PROJECT_PATH"

Check if exists

检查目录是否存在

if [ -d "$SESSION_DIR" ]; then echo "Session directory: $SESSION_DIR" echo "Sessions by date:" ls -la "$SESSION_DIR"/*.jsonl 2>/dev/null | grep -v agent- | awk '{print $6, $7}' | sort -u else echo "No session directory found for this project" fi

undefined

undefined

Notes

注意事项

Session files named
```
agent-*.jsonl
```
are sub-agent sessions and typically don't contain direct user input
Main session files have UUID-style names (e.g.,
```
01e78099-de0e-4424-845c-518638c8241e.jsonl
```
)
The
```
.message.content
```
field can be either a string (user text) or an array (tool results)
Always verify the extracted content makes sense before committing

名为
```
agent-*.jsonl
```
的会话文件是子代理会话，通常不包含直接用户输入
主会话文件采用UUID格式命名（例如：
```
01e78099-de0e-4424-845c-518638c8241e.jsonl
```
）
```
.message.content
```
字段可以是字符串（用户文本）或数组（工具结果）
提交前请务必验证提取的内容合理有效