CCDebug - Claude Code 调试工具

May 25, 2026 · View on GitHub

CCDebug 是一个针对 Claude Code 和 Codex 的调试工具，用于记录并可视化运行轨迹，同时支持对单个 LLM 请求进行“修改-重放”，帮助你快速定位提示词/上下文/工具调用导致的偏差。（本项目基于 lemmy/claude-trace 二次开发）

>>English README

✨ 主要功能

1、时间线展示轨迹

  • 按CC执行步骤显示: 可以区分不同类型日志，用户输入、LLM回复、工具调用等
  • 支持步骤详情: 可以快速查看某一步的原始CC日志内容

时间线展示CC运行轨迹

2、快速切换日志

  • 一键跳转SubAgent日志: 一键跳转到子代理日志，方便查看子代理的运行轨迹
  • 快速切换项目和会话: 直接切换 ~/.claude/projects 下的不同项目和会话，无需启动多次工具

快速切换项目和会话

3、快速搜索定位

  • 全局搜索关键字: 可以快速定位到包含指定关键字的日志（搜索当前会话下所有日志文件）
  • 步骤概览过滤: 步骤概览显示执行全貌，可按不同类型的时间线节点过滤
  • 生成分享链接: 可以生成当前会话的分享链接，方便多人协作分析

快速搜索定位

4、快速分析耗时

  • 显示步骤开始时间: 每个日志节点显示当前步骤的开始时间
  • 显示工具调用耗时: 对于工具调用、SubAgent执行的步骤，节点将显示调用耗时
  • 统计步骤间耗时: 用户可以标记2个步骤节点，共计自动计算并显示2个节点间耗时

快速分析耗时

5、对CC步骤单点调试

注意：调试功能仅支持NPM脚本形式安装的 Claude Code，不支持原生二进制版本。

对CC步骤单点调试

  • 追踪LLM请求: 详细记录CC对LLM的所有请求日志
  • 重新发送LLM请求: 支持修改LLM请求数据，重新发送请求，方便反复验证LLM的响应是否符合预期

🚀 快速开始

安装

# 推荐：从 npm 全局安装
npm install -g @myskyline_ai/ccdebug

# 或：安装本地/发布产物 tgz
# npm install -g /path/to/@myskyline_ai-ccdebug-x.y.z.tgz

基本使用

1. 启动 Claude 并记录交互

# 基本用法 - 启动 Claude 并自动记录
ccdebug

# 包含所有请求（不仅仅是对话）
ccdebug --include-all-requests

# 将后续参数传递给 Claude 进程（示例）
ccdebug --run-with -p "请按要求工作" --verbose

2. 启动 Web 站点查看时间线轨迹

# 启动 Web 服务器查看时间线（默认端口 3001，默认项目目录为当前目录）
ccdebug -l

# 在自定义端口启动
ccdebug -l --port 3001

# 指定项目目录启动
ccdebug -l --project /path/to/your/cc_workdir

# 直接指定日志目录启动（不是项目目录）
ccdebug -l --log-dir /path/to/your/logs

# 查看 Codex 执行日志（默认读取 ~/.codex/sessions）
ccdebug -l --codex

# 查看指定项目路径对应的 Codex 执行日志（匹配 session_meta.cwd）
ccdebug -l --codex --project /path/to/your/codex_workdir

# 指定 Codex sessions 目录
ccdebug -l --codex --codex-sessions-dir /Users/ligf/.codex/sessions

# 直接读取指定目录下的 Codex jsonl 日志
ccdebug -l --codex --log-dir /Users/ligf/Code/claude-code/ccdebug/ccdemo

# 部署在反向代理子路径下
ccdebug -l --port 1435 --base-path /jm-ai-agent-service-log

指定日志文件自动打开：

http://localhost:3001/?logfile=<日志文件名>

logfile 参数不包含 .jsonl 后缀，且只会匹配 --log-dir 指定目录下的同名日志文件。

