claude-code-transcripts

claude-code-transcripts 是一个用于将 Claude Code 会话文件转换为 HTML 转录稿的技能工具，由 ara.so 提供，属于 reason-machines/claude-code-skills 技能集合。

用途

该工具把 Claude Code 的会话文件（JSON 或 JSONL 格式）转换为干净、适配移动端、分页展示的 HTML 转录稿。它适用于查看、归档和分享 Claude Code 会话记录，支持本机会话、网页会话以及直接指定会话文件三种来源，并可直接发布到 GitHub Gist 进行分享。

主要能力

转换本地会话：从 ~/.claude/projects 选择会话并生成 HTML。
转换网页会话：通过 Claude API 导入会话（macOS 会自动从钥匙串获取凭据）。
转换指定文件：支持本地 JSON/JSONL 文件或远程 URL。
批量归档：将全部本机会话转换为可浏览的 HTML 归档。
发布到 GitHub Gist：上传转录稿并生成可分享的预览链接。
生成内容包含分页转录页面、提示与提交的时间线、时间戳、语法高亮代码块和工具使用详情。
提供 Python API，可在代码中调用转换与会话获取功能。

使用方式

安装（推荐 uv）：

uv tool install claude-code-transcripts

或免安装运行：

uvx claude-code-transcripts --help

或使用 pip：

pip install claude-code-transcripts

本地会话命令示例：

# 交互式选择最近会话
claude-code-transcripts
# 显式使用本地命令
claude-code-transcripts local
# 显示更多会话
claude-code-transcripts local --limit 20
# 保存到指定目录
claude-code-transcripts local -o ./my-transcript
# 根据会话自动命名输出目录
claude-code-transcripts local -a
# 保留原始 JSON 文件
claude-code-transcripts local -o ./output --json

网页会话命令示例：

claude-code-transcripts web
claude-code-transcripts web SESSION_ABC123
claude-code-transcripts web --repo simonw/datasette
claude-code-transcripts web --token $CLAUDE_TOKEN --org-uuid $ORG_UUID

转换指定文件示例：

claude-code-transcripts json session.json -o ./output
claude-code-transcripts json https://example.com/session.json --open
claude-code-transcripts json ~/.claude/projects/my-project/session.jsonl -a

批量归档示例：

claude-code-transcripts all
claude-code-transcripts all --dry-run
claude-code-transcripts all -o ./my-archive
claude-code-transcripts all --include-agents
claude-code-transcripts all --open
claude-code-transcripts all -q

发布到 GitHub Gist（需安装并认证 gh CLI）：

claude-code-transcripts --gist
claude-code-transcripts web SESSION_ID --gist
claude-code-transcripts json session.json --gist
claude-code-transcripts json session.json -o ./backup --gist

输出示例：

Gist: https://gist.github.com/username/abc123def456
Preview: https://gisthost.github.io/?abc123def456/index.html
Files: /tmp/session-abc123

通用选项：

-o, --output DIRECTORY 输出目录（默认临时目录并自动打开浏览器）
-a, --output-auto 根据会话 ID 或文件名自动命名子目录
--repo OWNER/NAME 用于提交链接的 GitHub 仓库（可从 git 自动检测）
--open 在默认浏览器打开 index.html（未指定 -o 时为默认行为）
--gist 上传到 GitHub Gist 并输出预览 URL
--json 在输出目录中包含原始会话文件

输出结构：

output-directory/
├── index.html          # 提示与提交的时间线
├── page-001.html       # 转录第一页
├── page-002.html       # 转录第二页
├── ...
└── session_ABC.json    # 原始会话（使用 --json 时）

Python API 示例：

from claude_code_transcripts.core import convert_session_to_html
from pathlib import Path

session_file = Path("~/.claude/projects/my-project/session.jsonl").expanduser()
output_dir = Path("./transcript")

convert_session_to_html(
    session_file=session_file,
    output_dir=output_dir,
    repo="owner/repo",
    open_browser=True
)

from claude_code_transcripts.web import fetch_session_data, list_sessions

sessions = list_sessions(token="...", org_uuid="...")
for session in sessions:
    print(f"{session['id']}: {session.get('description', 'No description')}")

session_data = fetch_session_data(
    session_id="SESSION_ABC123",
    token="...",
    org_uuid="..."
)

环境变量（网页 API 访问可选用）：

CLAUDE_TOKEN 替代 --token
ORG_UUID 替代 --org-uuid 在 macOS 上，登录 Claude Code 后会自动从系统钥匙串获取。

适用场景

快速预览：交互选择最近会话，生成 HTML 并打开浏览器。
公开分享：将网页会话或本地会话转换为 Gist 并获取可分享链接。
归档备份：将全部本机会话转为可浏览的 HTML 归档，并可包含原始文件。
批量处理：用 shell 循环转换多个会话文件。

限制与注意事项

网页会话功能目前存在问题（见 issue #77），可能无法列出或获取会话，建议改用本地会话或 JSON 导出。
使用 --gist 需要安装并认证 GitHub CLI（gh auth login）。
若缺少提交链接，需通过 --repo 显式指定仓库，或确保当前处于具有 GitHub 远程的 git 仓库中。
本地无会话时，请检查 ~/.claude/projects/*/session.jsonl 是否存在。
超大会话文件转换可能耗时较长；转录会自动分页，可用 -q 减少进度输出。
其他平台凭据获取与收费情况资料未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项