ccdump

Wrap Claude Code and capture CLI Node process network traffic (HTTP/HTTPS/HTTP2/fetch), plus related ~/.claude context, into a shareable archive (.tar.gz by default).

适用场景：你遇到了 Claude Code 的可复现问题，想把“这一次会话发生了什么”完整交给他人 debug（同事、Anthropic 支持、issue 附件等）。
ccdump 在不改 ANTHROPIC_BASE_URL / 不装 CA 证书 / 不改系统代理的前提下完成抓取与打包。

目录

• 快速开始
• 打包产物
• CLI 选项
• 实现概要
• 隐私与脱敏
• 已知限制
• 开发
• License

快速开始

# 无需安装，直接用 npx 包装启动
npx ccdump [...你本来就会传给 claude 的参数]

# 例子
npx ccdump
npx ccdump --resume
npx ccdump -p "修一下这个 bug" ./some-file.ts

会话结束后（正常 /exit 或 Ctrl+C），cctracer 会自动：

1. 从 ~/.cctracer/sessions/<时间戳>/raw/ 聚合可读请求列表
2. 生成 traffic.har / requests.jsonl / summary.md
3. 扫描敏感字段（如 Authorization、sk-ant-...）并给出清单
4. 你确认后打包为 ~/.cctracer/sessions/<时间戳>.tar.gz（可切换为 zip）

打包产物

cctracer-<ts>.tar.gz   # 默认；可通过 --cctracer-zip 生成 .zip
├── meta.json            # Claude Code/Node/OS/启动参数/ANTHROPIC_BASE_URL/起止时间
├── summary.md           # 速览（状态码、模型分布、最慢 5 条、错误）
├── traffic.har          # 可直接拖进 Chrome DevTools Network 面板
├── requests.jsonl       # 每行一条完整 RequestRecord（保留 streaming chunk 时序）
├── requests-summary.json
├── raw/
│   └── <pid>-<n>.jsonl  # 最原始事件流；其余产物都由此派生
└── claude-bundle/       # 相关 ~/.claude 快照（标准集）
    ├── settings.json
    ├── settings.local.json
    └── projects/<encoded-cwd>/<sessionId>.jsonl

CLI 选项

cctracer 自有参数全部以 --cctracer- 开头，不会和 claude 参数冲突；其余参数原样透传给 claude。

| 选项 | 说明 | | --- | --- | | --cctracer-no-zip / --cctracer-no-archive | 会话结束后不生成压缩包（raw/ 仍保留） | | --cctracer-yes | 跳过敏感字段确认（CI / 非交互） | | --cctracer-out <path> | 自定义会话目录根（默认 ~/.cctracer/sessions） | | --cctracer-repack <dir> | 重用已有会话目录重新生成压缩包（不启动 claude） | | --cctracer-zip | 使用 .zip（默认是 .tar.gz） | | --cctracer-tar | 显式使用 .tar.gz（默认行为） | | --cctracer-help | 显示帮助 |

实现概要

Claude Code 现在发布为 Bun 编译的原生二进制（不是 Node 脚本），NODE_OPTIONS=--require 对主进程无效。
因此 cctracer 采用两条独立录制通道：

通道 1：本地转发代理（主通道，覆盖 LLM API 流量）

claude (Bun)
  ↓ http://127.0.0.1:<port>/<原 path>
cctracer 父进程本地 HTTP server
  ↓ https://<原 BASE_URL host>/<原 path>
真上游（api.anthropic.com / api.qnaigc.com / 兼容端点）

• 启动时从 user/project/local settings.json 和 process.env 解析真实 ANTHROPIC_BASE_URL（未配置则默认官方）
• spawn claude 时传入 --settings <overlay>，并同时改写 process.env.ANTHROPIC_BASE_URL 到本地代理（双保险）
• 代理在转发时将 request/response/SSE chunk 事件写入 raw/<reqId>.jsonl
• 不装 CA、不改系统代理、不动 HTTPS_PROXY，与 Clash Verge / OpenVPN 路由不冲突

通道 2：NODE_OPTIONS hook（补充通道，覆盖 Node 子进程）