日志输出目录

  • CC 标准日志（用于时间线）: .claude-trace/cclog/*.jsonl（包含主日志与 agent-*.jsonl 子代理日志）
  • CC API 跟踪日志（用于 LLM 请求调试）: .claude-trace/tracelog/*.jsonl
  • 已保存的 LLM 请求（用于覆盖/重放）: .claude-trace/tracelog/llm_requests/*.json

说明：

  • 运行 ccdebug 启动 Claude 会话后，会将本次会话对应的 CC 标准日志自动拷贝到 .claude-trace/cclog/，并将 API 跟踪日志重命名为 {sessionId}.jsonl。
  • Codex 日志会从 ~/.codex/sessions/**/*.jsonl 读取，并按第一条 session_meta.payload.cwd 与当前启动目录（或 --project 指定目录）精确匹配后展示。
  • 如果你使用的是 Claude Code 原生二进制版本（非 NPM 脚本形式），CCDebug 无法拦截 API 请求，LLM 请求调试能力将不可用（仍可通过 Web 站点查看已有 CC 标准日志）。

📋 命令行选项

选项描述
--log, -l启动 Web 时间线服务器（当 --log 不带参数时等同于 --serve；建议用 -l 避免与 --log <name> 混淆）
--port <number>指定 Web 服务器端口（默认 3001）
--project <path>指定项目目录路径
--log-dir <path>指定 Web 直接读取的日志目录，不按项目目录推导
--base-path <path>指定反向代理子路径，例如 /jm-ai-agent-service-log
--source <claude|codex>指定 Web 日志来源（默认 claude）
--codex使用 Codex 日志来源，读取 ~/.codex/sessions 下的 JSONL 文件
--codex-sessions-dir <path>指定 Codex sessions 目录
--run-with <args>将后续参数传递给 Claude 进程
--include-all-requests包含所有 fetch 请求，而不仅仅是对话
--claude-path <path>指定 Claude 二进制文件的自定义路径
--index为 .claude-trace/ 目录生成对话摘要和索引（会调用 Claude 产生额外 token 消耗）
--version, -v显示版本信息
--help, -h显示帮助信息

🏗️ 技术架构

核心组件

  • HTTP/API 拦截器: 基于 Node.js 的 HTTP/HTTPS + fetch 拦截机制，记录对 Anthropic/Bedrock 的请求与响应
  • CC 标准日志整理: 退出会话时自动将 CC 标准日志（主日志与子代理日志）拷贝到 .claude-trace/cclog/
  • Web 服务器: Express.js 提供文件列表、会话管理、项目切换、LLM 请求读取/保存/重放等 API
  • 前端界面: Vue 3 + Vite + Pinia + Arco Design

数据流程

HTTP 请求/响应 → 拦截器 → 原始数据(JSONL) → 数据处理器 → 结构化数据 → Web 界面展示

📁 项目结构

ccdebug/
├── src/                     # CLI 与拦截器
│   ├── cli.ts              # 命令行入口
│   ├── interceptor.ts      # API 拦截与 tracelog 记录
│   ├── html-generator.ts   # HTML 报告生成器（基于 frontend）
│   └── index-generator.ts  # 对话摘要与索引生成
├── web/                     # Web 时间线站点（Vite + Vue 3）
│   ├── src/                # 前端源码
│   ├── dist/               # 构建产物
│   └── server/             # Express 后端（供 CLI 直接 require 启动）
├── frontend/                # 独立 HTML 报告前端（bundle 注入到 HTML）
├── scripts/                 # 打包脚本
└── docs/                    # 文档与设计说明

🔧 开发

环境要求

  • Node.js >= 16.0.0
  • npm 或 yarn

本地开发

# 克隆项目
git clone https://github.com/ThinkingBeing/ccdebug.git
cd ccdebug

# 安装依赖
npm install

# 构建项目
npm run build

# 开发模式（同时 watch 核心代码 + 前端）
npm run dev

# 使用 tsx 直接运行 CLI（开发调试用）
npx tsx src/cli.ts --help
npx tsx src/cli.ts -l --port 3001 --project /path/to/your/cc_workdir

# 功能ok后打包，包会出现在release目录
npm run package

🔗 相关链接