Professional local web console for Claude Code
English | 中文
基于官方 Agent SDK 随包的 Claude Code runtime,提供本地图形客户端。以对话为主界面:添加模型连接、提出任务、按需审批、查看改动;原生终端只作为设置里的排障入口。配置按所选来源和原生能力加载,完整覆盖状态见能力矩阵。
npx ccweb-console → 打开 http://127.0.0.1:3477,就这么简单。
终端里的 Claude Code 很强,但长会话缺一层图形化的管理与观测。ccweb 基于官方 Claude Agent SDK 驱动真正的 Claude Code 子进程,把这一层补齐。
| 功能 | 说明 | |
|---|---|---|
| 🔌 | 模型连接 | 图形化添加 Base URL / API Key / 模型 ID,保存到本机独立配置;可选的显式连通测试,按凭证、路径、限流、网络、协议分类提示;兼容旧模板只读合并 |
| 💬 | 完整对话 GUI | markdown + 代码高亮、thinking 折叠、消息分叉(fork)、重新生成 |
| 🔧 | 工具调用卡片 | Read/Grep 行号展示、Edit 行级 diff 预览(红删绿增)、Bash 输出 ANSI 着色、耗时统计 |
| 🔍 | 改动审查 | 在「本次改动」展开文件,查看 Edit / Write / MultiEdit 执行前后的磁盘差异。每轮最多采集 32 次,限当前工作区内不超过 64 KiB 的 UTF-8 文件。快照保存在本地,缺少快照时展示请求预览 |
| 🛡 | 可视化审批 | 允许、拒绝、停止,审批刷新后可继续;反问支持单选、多选和自由回答 |
| 📬 | 消息队列 | 生成中发送自动排队:可见、可撤销、成功结束后继续;中断或失败暂停,用户明确恢复 |
| 📊 | 实时指标 | 输入区下方低噪声摘要(输出速度 / 本轮耗时 / 上下文);原生耗时、配对请求、重试等进入诊断详情,不常驻主界面 |
| 🧭 | 上下文水位 | 原生上下文水位;累计 Token 用量与上下文占用分别展示 |
| 🗂 | 会话管理 | 跨工作区常驻置顶 / 搜索 / resume / fork / 改名 / 删除 / 拖拽排序 / 历史秒级回放与底部直达;工作区智能消歧与临时测试项目收纳;服务重启不自动重新执行未完成任务 |
| ⌨️ | 补全 | / 斜杠命令(含自定义 skills)、@ 工作区文件路径 |
| ⚙️ | 全图形设置 | 九类配置中心;Skills / Commands / 规则原生文件编辑、来源筛选、差异确认、冲突检测、备份;MCP / Hooks 配置与诊断 |
| 🌓 | 双主题 · 中英双语 | 默认跟随系统;进程内会话快照重建与请求回执 |
| ▣ | 原生终端(排障) | 从默认工作流移除,仅保留在「设置 → 关于与更新」;xterm + ConPTY、固定随包二进制、标签页能力令牌、断线恢复 |
| 💾 | 一键导出 | 完整对话含工具调用,导出 Markdown |
# Node 20+;SDK 自带 claude 二进制,无需单独安装 CLI
npx ccweb-console浏览器打开 http://127.0.0.1:3477。API 端点沿用环境里的 ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN,或在设置页切换已配置的端点模板——凭证不出本地。
从源码运行
git clone https://github.com/TimeCraker/ccweb && cd ccweb
pnpm install && pnpm build && node apps/server/bin/ccweb.mjspnpm dev # 并行起 server(3477) + web(5173, WS 代理)
pnpm check # lint + typecheck + test + build 质量门开发前端端口由 CCWEB_WEB_PORT 指定,默认 5173。用同一份环境启动前后端。若同时改了后端的 CCWEB_PORT,将 CCWEB_API_TARGET 指向对应的本机地址。
| 按键 | 动作 |
|---|---|
Ctrl+K |
命令面板(命令 / 会话 / 工作区) |
Ctrl+N / Ctrl+B |
新建会话 / 折叠侧栏 |
Ctrl+, |
设置 |
Esc |
中断生成 / 关闭弹层 |
Enter / Shift+Enter |
发送 / 换行(生成中 Enter = 排队) |
/ @ |
斜杠命令 / 文件路径补全 |
| 工作台 | 配置管理 |
|---|---|
![]() |
![]() |
截图来自 Stage 6.5 实际浏览器界面,TC 品牌与个人主站统一。运行和审批图使用明确标注的确定性 SDK 模拟,指标不代表真实模型表现;真实模型证据和限制见 产品诊断的 V2 验收。
Troubleshooting
- 换工作区后模型仍知道其他项目的内容:设置 → 运行与权限选择配置来源,原生
settingSources对新会话生效。空来源不等于安全沙箱;环境、登录、恢复历史等来源独立存在 - 会话列表为空:确认顶部工作区是实际跑会话的目录;Windows 路径已自动归一化
- 端口冲突:
CCWEB_PORT=3999 npx ccweb-console - 切换端点模板后不生效:端点设置对新会话生效,当前会话沿用启动时环境
相比 0.1.4 版本的重大升级:
- 生产力核心跃迁:
- Split Diff 并排代码比对:支持单列(Unified)与左右并排(Split)双模式渲染,行级精准对齐与独立水平平滑滚动,支持偏好持久化记忆。
- Plan 计划双向持久化:计划面板复选框与本地任务文档(
implementation_plan.md,SPEC.md等)原子写回双向同步,提供操作轻量实时反馈。 - Prompt 模板胶囊 (Snippets):内置常用开发者高频 Prompt(审查、单测、提交规范等),支持将自定义 Prompt 一键保存至本地。
- 文件树 Git 变动状态与路径快捷复制:文件树彩点呈现变动状态,标头支持一键复制相对/绝对路径。
- 长会话交互体验优化:
- 密集工具链智能折叠链 (Tool Chain Batching):连续出现的工具调用卡片默认聚合折叠展示总览与耗时;遇到异常或失败自动熔断展开。
- 长文本流式视口防抢占:流式生成期间手动向上滚动不被强制吸底;增设「回到底部」浮动快捷按钮与视口安全留白。
- 秒开直达底部:进入长历史会话自动定位至最新消息,彻底消除长会话加载初期的跳动与空白。
- 侧边栏跨工作区置顶与多会话并行感知:置顶核心会话,会话卡片实时呈现后台运行状态与计数气泡。
- 视觉系统全面矢量化:
- 全界面清退散落 Emoji,重构为统一规范的极简内联 SVG 矢量图标。
- 底部用量栏新增上下文容量占用率水位环与分级预警(80% 预警,90% 提示
/compact)。 - 温润卡片式代码块与伴侣抽屉自适应宽度拖拽支持。
- 工程健全与零构建分发:
- 严格精简发布包体积与文件白名单,
npx ccweb-console支持零构建纯净冷启动。
- 严格精简发布包体积与文件白名单,
MIT © TimeCraker
本项目为社区第三方工具,与 Anthropic 无关联;Claude 为 Anthropic 商标。
English | 中文
ccweb is a professional, open-source web console for Claude Code — built on the official Claude Agent SDK, it drives a real Claude Code runtime behind a full GUI. Configuration follows the selected native setting sources and runtime capabilities; an embedded native terminal carries TUI operations with explicit process ownership and version boundaries.
npx ccweb-console # Node 20+; bundles its own claude binaryOpen http://127.0.0.1:3477. Endpoint credentials come from your environment (ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN) or any configured template in Settings.
- 🖥 Full GUI — markdown + syntax highlighting, tool-call cards (Read/Grep with line numbers, Edit with line-level diff, ANSI-colored Bash output), collapsible thinking, fork & regenerate
- 🛡 Visual approvals — confirm dangerous actions in-app; AskUserQuestion as tab UI; reconnectable allow/deny controls and explicit interruption
- 📬 Message queue — queued, visible, cancelable; resumes after successful turns; interruption or errors pause the queue
- 📊 Live metrics — paired actual output tokens and output-phase duration, separate first-content latency and turn time; SDK costs are estimates
- 🧭 Context gauge & trajectory — usage ring with proactive warning above 85%; right-panel timeline of every tool call
- 🗂 Sessions — search / resume / fork / rename / delete / drag-reorder; history survives server restarts
- 🌓 Dark & light themes · bilingual UI (中文/English) · session snapshot reconstruction and command receipts
- ccweb 使用 SDK 随包运行时,不自动替换为本机 CLI。SDK 精确版本由 lockfile 和包清单共同锁定。
- 默认配置、运行指标、计划和私有临时目录保存在
~/.ccweb;CCWEB_HOME可覆盖。原生配置目录支持CLAUDE_CONFIG_DIR。 - 会话显式采用官方
claude_code系统提示预设,避免 SDK 精简默认值造成行为差异。 - 模型、权限支持原生热切;端点、effort、配置来源对新会话生效。界面同时保留默认值和当前会话快照。
- 自动模式按运行时、模型和账号支持情况确认;不映射为跳过审批。运行一切需明确开启,服务重启后恢复手动审批。
/plan、/model、/effort、/clear、/new、/settings、/mcp、/permissions、/memory、/context、/tasks、/rewind等对应 GUI 入口;发现的原生命令交给 SDK。登录与终端专属操作使用 ccweb 内的原生终端,账号授权仍需本人完成。随包二进制始终锁定,版本不符拒绝启动;升级须更新精确 SDK、能力矩阵与回归后重新安装/启动,不自动改全局 CLI。- 原生交互能够切换目录/恢复会话,因此 SDK 与原生执行在本服务整体互斥。启动 SDK 前还会核对原生后台会话,存在后台写入时要求先在 ccweb 内处理。
- 操作覆盖与未验项见 版本能力矩阵;执行状态见 A–G Spec。模拟测试、真实模型与人工视觉/登录验收分别记录,未验不计完成。
- 最新本地分发和真实验收见 Stage 6.7 同版本报告:A/B/C/D/G 关闭,E/F 人工与账号项保留;GLM 图片理解失败如实记录,不宣称无条件全功能等价。
- 费用为 SDK 估算,输出速度不包含请求之间的工具或审批等待。没有完整样本时不显示伪造数值;旧历史无统计时显示未记录。
- Dependabot 每周提出升级 PR;CI 验证契约、原生二进制、浏览器和实际 tarball 安装。配置提交到默认分支后才会在 GitHub 生效,不能保证未来任何上游版本自动兼容。
本地验证:pnpm check、pnpm --filter ccweb-console test:runtime、pnpm --filter @ccweb/web exec playwright test。后者包含明确标记的模拟 SDK 流程,不消耗模型额度。真实模型验收单独记录。



