claude-web-ui 1.5.2

Web UI for Claude Code CLI — token streaming, tool visualization, checkpoint rollback, multi-session management

Claude Code Web

一个给 Claude Code CLI 加可视化界面的 Web 应用。后端用 FastAPI 包装 claude -p --output-format stream-json，前端通过 SSE 流式渲染对话、工具调用、思考过程。

更新日志 · API 端点 · Roadmap

pip install claude-web-ui && claude-web

🔒 隐私说明：本工具只是 claude CLI 的本地 GUI 包装器，不上传任何数据到第三方服务。所有对话、图片、会话历史都存在本机 history/ uploads/ claude-web.db 中。认证沿用你本地 claude 的登录态（~/.claude/），本工具不接触任何 API Key。

📸 截图

主对话界面

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

Edit 工具并排 Diff

使用统计面板

暗黑模式

✨ 特性

💬 对话

• Token 级流式输出（打字机效果）
• 多轮对话（基于 claude --resume）
• 停止正在运行的任务
• 跟进建议：回答后自动生成 3 个「你可能想继续问」的追问按钮
• 会话分叉：基于任意历史消息编辑 / 重新生成，原会话保留
• 思考动画：等待响应时用跳动圆点 + 扫光文字提示

📝 输入

• 文本 + 图片（文件选择 / 粘贴 / 拖拽），同一图片不会重复上传
• 待发送图片缩略图点击放大预览，确认上传内容
• 文档上传：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，显示在「我的模板」分组
• Token 估算 + 草稿自动保存
• 提示词模板库（支持普通插入和 Slash 触发）

🎨 渲染

• Markdown + 代码高亮（highlight.js）
• 工具调用图标化（Bash / Read / Write / Edit 等）
• Edit 工具并排 diff
• Mermaid 图表 + LaTeX 公式
• 代码块一键运行：Python / JavaScript / Bash 现场执行，输出嵌在对话里
• 图片 Lightbox（点击放大）
• 代码块 / 全文一键复制
• 滚动控制：流式输出中手动往上滚不被打断，右下角浮动「跳到最新 ↓」按钮带新内容计数

🗂 会话管理

• 📌 置顶 / 📥 归档 / 🏷 标签
• 🪄 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 输入法兼容（中文拼音回车不误发）

---

🚀 快速开始

前置条件

1. 已安装 Claude Code CLI：

   npm install -g @anthropic-ai/claude-code
   claude  # 首次登录
   

2. 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，点「＋ 新会话」即可并行对话。每个标签页独立，互不干扰。

---

🔐 提交前敏感信息检查

仓库内置了 .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 主服务
├── 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/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 + 内置 / 自定义模板）
• Mermaid / LaTeX 渲染、图片 Lightbox、代码块复制与本地运行
• 会话置顶 / 归档 / 标签 / 搜索 / 导出 / 双击重命名 / AI 智能命名
• 历史消息就地编辑继续、重新生成分叉、Git checkpoint 回滚
• TodoWrite 实时看板、统计面板、Git 状态栏、暗黑模式、移动端侧栏
• 权限策略（CLI 默认 / 允许编辑 / 计划 / 只读 / 自定义工具）和权限失败后的本会话临时放行重试
• MCP Server 管理面板（多 scope 查看 / 启用 / 禁用 / 添加 / 删除 / 脱敏展示）
• 首次启动 5 步交互引导 + What's New 升级提醒 + 帮助面板（含完整更新日志）
• 稳定性硬化：SQLite WAL / SSE 断开清理子进程 / stderr 并发 drain / JSONL 原子写 / SIGTERM+SIGKILL 兜底
• 启动检测 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 天有效，5 月 28 日前有效，过期请提 Issue 提醒）：

🤝 贡献

欢迎 Issue / PR。

📄 License

Apache License 2.0 — 见 LICENSE

🙏 致谢

• Claude Code — Anthropic
• FastAPI · TailwindCSS · marked · pypdf · python-docx · openpyxl · xlrd