claude-web
heng1234/claude-web
Web UI for Claude Code CLI - token streaming, tool visualization, checkpoint, multi-session management
Instalação
npx convez-ai heng1234/claude-web1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Claude Code Web
一个给 Claude Code CLI 加可视化界面的 Web 应用。后端用 FastAPI 包装 claude -p --output-format stream-json,前端通过 SSE 流式渲染对话、工具调用、思考过程。
pip install claude-web-ui && claude-web
🔒 隐私说明:本工具只是
claudeCLI 的本地 GUI 包装器,不上传任何数据到第三方服务。所有对话、图片、会话历史都存在本机history/uploads/claude-web.db中。认证沿用你本地claude的登录态(~/.claude/),本工具不接触任何 API Key。
📸 截图
主对话界面

Token 级流式输出 & 工具调用可视化

Chrome MV3「选中即问」插件
网页选中文本或代码后右键让 Claude 解释、审查、改写或生成测试,结果在 Chrome Side Panel 流式展示。

使用统计面板

暗黑模式

✨ 特性
💬 对话
- Token 级流式输出(打字机效果)
- 多轮对话(基于
claude --resume) - 停止正在运行的任务
- 活跃会话保温:每个会话保留一个持久 claude 进程,后续轮次跳过冷启动和 MCP 握手(无 MCP 省 1-2s,重度 MCP 用户省 5-15s/轮)
- 跟进建议:回答后自动生成 3 个「你可能想继续问」的追问按钮
- 会话分叉:基于任意历史消息编辑 / 重新生成,原会话保留
- 思考动画:等待响应时用跳动圆点 + 扫光文字提示
📝 输入
- 文本 + 图片(文件选择 / 粘贴 / 拖拽),同一图片不会重复上传
- Chrome 选中即问插件:网页里选中代码/文字,右键让 Claude 解释、审查、改写或生成测试,结果直接显示在 Chrome Side Panel,并可一键转入完整 Web 会话
- 待发送图片缩略图点击放大预览,确认上传内容
- 文档上传:PDF / DOCX / XLSX / XLS / CSV / TSV / TXT / MD / JSON / LOG 自动提取文本作为上下文
- URL 自动检测:输入框里粘贴链接,发送时自动抓取网页正文
- 联网搜索开关:一键激活 WebSearch / WebFetch
@引用工作目录下的文件(↑↓ 选择)- Slash 命令菜单:输入
/弹出操作、重操作、内置模板和个人模板分组,支持 ↑↓ / Tab / Enter / Esc - 会话操作命令:
/new新建、/clear清空当前会话、/fork从最后一条用户消息分叉 - 重操作命令:
/compact用 Haiku 压缩旧历史并备份 JSONL,/init扫描项目生成CLAUDE.md草稿到输入框 - 内置模板命令:
/recap/test/explain/review/refactor/commit/docs - 自定义 Slash 模板:提示词模板可设置
slash_trigger,显示在「我的模板」分组 - Prompt 优化器:基于本地黄金样本库、好评 / 收藏候选和个人任务规则,生成轻度优化 / 专家模式 / 探索模式三档改写
- 本地优先的 Prompt 规则沉淀:按代码审查、Debug、产品方案、写作等任务类型自动分类,沉淀个人偏好规则,并在改写时解释用了哪些规则和相似样本
- Token 估算 + 草稿自动保存
- 提示词模板库(支持普通插入和 Slash 触发)
🎨 渲染
- Markdown + 代码高亮(highlight.js)
- 工具调用图标化(Bash / Read / Write / Edit 等)
- Edit 工具并排 diff
- Mermaid 图表 + LaTeX 公式
- 代码块一键运行:Python / JavaScript / Bash 现场执行,输出嵌在对话里
- 图片 Lightbox(点击放大)
- 代码块 / 全文一键复制
- 滚动控制:流式输出中手动往上滚不被打断,右下角浮动「跳到最新 ↓」按钮带新内容计数
🗂 会话管理
- 📌 置顶 / 📥 归档 / 🏷 标签
- CLI 会话 Tab:侧栏可直接切到「CLI」查看
~/.claude/projects/历史,会话标题优先显示真实用户消息,跳过 hook 注入噪音 - 🪄 AI 智能命名(让 Claude 给会话起标题)
- 双击标题重命名
- 搜索(标题 + 内容)
- 导出为 Markdown
- 会话 token 累计展示,长上下文时提示可用
/compact降低后续成本
🛡 安全 & 回滚
- 权限策略:自由 / 允许编辑 / 计划 / 只读 / 自定义工具列表
- 工具权限重试:当 Claude 因权限不足无法使用工具时,UI 弹出提示卡片,支持一键放行工具并重试本轮(无需切到 CLI)
- Git Checkpoint:每轮对话前自动
git stash create快照,一键回滚文件 - 编辑 / 重新生成:基于任意历史消息分叉新会话
- SSRF 防护:URL 抓取拒绝私网 / 本地主机
📋 TodoWrite 实时看板
- Claude 调用 TodoWrite 时右上角弹出任务面板
- 进度条 + 逐项状态(⬜ 待办 / ⏳ 进行中 / ✅ 完成)
- 多次 TodoWrite 调用自动队列回放,进度动画
- 面板可折叠 / 关闭
🔌 MCP Server 管理面板
- 可视化查看所有 MCP server(支持 user / local / project 三层 scope)
- 一键启用 / 禁用 / 删除
- 添加新 server(表单引导,支持 stdio 类型)
- 环境变量 / headers 自动脱敏显示(token/key/secret 只显示前 4 位)
- 支持
.mcp.json项目级配置 - 修改后新建会话即生效
🎓 上手 & 引导
- 首次启动 5 步交互引导:高亮 UI 控件 + 浮层 tooltip,半分钟学会主功能
- What's New 弹窗:升级到新版本后右下角提示新增/破坏性变更,纯修复版本只显示小红点不打扰
- 帮助面板(顶栏
?):快捷键速查 / 使用技巧 / 完整更新日志 / 一键重看引导 - 新会话空状态:4 张示例 prompt 卡片(代码审查 / 技术解释 / 写工具 / Mermaid)一键填入
📊 其它
- 模型切换(Opus / Sonnet / Haiku)
- 使用统计(总成本 / 每日成本柱图 / 工具使用排行)
- Git 状态栏(branch / dirty 文件数)
- 系统提示词自定义
- 暗黑模式
- 快捷键:
⌘K搜索 ·⌘N新会话 ·Esc关闭弹窗 / 引导 / 弹窗 - 浏览器通知 + 完成提示音
- 移动端响应式(侧栏可收起)
- IME 输入法兼容(中文拼音回车不误发)
🚀 快速开始
前置条件
- 已安装 Claude Code CLI:
npm install -g @anthropic-ai/claude-code claude # 首次登录 - Python 3.9+
安装
方式一:pip 安装(推荐)
pip install claude-web-ui
安装完成后一条命令启动:
claude-web
# 浏览器打开 http://127.0.0.1:8765
更新到最新版:
pip install --upgrade claude-web-ui
方式二:让 Claude Code 自己装 🎉
claude
进入交互模式后,把下面这段话丢给它:
帮我安装 claude-web-ui:pip install claude-web-ui,然后运行 claude-web 启动服务
💡 用 Claude Code 给 Claude Code 装一个 Web UI。
方式三:从源码安装
git clone https://github.com/heng1234/claude-web.git
cd claude-web
pip install -e .
claude-web
运行
claude-web # 默认 127.0.0.1:8765
claude-web --port 9000 # 自定义端口
claude-web --open # 启动后自动打开浏览器
claude-web --host 0.0.0.0 # 局域网共享
局域网共享(可选)
claude-web --host 0.0.0.0
⚠️ 别暴露到公网,本工具没有鉴权。
自定义端口
PORT=9000 python server.py
多窗口并行对话
直接在新浏览器标签页 / 窗口打开 http://127.0.0.1:8765,点「+ 新会话」即可并行对话。每个标签页独立,互不干扰。
Chrome 插件:选中即问
插件目前按 Chrome 开发者模式安装。pip install claude-web-ui 的用户不需要找源码仓库,Claude Web 设置页会直接显示插件目录,也可以下载 ZIP。
- 启动
claude-web,打开http://127.0.0.1:8765。 - 打开 Claude Web「设置」里的「浏览器插件」区域。
- 复制页面显示的插件目录,或点击「下载 ZIP」后解压。
- 在 Claude Web「设置」里点击「生成 Token」,复制生成的一次性 Token。
- 打开 Chrome
chrome://extensions,开启「开发者模式」。 - 点击「加载已解压的扩展程序」,选择插件目录或 ZIP 解压后的目录。
- 打开插件设置页,填写服务地址、Token、默认工作目录和权限模式。
- 在任意网页选中代码/文字,右键
Claude Code Web,选择解释、审查、改写或生成测试。
命令行也可以直接查看 pip 包里的插件目录:
claude-web --extension-path
# 或
claude-web-extension-path
源码开发时,插件目录仍然是仓库根部的 browser-extension/。
如果更新了插件代码,需要到 Chrome chrome://extensions 点一次「重新加载」,再刷新正在测试的网页。
插件默认在 Chrome Side Panel 里显示流式回答;需要长对话或查看历史时,点「在 Claude Web 中继续」会打开同一个会话。插件入口只支持 default / plan / readonly 三种权限模式,不会从插件侧启用 bypassPermissions。
常见问题
- 右键后没有反应:先到
chrome://extensions重新加载插件,然后刷新当前网页再试。 - 侧边栏提示未配置 Token:在 Claude Web 设置里重新生成 Token,粘贴到插件设置页并保存。
- 测试连接失败:确认
claude-web正在运行,插件服务地址和 Web 页面端口一致,例如http://127.0.0.1:8765。 - pip 用户找不到目录:在 Web 设置页复制「插件目录」,或者运行
claude-web --extension-path。
🔐 提交前敏感信息检查
仓库内置了 .githooks/pre-commit,会在 git commit 前扫描已暂存文件,重点拦截:
- 私钥块
- 常见平台 Token / API Key 模式
- 新增行里的
api_key/token/password/secret这类疑似敏感赋值
首次 clone 后执行一次:
git config core.hooksPath .githooks
手动检查当前文件也可以:
python3 scripts/check_sensitive_info.py --paths server.py static/index.html README.md
如果 hook 拦截了提交,先用 git diff --cached 看暂存内容,再决定是否移除或替换敏感信息。
🧩 技术栈
| 层 | 技术 |
|---|---|
| 后端 | Python 3.9+ · FastAPI · uvicorn · SQLite · pypdf · python-docx · openpyxl · xlrd |
| 前端 | 原生 JS · TailwindCSS · marked.js · highlight.js · Mermaid · KaTeX · Chart.js |
| 协议 | Server-Sent Events(流式输出)· stream-json stdin(多模态图片输入) |
| 依赖 | claude CLI(透过 subprocess 调用) |
📐 架构
浏览器 ──POST /api/chat──> FastAPI
└─ subprocess: claude -p [message | --input-format stream-json] \
--output-format stream-json \
--include-partial-messages \
[--session-id | --resume] \
[--permission-mode | --allowed-tools]
└─ stdout JSON lines ──SSE──> 浏览器渲染
- 会话 ID 首轮前端生成 UUID 通过
--session-id传入,后续用--resume --include-partial-messages开启 token 级流式- 图片输入走
--input-format stream-json+ stdin,base64 内联(跟 Anthropic API 多模态格式一致),而非通过 Read 工具间接读取,避免精度损失 - 每轮对话前若 cwd 是 git 仓库,执行
git stash create创建 checkpoint - 会话元数据存 SQLite(
claude-web.db),事件流存 JSONL(history/{session_id}.jsonl)
📁 项目结构
claude-web/
├── server.py # FastAPI 主服务
├── browser-extension/ # Chrome MV3 选中即问插件
├── static/
│ └── index.html # 单页前端
├── requirements.txt
├── screenshots/ # README 使用的截图
├── history/ # 会话事件 JSONL(运行时生成,gitignore)
├── uploads/ # 上传的图片/文档(运行时生成,gitignore)
├── claude-web.db # SQLite 会话元数据(运行时生成,gitignore)
└── .venv/ # 虚拟环境(gitignore)
🧰 API 端点速查
| 端点 | 方法 | 说明 |
|---|---|---|
/api/chat | POST | 主对话,SSE 流式返回 |
/api/chat/stop/{session_id} | POST | 停止正在运行的会话 |
/api/extension/status | GET | Chrome 插件检测服务和 token 状态 |
/api/extension/token | POST | 生成 / 重置浏览器插件 token |
/api/extension/ask | POST | 插件选中即问,SSE 流式返回并写入会话历史 |
/api/extension/stop/{session_id} | POST | 停止插件侧正在运行的会话 |
/api/extension/drafts | POST | 创建插件草稿并返回 Claude Web 打开链接 |
/api/extension/drafts/{id} | GET | Claude Web 读取插件草稿并自动填入 / 发送 |
/api/prompt-optimizer | GET | Prompt 优化器仪表盘:样本、规则、好评 / 收藏候选 |
/api/prompt-optimizer/samples | POST/DELETE | 手动维护黄金样本 |
/api/prompt-optimizer/samples/from-session | POST | 从当前会话或候选会话加入黄金样本 |
/api/prompt-optimizer/rules/{id} | PATCH | 启用 / 关闭个人 Prompt 规则 |
/api/prompt-optimizer/rewrite | POST | 生成轻度 / 专家 / 探索三档 Prompt 改写 |
/api/prompt-optimizer/feedback | POST | 记录复制 / 采用改写结果的反馈 |
/api/upload | POST | 上传图片 |
/api/upload-doc | POST | 上传文档(PDF / DOCX / XLSX / XLS / CSV / TSV / TXT / MD / JSON / LOG),自动提取文本 |
/api/exec-code | POST | 运行代码块(Python/JS/Bash,15s 超时) |
/api/fetch-url | POST | 抓取 URL 正文(带 SSRF 防护) |
/api/sessions | GET | 列出所有会话(含搜索 / 归档 / 标签) |
/api/sessions/search | GET | 搜索会话(@ 引用用) |
/api/sessions/{id} | GET/PATCH/DELETE | 查看 / 修改 / 删除会话 |
/api/sessions/{id}/clear | POST | 清空当前会话历史,保留本地 session id |
/api/sessions/{id}/compact | POST | 用 Haiku 压缩旧历史,备份原 JSONL 并重置远端会话缓存 |
/api/sessions/{id}/export | GET | 导出 Markdown |
/api/sessions/{id}/usage | GET | 查看当前会话 token / 成本累计 |
/api/sessions/{id}/mention | GET | 把会话内容整理成可引用上下文 |
/api/sessions/{id}/prepare-fork | POST | 创建分叉会话 |
/api/sessions/{id}/prepare-inline-edit | POST | 就地编辑历史消息并从该轮继续 |
/api/sessions/{id}/restore-checkpoint | POST | Git 回滚 |
/api/sessions/{id}/suggest-title | POST | AI 智能命名 |
/api/suggest-followups | POST | 生成跟进建议 |
/api/prompts | GET/POST/PUT/DELETE | 提示词模板 CRUD |
/api/prompts/search | GET | 搜索提示词模板(@ 引用和 Slash 自定义模板用) |
/api/projects/scan | POST | 扫描项目关键文件和目录结构,供 /init 生成 CLAUDE.md 草稿 |
/api/memories | GET/POST/PUT/DELETE | 持久记忆 CRUD(全局 / 项目 / 会话 scope) |
/api/memories/active | GET | 查看当前 cwd / session 生效的记忆 |
/api/memories/search | GET | 搜索记忆(@ 引用用) |
/api/stats | GET | 使用统计(成本 / 工具 / 每日) |
/api/git | GET | 当前目录 git 状态 |
/api/files | GET | 当前目录文件列表(@ 引用用) |
/api/cwds | GET | 最近用过的工作目录 |
/api/tags | GET | 所有标签统计 |
/api/mcp/servers | GET | 列出所有 MCP server(含 disabled / 多 scope) |
/api/mcp/servers/{name} | POST/PATCH/DELETE | 新增 / 修改 / 删除 MCP server |
/api/version | GET | 当前后端版本(前端用于检测升级) |
/changelog.json | GET | 更新日志(用于 What's New 弹窗 + 帮助面板) |
⚠️ 已知限制
- 权限审批是"失败后重试"模式:不是 Cursor 那种执行中实时弹窗。当 Claude 因权限被拒时,UI 会显示琥珀色提示卡片,用户点击「允许 xxx 并重试」后系统自动把工具加入白名单并重发本轮。体验上多等一轮(20-30 秒),但功能完整。真正的实时交互审批需自建 MCP 权限服务器或双向 stream-json 通信。
- Checkpoint 仅限 git 仓库:非 git 目录跳过(后续可加 tar 快照)。
- 分叉会话会打包上下文:编辑/重新生成时把历史作为前缀发给 Claude(可能多消耗 token)。
/compact会调用模型:压缩会话历史会额外调用一次 Haiku;原历史会备份到history/{sid}.before-compact-*.jsonl,并自动清理旧备份。/init不直接写文件:只把CLAUDE.md草稿 prompt 填入输入框,发送后由用户审阅再决定是否写入项目。- 无鉴权:仅供本地使用,不建议直接暴露公网。
- 代码块运行无沙盒:Python/JS/Bash 直接在本机跑,点运行前会二次确认。
- Claude CLI
-p模式流式局限:CLI 在非交互模式下会整段缓冲后一次性吐事件,token 流式是"视觉动画模拟",非真实 token 速率。
🗺 Roadmap
当前实现情况
已实现 ✅
- 多轮对话、停止生成、图片输入、工具调用可视化、思考过程展示
- 文档上传(PDF / DOCX / XLSX / XLS / CSV / TSV / TXT / MD / JSON / LOG)和 URL 自动抓取上下文
- 联网搜索开关、
@文件 / 会话 / 提示词 / 记忆引用、Token 估算、草稿自动保存、提示词模板库 - Slash 命令菜单(
/new/clear/fork/compact/init+ 内置 / 自定义模板) - Prompt 优化器(本地黄金样本库、按任务类型沉淀个人规则、相似成功样本、三档改写、一键采用)
- Chrome 选中即问插件(右键解释 / 审查 / 改写 / 生成测试,Side Panel 流式回答,可转入完整 Web 会话)
- Mermaid / LaTeX 渲染、图片 Lightbox、代码块复制与本地运行
- 会话置顶 / 归档 / 标签 / 搜索 / 导出 / 双击重命名 / AI 智能命名
- 历史消息就地编辑继续、重新生成分叉、Git checkpoint 回滚
- TodoWrite 实时看板、统计面板、Git 状态栏、暗黑模式、移动端侧栏
- 权限策略(CLI 默认 / 允许编辑 / 计划 / 只读 / 自定义工具)和权限失败后的本会话临时放行重试
- MCP Server 管理面板(多 scope 查看 / 启用 / 禁用 / 添加 / 删除 / 脱敏展示)
- 首次启动 5 步交互引导 + What's New 升级提醒 + 帮助面板(含完整更新日志)
- 稳定性硬化:SQLite WAL / SSE 断开清理子进程 / stderr 并发 drain / JSONL 原子写 / SIGTERM+SIGKILL 兜底
- 活跃会话保温(Warm Process Pool):持久 claude 进程复用,后续轮次跳过冷启动和 MCP 握手,空闲 90s 自动回收
- 启动检测 claude CLI、
--host非 localhost 警告、uploads/自动清理 > 30 天文件 - PyPI 发包(
pip install claude-web-ui)
部分实现 / 有限制 ⚠️
- 运行时交互式权限审批仍未实现;目前是预设策略 + 权限失败后重试
- 真正按模型原始速率的 token 级流式输出仍受 Claude CLI
-p模式限制 - Git checkpoint / 回滚仅适用于 git 仓库
- 代码块运行已实现,但无沙盒,只适合本机可信代码
待办
- Artifacts 侧边预览(HTML/React 实时渲染)
- 导入
~/.claude/projects/原生会话 - 基于 MCP 的真·交互审批
- 简单鉴权(Token / 密码)
- 内嵌终端(xterm.js)
- Projects 分组(跨会话共享上下文)
- 划选文字浮动工具栏
- 语音输入 / 朗读
💬 交流群
扫码加入微信交流群(二维码 7 天有效,6 月 21 日前有效,过期请提 Issue 提醒):
🤝 贡献
欢迎 Issue / PR。
👨💻 作者
heng1234 · CSDN 博客
📄 License
Apache License 2.0 — 见 LICENSE
🙏 致谢
- Claude Code — Anthropic
- FastAPI · TailwindCSS · marked · pypdf · python-docx · openpyxl · xlrd