English | 简体中文

CCM — Claude Context Manager

一个代理 + Web UI 工具，用于实时查看、可视化和裁剪 Claude Code 的上下文窗口。

CCM 位于 Claude Code 和 Anthropic API 之间，拦截每个请求，让你清楚看到上下文窗口中的所有内容——并删除不需要的部分。

为什么用 CCM？

Claude Code 的上下文窗口是个黑盒——你无法看到发送给 API 的具体内容，不知道每个 turn 占了多少 token，也不清楚哪些工具调用在膨胀你的上下文。当上下文达到上限时，你对裁剪内容毫无控制权。

CCM 让不可见变为可见：

• 看到 Claude 所见 — 每一条 system prompt、消息、工具调用和子 agent 请求，都附带 token 计数
• 掌握控制权 — 在 Claude 自动压缩之前，手动删除特定 turn 以释放上下文空间
• 实时掌握用量 — token 用量实时分项展示，让你清楚预算花在了哪里
• 消除上下文污染 — 工具调用返回的大段无关内容、失败重试、废弃的探索方向会悄悄膨胀上下文。精准定位污染源，在它们挤占有效信息之前清除掉
• 零配置 — 一条命令启动，兼容现有的 Claude Code 环境

前置要求

• Node.js >= 18（需要 ES2022 模块支持）
• Claude Code 已安装并配置了有效的 ANTHROPIC_API_KEY
• C++ 编译工具，用于编译 node-pty：

| 平台 | 要求 | |------|------| | macOS | Xcode Command Line Tools — 运行 xcode-select --install | | Linux | build-essential 和 python3 — 运行 sudo apt install build-essential python3 | | Windows | Visual Studio Build Tools — 运行 npm install -g windows-build-tools |

提示： 如果全局安装 CCM 时遇到 node-pty 编译错误，安装上述工具几乎总能解决问题。

快速开始

git clone https://github.com/tigicion/ccm.git
cd ccm
npm install && cd ui && npm install && cd ..
npm run build
npm start

CCM 会在端口 4040 启动代理，在端口 4041 启动 Web UI，并通过代理启动 Claude Code。

工作原理

Claude Code CLI ──HTTP──▶ CCM Proxy (:4040) ──HTTPS──▶ Anthropic API
                              │
                         捕获请求体
                         应用删除集合
                         提取 token 用量
                              │
                         CCM Web UI (:4041)
                         ├── 终端 (xterm.js + PTY)
                         └── 上下文面板 (Vue)

1. CCM 设置 ANTHROPIC_BASE_URL，使 Claude Code 的请求经过本地代理
2. 代理捕获完整的请求体，并从响应流中提取 token 用量
3. Web UI 通过 SSE 实时展示上下文结构
4. 你可以选中并删除 turn，删除会在下一次 API 请求时生效

功能特性

• 上下文可视化 — 查看对话中的每个 turn、system prompt、工具调用和子 agent，附带 token 计数
• 用量仪表盘 — 实时 token 用量进度条，含 input / cache read / cache write / output 分项
• Turn 删除 — 选中并删除 turn 以缩减上下文，支持撤销
• 内嵌终端 — 通过浏览器内的 xterm.js 终端直接运行 Claude Code
• 多标签会话 — 同时打开多个 Claude Code 会话
• 子 Agent 追踪 — 内联监控子 agent 调用的状态和 token 用量
• 图片粘贴 — 在终端中直接粘贴截图，自动保存为临时文件传递给 Claude
• 自动重连 — 终端会话跨页面刷新持久化，WebSocket 自动重连

使用方法

# 默认：代理端口 4040，Web UI 端口 4041
ccm

# 自定义端口（代理 = 端口 - 1）
ccm --port 5000

# 显示帮助
ccm --help

环境变量

| 变量 | 说明 | 默认值 | |------|------|--------| | ANTHROPIC_API_KEY | Anthropic API 密钥（由 Claude Code 使用） | —（必需） | | CCM_UPSTREAM_URL | 上游 Anthropic API 地址 | https://api.anthropic.com | | ANTHROPIC_BASE_URL | 备选上游地址（CCM_UPSTREAM_URL 未设置时使用） | https://api.anthropic.com |

ANTHROPIC_API_KEY 由 Claude Code 自身读取，CCM 不直接使用。如果 Claude Code 在你的机器上已经可以正常工作，无需额外配置。

命令行参数

| 参数 | 说明 | 默认值 | |------|------|--------| | --port <number> | Web UI 端口（代理自动使用 port - 1） | 4041 | | --help, -h | 显示帮助信息 | — |

开发

npm run dev          # 后端 TypeScript 监听模式
cd ui && npm run dev # 前端 Vite 开发服务器

npm test             # 运行后端单元测试
cd ui && npx vitest run       # 运行前端组件测试
cd ui && npx playwright test  # 运行 E2E 浏览器测试

技术栈

| 层级 | 技术 | |------|------| | 代理 | Node.js HTTP server | | Web 服务 | Hono | | 前端 | Vue 3 + xterm.js | | 终端 | node-pty + WebSocket | | 构建 | TypeScript + Vite | | 测试 | Vitest + Playwright |

许可证

MIT