claude-code-transcripts完整教程：local、web、json命令全解析

【免费下载链接】claude-code-transcripts Tools for publishing transcripts for Claude Code sessions 项目地址: https://gitcode.com/gh_mirrors/cl/claude-code-transcripts

claude-code-transcripts是一款功能强大的工具，专为发布Claude Code会话记录而设计，支持local、web和json三种命令模式，帮助用户轻松将会话转换为HTML格式。

一、快速入门：安装与基础配置

1.1 环境准备

在开始使用claude-code-transcripts之前，请确保您的系统已满足以下要求：

• Python环境（推荐Python 3.8及以上版本）
• 网络连接（用于web命令和依赖安装）

1.2 安装步骤

通过以下命令克隆仓库并安装依赖：

git clone https://gitcode.com/gh_mirrors/cl/claude-code-transcripts
cd claude-code-transcripts
pip install .

安装完成后，您可以通过运行claude-code-transcripts --help命令验证安装是否成功。

二、local命令：处理本地会话文件

2.1 命令概述

local命令用于处理本地存储的Claude Code会话文件，将其转换为HTML格式。该命令位于src/claude_code_transcripts/init.py文件中，函数定义如下：

def local_cmd(output, output_auto, repo, gist, include_json, open_browser, limit):
    """Select and convert a local Claude Code session to HTML."""

2.2 基本用法

最简单的使用方式是直接运行：

claude-code-transcripts local

该命令会自动扫描默认会话目录（~/.claude/projects），并显示所有可用的会话供您选择。选择后，工具将生成HTML文件并自动在浏览器中打开。

2.3 高级选项

local命令提供了多种实用选项，让您可以自定义输出：

• -o, --output：指定输出目录
• --output-auto：自动创建以会话ID命名的子目录
• -r, --repo：关联GitHub仓库信息
• -g, --gist：创建GitHub Gist并生成预览链接
• --include-json：同时保存原始JSONL文件
• --open-browser：自动在浏览器中打开生成的HTML
• --limit：限制显示的会话数量

示例：将本地会话转换为HTML并保存JSON文件

claude-code-transcripts local --include-json -o ./output

三、json命令：处理JSON/JSONL文件

3.1 命令概述

json命令允许您直接处理JSON或JSONL格式的会话文件，无论是本地文件还是通过URL获取的文件。函数定义如下：

def json_cmd(json_file, output, output_auto, repo, gist, include_json, open_browser):
    """Convert a Claude Code session JSON/JSONL file or URL to HTML."""

3.2 本地文件处理

要处理本地JSON/JSONL文件，只需指定文件路径：

claude-code-transcripts json ./path/to/session.json

3.3 URL文件处理

json命令还支持直接从URL获取会话文件：

claude-code-transcripts json https://example.com/session.jsonl

工具会自动下载文件并转换为HTML格式。

3.4 实用示例

将远程JSONL文件转换为HTML并创建Gist：

claude-code-transcripts json https://example.com/session.jsonl -g --open-browser

四、web命令：从Claude API获取会话

4.1 命令概述

web命令允许您直接从Claude API获取会话数据并转换为HTML。函数定义如下：

def web_cmd(
    session_id,
    output,
    output_auto,
    token,
    org_uuid,
    repo,
    gist,
    include_json,
    open_browser,
):
    """Select and convert a web session from the Claude API to HTML."""

4.2 配置认证

使用web命令前，需要配置访问令牌和组织UUID。您可以通过以下方式提供：

1. 直接通过命令行参数：

   claude-code-transcripts web --token YOUR_TOKEN --org-uuid YOUR_ORG_UUID
   

2. 在macOS上，工具会自动从钥匙串获取令牌（如果已登录Claude Code）

4.3 基本用法

如果不指定会话ID，工具会显示交互式会话选择器：

claude-code-transcripts web

您也可以直接指定会话ID：

claude-code-transcripts web SESSION_ID

4.4 按仓库筛选会话

使用--repo选项可以按GitHub仓库筛选会话：

claude-code-transcripts web --repo owner/repo-name

五、高级功能与最佳实践

5.1 生成Gist分享

所有命令都支持-g或--gist选项，用于创建GitHub Gist并生成预览链接：

claude-code-transcripts local -g

生成的Gist包含完整的HTML文件，您可以通过提供的预览链接分享给他人。

5.2 自定义输出目录

使用-o选项指定输出目录，结合--output-auto可以自动创建以会话ID命名的子目录：

claude-code-transcripts json ./session.json -o ./output --output-auto

这将在./output目录下创建一个以会话ID命名的子目录，并将所有输出文件保存在其中。

5.3 同时保存JSON数据

使用--include-json选项可以在生成HTML的同时保存原始JSON数据：

claude-code-transcripts web --include-json

这对于后续分析或数据备份非常有用。

六、常见问题解决

6.1 本地会话未找到

如果运行local命令时提示"Projects folder not found"，请确保您的Claude Code已保存会话到默认目录（~/.claude/projects）。

6.2 API认证失败

使用web命令时如果遇到认证问题，请检查您的访问令牌和组织UUID是否正确。您可以通过以下命令获取组织UUID：

cat ~/.claude.json | grep orgId

6.3 输出目录权限问题

如果遇到"Permission denied"错误，请确保您对指定的输出目录有写入权限，或选择其他目录。

七、总结

claude-code-transcripts提供了三种强大的命令模式（local、web和json），让您可以轻松地将Claude Code会话转换为HTML格式。无论是处理本地文件、远程URL还是直接从API获取数据，这款工具都能满足您的需求。通过本文介绍的各种选项和最佳实践，您可以充分利用claude-code-transcripts的功能，高效地管理和分享您的Claude Code会话记录。

【免费下载链接】claude-code-transcripts Tools for publishing transcripts for Claude Code sessions 项目地址: https://gitcode.com/gh_mirrors/cl/claude-code-transcripts