@myskyline_ai/ccdebug 0.2.16 → 0.2.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/README.en.md +67 -57
  2. package/README.md +34 -20
  3. package/dist/cli.d.ts.map +1 -1
  4. package/dist/cli.js +149 -158
  5. package/dist/interceptor.d.ts +0 -3
  6. package/dist/interceptor.d.ts.map +1 -1
  7. package/dist/interceptor.js +0 -136
  8. package/package.json +1 -1
  9. package/web/dist/assets/{index-PAf6etkP.css → index-CHUycE0b.css} +1 -1
  10. package/web/dist/assets/{index-CBtN4uj6.js → index-CP7tYHG0.js} +3 -3
  11. package/web/dist/assets/{index-CBtN4uj6.js.map → index-CP7tYHG0.js.map} +1 -1
  12. package/web/dist/index.html +2 -2
package/README.en.md CHANGED
@@ -1,131 +1,141 @@
1
+
1
2
  # CCDebug - Claude Code Debugging Tool
2
3
 
3
- CCDebug is a debugging tool for Claude Code. It records and visualizes Claude Code execution traces, and also supports “edit & replay” for a single LLM request so you can quickly pinpoint deviations caused by prompts/context/tool calls.
4
+ CCDebug is a debugging tool for Claude Code. It records and visualizes Claude Code execution traces, and also supports “edit & replay” for a single LLM request to help you quickly pinpoint deviations caused by prompts/context/tool calls. (This project is a derivative work based on [lemmy/claude-trace](https://github.com/badlogic/lemmy/tree/main/apps/claude-trace).)
4
5
 
5
- This project is a derivative work based on [lemmy/claude-trace](https://github.com/badlogic/lemmy/tree/main/apps/claude-trace).
6
+ [>>中文 README](./README.md)
6
7
 
7
8
  ## ✨ Key Features
8
9
 
9
- ### 📊 Timeline view for Claude Code execution
10
+ ### **1. Timeline trace view**
11
+ - **Show by Claude Code execution steps**: distinguish different log types such as user input, LLM replies, and tool calls
12
+ - **Step details supported**: quickly inspect the raw Claude Code log content for any step
13
+
14
+ ![Timeline trace for Claude Code](./docs/img/1、日志以时间线形式展示.png)
15
+
16
+ ### **2. Quick log switching**
17
+ - **One-click jump to SubAgent logs**: jump to sub-agent logs to inspect the sub-agent execution trace
18
+ - **Quickly switch projects and sessions**: switch between different projects and sessions under `~/.claude/projects` without running the tool multiple times
19
+
20
+ ![Quickly switch projects and sessions](./docs/img/2、快速切换项目和会话.gif)
10
21
 
11
- ![Timeline](./docs/img/时间线.png)
22
+ ### **3. Fast search & pinpointing**
23
+ - **Global keyword search**: quickly locate logs containing a given keyword (searches all log files under the current session)
24
+ - **Step overview filtering**: the overview shows the whole execution; filter timeline nodes by type
25
+ - **Generate share links**: generate a share link for the current session for collaborative analysis
12
26
 
13
- - **Conversation timeline**: visualize the full conversation flow and tool call chain.
14
- - **Filter by step type**: filter timeline nodes by type (user message, assistant reply, tool call, etc.).
15
- - **Combined tool call + result**: tool input and its output are shown together for easier inspection.
16
- - **Session selector & sub-agent labels**: choose a main session log; sub-agent logs are shown using agent name/description.
17
- - **Project switching**: switch projects under `~/.claude/projects` in the Web UI to avoid running multiple servers.
27
+ ![Fast search & pinpointing](./docs/img/3、快速搜索定位.gif)
18
28
 
19
- ### 🛠️ Step-level LLM request debugging
29
+ ### **4. Quick latency analysis**
30
+ - **Show step start time**: each log node displays the start time of the step
31
+ - **Show tool-call duration**: for tool calls and SubAgent steps, nodes display the duration
32
+ - **Measure time between steps**: mark two step nodes to automatically calculate and display the elapsed time between them
20
33
 
21
- ![LLM Request Debug](./docs/img/LLM请求调试.png)
34
+ ![Quick latency analysis](./docs/img/4、快速分析耗时.gif)
22
35
 
23
- ![Send Modified Request](./docs/img/发送修改后的LLM请求.png)
36
+ ### **5. Step-level debugging for Claude Code**
37
+ > Note: the debugging feature only supports Claude Code installed via the NPM script form, and does not support the native binary version.
24
38
 
25
- - **Track LLM requests**: record all LLM request/response logs made by Claude Code.
26
- - **Replay requests**: edit the request payload and resend it to validate the response repeatedly.
39
+ ![Step-level debugging for Claude Code](./docs/img/LLM请求调试.png)
40
+ - **Track LLM requests**: record all Claude Code request logs to the LLM in detail
41
+ - **Resend LLM requests**: edit the LLM request payload and resend it, making it easy to repeatedly validate whether the response meets expectations
27
42
 
28
43
  ## 🚀 Quick Start
29
44
 
30
45
  ### Install
31
46
 
32
47
  ```bash
33
- # Recommended: install from npm
48
+ # Recommended: install globally from npm
34
49
  npm install -g @myskyline_ai/ccdebug
35
50
 
36
- # Or install from a local tgz artifact
51
+ # Or: install a local/released tgz artifact
37
52
  # npm install -g /path/to/@myskyline_ai-ccdebug-x.y.z.tgz
38
53
  ```
39
54
 
40
55
  ### Basic usage
41
56
 
42
- #### 1) Launch Claude and record traffic
57
+ #### 1. Launch Claude and record interactions
43
58
 
44
59
  ```bash
45
- # Basic usage - start Claude and record logs
60
+ # Basic usage - start Claude and record automatically
46
61
  ccdebug
47
62
 
48
- # Include all requests (not only /v1/messages)
63
+ # Include all requests (not only conversations)
49
64
  ccdebug --include-all-requests
50
65
 
51
- # Pass all subsequent arguments to Claude (example)
52
- ccdebug --run-with -p "Do the work as requested" --verbose
66
+ # Pass subsequent args to the Claude process (example)
67
+ ccdebug --run-with -p "Please work as requested" --verbose
53
68
  ```
54
69
 
55
- #### 2) Start the Web timeline server
70
+ #### 2. Start the Web site to view the timeline trace
56
71
 
57
72
  ```bash
58
- # Start the Web server (default port: 3001, default project dir: current working directory)
59
- ccdebug --serve
73
+ # Start the Web server for the timeline (default port: 3001; default project dir: current directory)
74
+ ccdebug -l
60
75
 
61
- # Custom port
62
- ccdebug --serve --port 3001
76
+ # Start on a custom port
77
+ ccdebug -l --port 3001
63
78
 
64
- # Specify project directory
65
- ccdebug --serve --project /path/to/your/cc_workdir
79
+ # Start with a specified project directory
80
+ ccdebug -l --project /path/to/your/cc_workdir
66
81
  ```
67
82
 
68
83
  ### Log output directories
69
84
 
70
85
  - **Claude Code standard logs (for timeline)**: `.claude-trace/cclog/*.jsonl` (includes main logs and `agent-*.jsonl` sub-agent logs)
71
- - **Claude API tracing logs (for LLM debugging)**: `.claude-trace/tracelog/*.jsonl`
72
- - **Saved LLM request overrides (for replay)**: `.claude-trace/tracelog/llm_requests/*.json`
86
+ - **Claude Code API tracing logs (for LLM request debugging)**: `.claude-trace/tracelog/*.jsonl`
87
+ - **Saved LLM requests (for override/replay)**: `.claude-trace/tracelog/llm_requests/*.json`
73
88
 
74
89
  Notes:
75
90
 
76
- - After a `ccdebug`-launched Claude session ends, CCDebug automatically copies the corresponding Claude Code standard logs into `.claude-trace/cclog/`, and renames the API tracing log to `{sessionId}.jsonl`.
77
- - If you are using the **native Claude Code binary** (not the npm script version), CCDebug cannot intercept API requests, so LLM request debugging won’t work. You can still use the Web UI to view existing standard logs.
91
+ - After you run `ccdebug` to start a Claude session, CCDebug automatically copies the corresponding Claude Code standard logs into `.claude-trace/cclog/`, and renames the API tracing log to `{sessionId}.jsonl`.
92
+ - If you are using the **native Claude Code binary version** (not the NPM script form), CCDebug cannot intercept API requests, and LLM request debugging will be unavailable (you can still view existing Claude Code standard logs via the Web site).
78
93
 
79
94
  ## 📋 CLI Options
80
95
 
81
96
  | Option | Description |
82
97
  |------|------|
83
- | `--serve` | Start the Web timeline server |
84
- | `--log, -l` | Start the Web timeline server (`--log` without a value behaves like `--serve`; prefer `-l` to avoid confusion with `--log <name>`) |
98
+ | `--log, -l` | Start the Web timeline server (when `--log` is used without a value, it is equivalent to `--serve`; prefer `-l` to avoid confusion with `--log <name>`) |
85
99
  | `--port <number>` | Web server port (default: 3001) |
86
- | `--project <path>` | Project directory |
100
+ | `--project <path>` | Project directory path |
87
101
  | `--run-with <args>` | Pass subsequent args to the Claude process |
88
- | `--include-all-requests` | Capture all Claude-related requests, not only chat requests |
89
- | `--no-open` | Do not auto-open the generated HTML in a browser (currently only effective for `--generate-html`) |
90
- | `--claude-path <path>` | Custom path to the Claude binary or `cli.js` |
91
- | `--log <name>` | Base name for API tracing logs (affects files under `.claude-trace/tracelog/`) |
92
- | `--generate-html <input.jsonl> [output.html]` | Generate an HTML report from a JSONL file |
93
- | `--index` | Generate conversation summaries & an index under `.claude-trace/` (will call Claude and incur token usage) |
94
- | `--extract-token` | Extract OAuth token and exit |
95
- | `--version, -v` | Print version |
102
+ | `--include-all-requests` | Include all fetch requests, not only conversations |
103
+ | `--claude-path <path>` | Custom path to the Claude binary |
104
+ | `--index` | Generate conversation summaries and an index for the `.claude-trace/` directory (will call Claude and incur extra token usage) |
105
+ | `--version, -v` | Show version information |
96
106
  | `--help, -h` | Show help |
97
107
 
98
108
  ## 🏗️ Architecture
99
109
 
100
110
  ### Core components
101
111
 
102
- - **HTTP/API interceptor**: intercepts Node.js HTTP/HTTPS + fetch to capture Anthropic/Bedrock requests and responses.
103
- - **Standard log collection**: on exit, copies main and sub-agent Claude Code logs into `.claude-trace/cclog/`.
104
- - **Web server**: Express provides APIs for file listing, session management, project switching, and LLM request read/save/replay.
105
- - **Frontend**: Vue 3 + Vite + Pinia + Arco Design.
112
+ - **HTTP/API interceptor**: based on Node.js HTTP/HTTPS + fetch interception, recording requests and responses to Anthropic/Bedrock
113
+ - **Claude Code standard log consolidation**: on session exit, automatically copies Claude Code standard logs (main and sub-agent logs) into `.claude-trace/cclog/`
114
+ - **Web server**: Express.js provides APIs for file listing, session management, project switching, and LLM request read/save/replay
115
+ - **Frontend UI**: Vue 3 + Vite + Pinia + Arco Design
106
116
 
107
117
  ### Data flow
108
118
 
109
119
  ```
110
- HTTP request/response → interceptor → raw JSONL → processors → structured data → Web UI
120
+ HTTP request/response → interceptor → raw data (JSONL) → data processor → structured data → Web UI
111
121
  ```
112
122
 
113
123
  ## 📁 Project Structure
114
124
 
115
125
  ```
116
126
  ccdebug/
117
- ├── src/ # CLI & interceptors
127
+ ├── src/ # CLI and interceptors
118
128
  │ ├── cli.ts # CLI entry
119
129
  │ ├── interceptor.ts # API interception and tracelog recording
120
130
  │ ├── html-generator.ts # HTML report generator (based on frontend)
121
- │ └── index-generator.ts # conversation summaries and index
131
+ │ └── index-generator.ts # conversation summaries and index generation
122
132
  ├── web/ # Web timeline site (Vite + Vue 3)
123
133
  │ ├── src/ # frontend source
124
134
  │ ├── dist/ # build output
125
- │ └── server/ # Express backend (required by CLI to start)
135
+ │ └── server/ # Express backend (started by the CLI via require)
126
136
  ├── frontend/ # standalone HTML report frontend (bundle injected into HTML)
127
137
  ├── scripts/ # packaging scripts
128
- └── docs/ # docs and design notes
138
+ └── docs/ # documentation and design notes
129
139
  ```
130
140
 
131
141
  ## 🔧 Development
@@ -138,7 +148,7 @@ ccdebug/
138
148
  ### Local development
139
149
 
140
150
  ```bash
141
- # Clone
151
+ # Clone the repo
142
152
  git clone https://github.com/ThinkingBeing/ccdebug.git
143
153
  cd ccdebug
144
154
 
@@ -148,14 +158,14 @@ npm install
148
158
  # Build
149
159
  npm run build
150
160
 
151
- # Dev mode (watch core code + web frontend)
161
+ # Development mode (watch core code + frontend)
152
162
  npm run dev
153
163
 
154
- # Run CLI via tsx (for development/debugging)
164
+ # Run the CLI via tsx (for development debugging)
155
165
  npx tsx src/cli.ts --help
156
- npx tsx src/cli.ts --serve --port 3001 --project /path/to/your/cc_workdir
166
+ npx tsx src/cli.ts -l --port 3001 --project /path/to/your/cc_workdir
157
167
 
158
- # Package (artifacts will be placed under release/)
168
+ # Package after validation (artifacts will be under release/)
159
169
  npm run package
160
170
  ```
161
171
 
package/README.md CHANGED
@@ -1,23 +1,42 @@
1
1
  # CCDebug - Claude Code 调试工具
2
2
 
3
3
 
4
- CCDebug 是一个针对 Claude Code 的调试工具，用于记录并可视化 CC 运行轨迹，同时支持对单个 LLM 请求进行“修改-重放”，帮助你快速定位提示词/上下文/工具调用导致的偏差。本项目基于 [lemmy/claude-trace](https://github.com/badlogic/lemmy/tree/main/apps/claude-trace) 二次开发。
4
+ CCDebug 是一个针对 Claude Code 的调试工具，用于记录并可视化 CC 运行轨迹，同时支持对单个 LLM 请求进行“修改-重放”，帮助你快速定位提示词/上下文/工具调用导致的偏差。（本项目基于 [lemmy/claude-trace](https://github.com/badlogic/lemmy/tree/main/apps/claude-trace) 二次开发）
5
5
 
6
- 英文版：[README.en.md](./README.en.md)
6
+ [>>English README](./README.en.md)
7
7
 
8
8
  ## ✨ 主要功能
9
9
 
10
- ### 📊 时间线展示CC运行轨迹
11
- ![时间线展示CC运行轨迹](./docs/img/时间线.png)
12
- - **对话时间线**: 直观展示完整的对话流程和工具调用链
13
- - **按节点类型过滤**: 按不同类型的时间线节点过滤，如用户输入、LLM回复、工具调用等
14
- - **工具调用和结果整合展示**: 将工具调用和调用结果整合在一个节点展示，方便查看工具调用的输入参数和输出结果
15
- - **会话选择与子代理识别**: 支持主日志会话选择，子代理日志下拉框显示 agent 名称/描述
16
- - **项目切换**: Web 站点内可切换到 `~/.claude/projects` 下的其他项目，避免重复启动多个站点
10
+ ### **1、时间线展示轨迹**
11
+ - **按CC执行步骤显示**: 可以区分不同类型日志，用户输入、LLM回复、工具调用等
12
+ - **支持步骤详情**: 可以快速查看某一步的原始CC日志内容
13
+
14
+ ![时间线展示CC运行轨迹](./docs/img/1、日志以时间线形式展示.png)
15
+
16
+ ### **2、快速切换日志**
17
+ - **一键跳转SubAgent日志**: 一键跳转到子代理日志，方便查看子代理的运行轨迹
18
+ - **快速切换项目和会话**: 直接切换 `~/.claude/projects` 下的不同项目和会话，无需启动多次工具
19
+
20
+ ![快速切换项目和会话](./docs/img/2、快速切换项目和会话.gif)
21
+
22
+ ### **3、快速搜索定位**
23
+ - **全局搜索关键字**: 可以快速定位到包含指定关键字的日志（搜索当前会话下所有日志文件）
24
+ - **步骤概览过滤**: 步骤概览显示执行全貌，可按不同类型的时间线节点过滤
25
+ - **生成分享链接**: 可以生成当前会话的分享链接，方便多人协作分析
26
+
27
+ ![快速搜索定位](./docs/img/3、快速搜索定位.gif)
28
+
29
+ ### **4、快速分析耗时**
30
+ - **显示步骤开始时间**: 每个日志节点显示当前步骤的开始时间
31
+ - **显示工具调用耗时**: 对于工具调用、SubAgent执行的步骤，节点将显示调用耗时
32
+ - **统计步骤间耗时**: 用户可以标记2个步骤节点，共计自动计算并显示2个节点间耗时
33
+
34
+ ![快速分析耗时](./docs/img/4、快速分析耗时.gif)
35
+
36
+ ### **5、对CC步骤单点调试**
37
+ > 注意：调试功能仅支持NPM脚本形式安装的 Claude Code，不支持原生二进制版本。
17
38
 
18
- ### 🛠️ 对CC步骤单点调试
19
39
  ![对CC步骤单点调试](./docs/img/LLM请求调试.png)
20
- ![发送修改后的LLM请求](./docs/img/发送LLM请求.png)
21
40
  - **追踪LLM请求**: 详细记录CC对LLM的所有请求日志
22
41
  - **重新发送LLM请求**: 支持修改LLM请求数据，重新发送请求，方便反复验证LLM的响应是否符合预期
23
42
 
@@ -52,13 +71,13 @@ ccdebug --run-with -p "请按要求工作" --verbose
52
71
 
53
72
  ```bash
54
73
  # 启动 Web 服务器查看时间线（默认端口 3001，默认项目目录为当前目录）
55
- ccdebug --serve
74
+ ccdebug -l
56
75
 
57
76
  # 在自定义端口启动
58
- ccdebug --serve --port 3001
77
+ ccdebug -l --port 3001
59
78
 
60
79
  # 指定项目目录启动
61
- ccdebug --serve --project /path/to/your/cc_workdir
80
+ ccdebug -l --project /path/to/your/cc_workdir
62
81
  ```
63
82
 
64
83
  ### 日志输出目录
@@ -76,18 +95,13 @@ ccdebug --serve --project /path/to/your/cc_workdir
76
95
 
77
96
  | 选项 | 描述 |
78
97
  |------|------|
79
- | `--serve` | 启动 Web 时间线服务器 |
80
98
  | `--log, -l` | 启动 Web 时间线服务器（当 `--log` 不带参数时等同于 `--serve`；建议用 `-l` 避免与 `--log <name>` 混淆） |
81
99
  | `--port <number>` | 指定 Web 服务器端口（默认 3001） |
82
100
  | `--project <path>` | 指定项目目录路径 |
83
101
  | `--run-with <args>` | 将后续参数传递给 Claude 进程 |
84
102
  | `--include-all-requests` | 包含所有 fetch 请求，而不仅仅是对话 |
85
- | `--no-open` | 不在浏览器中自动打开生成的 HTML（当前仅对 `--generate-html` 生效） |
86
103
  | `--claude-path <path>` | 指定 Claude 二进制文件的自定义路径 |
87
- | `--log <name>` | 指定 API 跟踪日志基础名称（影响 `.claude-trace/tracelog/` 下文件名） |
88
- | `--generate-html <input.jsonl> [output.html]` | 从 JSONL 文件生成 HTML 报告 |
89
104
  | `--index` | 为 `.claude-trace/` 目录生成对话摘要和索引（会调用 Claude 产生额外 token 消耗） |
90
- | `--extract-token` | 提取 OAuth token 并退出 |
91
105
  | `--version, -v` | 显示版本信息 |
92
106
  | `--help, -h` | 显示帮助信息 |
93
107
 
@@ -149,7 +163,7 @@ npm run dev
149
163
 
150
164
  # 使用 tsx 直接运行 CLI（开发调试用）
151
165
  npx tsx src/cli.ts --help
152
- npx tsx src/cli.ts --serve --port 3001 --project /path/to/your/cc_workdir
166
+ npx tsx src/cli.ts -l --port 3001 --project /path/to/your/cc_workdir
153
167
 
154
168
  # 功能ok后打包，包会出现在release目录
155
169
  npm run package
package/dist/cli.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAyBA,eAAO,MAAM,MAAM;;;;;;CAMT,CAAC"}
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA2BA,eAAO,MAAM,MAAM;;;;;;CAMT,CAAC"}