spawn claude 时注入 NODE_OPTIONS=--require <hook.cjs>。
虽然 Bun 主进程不吃该变量，但 MCP 装包（npm exec / pacote）等场景会启动 Node 子进程，子进程会继承该 hook，覆盖：

• http.request / https.request / http.get / https.get
• http2.connect -> session.request
• globalThis.fetch（undici，借助 response.body.tee() 捕获 chunk 级时序）
• require('undici').fetch

事件格式

{"kind":"start",        "transport":"proxy|fetch|http|http2","method":...,"url":...,"headers":...,"body":...,"t":秒}
{"kind":"resp_headers", "status":...,"headers":...,"t":...}
{"kind":"chunk",        "idx":...,"bytes":...,"data":...,"t":...}
{"kind":"end",          "totalBytes":...,"t":...}
{"kind":"error",        "name":...,"message":...,"stack":...,"code":...,"t":...}

• t：相对 cctracer 启动时刻的秒数（process.hrtime.bigint()，纳秒精度）
• transport=proxy：来自通道 1
• transport=fetch|http|http2：来自通道 2（Node 子进程）

隐私与脱敏

默认是原样录制，不自动脱敏（因为 debug 时消息内容和 header 往往是关键信息）。
打包前会扫描已知敏感字段，并要求你确认：

发现敏感字段（压缩包中将保留原值，请确认后再分享）：

  [headers]  authorization         出现于约 142 个请求文件  示例: Bearer sk-ant-...
  [headers]  x-api-key             出现于约 142 个请求文件  示例: sk-ant-abc...
  [body]     Anthropic API key 形态 (body)  出现于约 2 个请求文件  示例: sk-ant-XYZ...

注意: 未将 /Users/…/.claude/.credentials.json 打入压缩包（OAuth 凭据）。

继续打包压缩包？
  > N — 不打包，保留 sessionDir 供稍后处理
    y — 原样打包（含上述敏感字段，默认输出 .tar.gz）
    edit — 逐项选择 keep/redact/drop 后再打包

edit 模式下，每个 finding 可选：

• keep：保留原值
• redact：替换为 ***REDACTED***
• drop：删除命中该项的请求文件

完成选择后，会重新生成 traffic.har / requests.jsonl / summary.md，再进行打包。

已知限制

• 通道 1 仅可见 ANTHROPIC_BASE_URL 流量；Claude Code 的遥测/更新检查/其他后台 HTTP（不走 BASE_URL）不可见
• 非 Node 的 MCP 子进程（如 Python）无法被通道 2 捕获
• 单请求响应体无硬上限，超大响应会消耗较多内存/磁盘
• Windows 未主动测试（理论跨平台，主目标为 macOS + Linux）

开发

npm test       # 单元 + e2e
npm run smoke  # 本地手动烟雾测试（需可 listen 127.0.0.1；macOS 沙盒可能 EPERM）

目录结构

cctracer/
├── bin/cli.js                 # ESM 入口
├── lib/
│   ├── orchestrator.js        # 父进程主流程
│   ├── proxy.cjs              # 通道 1：本地转发代理（覆盖 Bun 主进程）
│   ├── settingsResolve.js     # 解析 settings 链中的 ANTHROPIC_BASE_URL，生成 overlay
│   ├── hook.cjs               # 通道 2：子进程注入（覆盖 Node 子进程）
│   ├── recorder.cjs           # 共享写盘（父/子进程共用）
│   ├── replay.js              # raw/ -> RequestRecord[]
│   ├── argv.js                # --cctracer-* 参数解析
│   ├── paths.js               # ~/.claude/projects 目录名编码
│   ├── collectClaudeLogs.js   # 复制标准集到 sessionDir/claude-bundle
│   ├── sensitiveScan.js       # 扫描 + edit 模式的 redact/drop 写回
│   ├── rawSummary.js          # raw -> 人类可读列表（stderr）
│   ├── packager.js            # archiver 写压缩包（默认 tar.gz，可选 zip）
│   └── formats/
│       ├── har.js             # HAR 1.2
│       ├── jsonl.js           # 全保真 jsonl
│       └── summary.js         # summary.md
├── test/                      # node:test 单元 + e2e（含 e2eProxy.test.js）
└── docs/
    └── PLAN.md                # 设计决策、当前状态、待办

License

MIT