克劳德代码查看器

一款功能齐全的基于Web的克劳德代码客户端，提供完整的交互式功能来管理克劳德代码项目。您可以通过现代化的Web界面开始新对话、恢复现有会话、实时监控正在运行的任务，并浏览您的对话历史。

https://github.com/user-attachments/assets/090d4806-163f-4bac-972a-002c7433145e

简介

克劳德代码查看器是一款基于Web的克劳德代码客户端，专注于全面的会话日志分析。它通过严格的模式验证和渐进式展开的用户界面，在需要时才显示详细信息，从而保存并整理所有对话数据。

核心理念：零数据丢失 + 有效组织 + 远程友好设计

系统要求

• Node.js：版本 22.13.0 或更高
• 克劳德代码：v1.0.125 或更高
• 操作系统：macOS 和 Linux（不支持 Windows）

安装与使用

快速入门（CLI）

无需安装即可直接从 npm 运行：

npx @kimuson/claude-code-viewer@latest --port 3400

或者，您可以全局安装：

npm install -g @kimuson/claude-code-viewer
claude-code-viewer --port 3400

服务器将在端口 3400（或默认端口 3000）启动。在浏览器中打开 http://localhost:3400 即可访问界面。

可用选项：

claude-code-viewer [options]

选项：
  -p, --port <port>                监听端口（默认：3000）
  -h, --hostname <hostname>        监听主机名（默认：localhost）
  -v, --verbose                    启用详细调试日志
  -P, --password <password>        认证密码
  -e, --executable <executable>    克劳德代码可执行文件路径
  --claude-dir <claude-dir>        克劳德目录路径
  --api-only                       仅以 API 模式运行，无 Web UI

通过 Tailscale 的远程访问（移动端 / PWA）

克劳德代码查看器非常适合作为您从手机访问的持久化服务器。一种便捷的方式是在一台始终在线的机器上运行它，并通过 Tailscale 以 HTTPS 方式暴露：

1. 在您的 Tailscale 节点上设置 HTTPS，请参考 Tailscale HTTPS 证书指南。

2. 启动克劳德代码查看器，绑定到所有接口并设置密码：

   claude-code-viewer --hostname 0.0.0.0 --port 3400 --password your-secret
   

3. 从手机访问，使用 Tailscale 的 HTTPS URL（例如 https://your-machine.ts.net:3400）。

克劳德代码查看器是一个 PWA（渐进式 Web 应用程序）。在移动设备上，点击“添加到主屏幕”即可获得类似应用的体验，拥有优化的界面以及会话完成时的通知推送功能。

配置

命令行选项与环境变量

Claude Code Viewer 可以通过命令行选项或环境变量进行配置。命令行选项的优先级高于环境变量。

命令行选项	环境变量	描述	默认值
-p, --port <port>	PORT	Claude Code Viewer 运行的端口号	3000
-h, --hostname <hostname>	HOSTNAME	用于远程访问的监听主机名	localhost
-v, --verbose	—	启用详细调试日志。将详细的服务器端日志输出到标准错误流，便于排查问题。	（未设置）
-P, --password <password>	CCV_PASSWORD	身份验证密码。设置后，启用基于密码的身份验证，以保护对 Claude Code Viewer 的访问权限。所有 /api 路由（除登录、登出、检查、配置和版本端点外）都需要身份验证。若未设置，则禁用身份验证，应用程序可公开访问。	（无）
-e, --executable <executable>	CCV_CC_EXECUTABLE_PATH	Claude Code 安装路径。若未设置，则使用系统 PATH 中的安装路径，或回退到依赖项中打包的版本。	（自动检测）
--claude-dir <claude-dir>	CCV_GLOBAL_CLAUDE_DIR	存储会话日志的 Claude 目录路径。	~/.claude
--terminal-disabled	CCV_TERMINAL_DISABLED	设置为 1/true（环境变量）或存在该标志（命令行）时，禁用应用内的终端面板。	（未设置）
--terminal-shell <path>	CCV_TERMINAL_SHELL	终端会话使用的 Shell 可执行文件（例如 /bin/zsh）。	（自动检测）
--terminal-unrestricted	CCV_TERMINAL_UNRESTRICTED	设置为 1（环境变量）或存在该标志（命令行）时，禁用 Bash 的受限 Shell 标志。	（未设置）
--api-only	CCV_API_ONLY	以仅 API 模式运行。禁用 Web UI、终端 WebSocket 和非必要端点。仅暴露核心 API 路由（/api/version、/api/config、/api/projects、/api/claude-code、/api/search、/api/sse）。适用于与 n8n 等外部工具集成。	（未设置）

重大变更：环境变量名称已更改。如果您正在使用环境变量，请按以下方式更新：

• CLAUDE_CODE_VIEWER_AUTH_PASSWORD → CCV_PASSWORD
• CLAUDE_CODE_VIEWER_CC_EXECUTABLE_PATH → CCV_CC_EXECUTABLE_PATH
• 新增环境变量：CCV_GLOBAL_CLAUDE_DIR（此前 Claude 目录路径硬编码为 ~/.claude）

API 身份验证

当设置了 --password / CCV_PASSWORD 时，所有 /api 路由（除身份验证相关端点外）都需要身份验证。您可以通过两种方式进行身份验证：

1. 会话 Cookie：使用 /api/auth/login 端点设置 ccv-session Cookie，然后在后续请求中包含该 Cookie。
2. Authorization 头部：在每个请求中发送 Authorization: Bearer <password>。

如果未配置密码，则禁用 API 身份验证。

用户设置

可以在 Claude Code 查看器的侧边栏中配置设置。

设置	默认	描述
隐藏无用户消息的会话	true	Claude Code 会为 /compact 等不与实际任务相关的操作创建日志，这可能会产生干扰。启用后，将隐藏没有用户消息的会话。
合并同名会话	false	恢复会话时，Claude Code 会创建一个带有重新生成对话记录的新会话。启用后，仅显示最新的一次同名会话。
自动安排限流继续	false	当 Claude 达到速率限制时，自动安排一条“继续”消息。启用后，系统会在实时会话中检测到速率限制错误，并创建一个计划任务，在限流重置时间后一分钟发送“继续”消息。这样可以避免手动干预来恢复速率限制。
回车键行为	Shift+Enter	指定使用哪种键组合发送消息。选项包括 Enter、Shift+Enter 和 Command+Enter。
搜索快捷键	Command+K	选择用于打开搜索对话框的快捷键。选项包括 Ctrl+K 和 Command+K。
查找快捷键	Command+F	选择用于打开页面内查找栏的快捷键。选项包括 Ctrl+F 和 Command+F。
模型选项	default, haiku, sonnet, opus	自定义在会话选项工具栏中显示的模型选项列表。可添加 Claude Code 支持的任何模型标识符（例如 claude-opus-4-5）。
权限模式	请求权限	控制 Claude Code 请求工具调用时的批准逻辑。可通过聊天输入上方的会话选项工具栏按项目进行配置。需要 Claude Code v1.0.82 或更高版本。
主题	System	在深色模式和浅色模式之间切换。默认跟随系统设置。
通知	None	在运行中的会话进程完成时启用声音通知。可选择多种通知音效，并具有试听功能。
语言	System	界面语言选择。支持英语、日语和简体中文，并可自动检测系统语言。

环境变量

CCV_ENV 注意事项: 如果您在环境中设置了 CCV_ENV=development，应用程序将以开发模式启动。对于生产环境，请设置 CCV_ENV=production 或将其保持未设置状态。

功能

功能	描述
查看聊天记录	通过网页界面实时查看 Claude Code 会话日志。由于使用标准的 Claude Code 日志（~/.claude/projects/...）作为数据源，因此也支持历史日志。
搜索对话	使用 ⌘K（macOS）或 Ctrl+K（Linux）在所有对话中进行全文搜索。可在特定项目内或跨所有项目搜索。支持模糊匹配、前缀搜索以及键盘导航（上下键切换，回车键选择）。
页面内查找	使用可配置的快捷键（Ctrl+F / Command+F）跳转到当前对话中的任意文本。可通过键盘导航循环浏览所有匹配项。
开始对话	直接从 Claude Code Viewer 中启动 Claude Code 会话。享受文件/命令补全、暂停/恢复、工具审批等核心功能，并获得更优质的网页体验。
继续会话	直接从现有会话日志中继续对话。
持续会话	Claude Code Viewer 提供高级的会话流程控制。通过 Claude Code Viewer 启动的会话将保持活跃状态（除非被中止），允许您无需重新开始即可继续对话（不会重新分配会话 ID）。
创建项目	从 Claude Code Viewer 中创建新项目。通过网页界面选择目录，执行 /init 命令并开始项目设置。
会话选项工具栏	聊天输入框上方的内联工具栏，用于配置每个项目的会话选项：模型选择、思考力度（低/中/高/最大）、权限模式和系统提示预设。这些设置将按项目持久化保存。
语音输入	使用内置的语音输入按钮直接在聊天输入框中口述消息。转录后的文本会插入到输入框中，供您在发送前检查。
文件上传与预览	可直接从聊天界面上传图片（PNG、JPEG、GIF、WebP）、PDF 和文本文件。每种文件类型都会显示专用的预览组件——图片内嵌显示，PDF 嵌入查看器，文本文件则以格式化内容呈现。
剪贴板粘贴图片	使用 Ctrl+V / ⌘+V 直接从剪贴板将图片粘贴到聊天输入框中。粘贴的图片会被附加并在发送前预览。
聊天草稿保存	聊天输入草稿会按项目和会话自动保存。返回同一对话时，未发送的文本将被恢复。
浏览器预览	直接在 Claude Code Viewer 中预览 Web 应用程序。点击聊天消息中任何 URL 上的预览按钮，即可在右侧打开一个可调整大小的浏览器面板。功能包括键盘导航的 URL 输入、刷新功能以及聊天窗口宽度的自动调整。嵌入式浏览器会跟踪您导航时的 URL 变化（仅同源）。
消息调度	使用 Cron 表达式安排 Claude Code 消息，用于重复任务或指定时间的一次性执行。支持并发控制（跳过/执行）的周期性任务，以及预留任务的自动删除。
审查更改	内置的 Git Diff 查看器让您直接在 Claude Code Viewer 中审查所有更改。支持内联差异评论，以便标注特定行。
提交更改	直接从网页界面的 Git Diff 查看器中执行 Git 提交。
推送更改	直接从 Git Diff 查看器中推送已提交的更改。支持单独的推送操作，也支持合并提交与推送的工作流，以实现更流畅的部署。
分支切换器	直接从 Git 选项卡中切换本地 Git 分支（带有搜索和状态指示器）。
资源管理器	右侧面板选项卡汇总了已编辑的文件及操作按钮，按项目分组，列出工具调用并提供筛选和快速文件预览，同时在专门的部分显示代理子会话。
工具可视化显示	工具调用会以专用的可视化组件呈现（如文件差异、结构化输出）。必要时，可通过“原始”切换按钮切换到纯 JSON 视图。
待办事项查看器	从会话中提取最新的 TodoWrite 事项，并将其作为内联可折叠清单直接显示在对话中。
PR 链接显示	从 pr-link 日志条目中提取的拉取请求元数据（标题、编号、URL）会在对话中以富卡片形式呈现，方便您轻松导航到相关 PR。
复制按钮	每条 Markdown 消息都包含一个复制按钮，只需单击即可将完整文本内容复制到剪贴板。
项目切换器	通过页眉中的下拉框快速跳转到任意项目，无需返回项目列表。
内联审批	来自 CCVAskUserQuestion MCP 工具的工具权限请求和自定义问题会以内联面板的形式直接显示在聊天中，无需切换到其他窗口进行审批。
终端面板	底部面板中的 WebSocket 终端，可在不离开 UI 的情况下运行 Shell 命令。
MCP 服务器查看器	在会话侧边栏中直接查看 MCP 服务器配置。列出所有已配置的服务器及其名称和命令，并支持实时重新加载。
PWA 支持	将 Claude Code Viewer 作为渐进式 Web 应用安装到桌面或移动设备上。支持添加到主屏幕以及会话完成事件的推送通知。
系统信息	监控 Claude Code 和 Claude Code Viewer 的版本、功能兼容性以及系统状态。
多语言支持	全面的国际化支持，提供英语、日语和简体中文语言选项。

截图

功能	截图
BasicChat（桌面版）
BasicChat（移动版）
浏览器预览（右侧面板）
Git 选项卡（右侧面板）
审查面板（右侧面板）
文件差异（右侧面板）
设置
开始新聊天
项目列表
新项目模态框
命令补全
文件补全
差异查看器

注：更多 UI 截图可在 /e2e/snapshots/ 中找到。

数据来源

该应用从以下位置读取 Claude Code 对话日志：

• 位置：~/.claude/projects/<project>/<session-id>.jsonl
• 格式：包含对话条目的 JSONL 文件
• 自动检测：自动发现新项目和会话

国际化 (i18n)

Claude Code Viewer 目前支持 英语、日语 和 简体中文。添加新语言非常简单——只需为您的本地化环境添加一个新的 messages.json 文件（请参阅 src/i18n/locales/ 中的示例）。

如果您希望支持您的语言，请提交一个问题，我们将尽快添加！

替代方案与差异化

官方解决方案：Claude Code on the Web

Anthropic 提供了 Claude Code on the Web，它在 Anthropic 的云虚拟机中运行 Claude Code 会话。每个会话都会克隆您的仓库并执行预定义的设置命令（例如 pnpm install）。

何时使用 Claude Code on the Web：

• 无需本地设置或自托管基础设施即可快速测试
• 从移动设备或公共计算机进行随意开发
• 根目录下只有一个 CLAUDE.md 文件的简单仓库结构

何时使用 Claude Code Viewer：

• 处理预先配置的本地环境（数据库、服务、大型依赖项）
• 具有多份 CLAUDE.md 文件且分布在不同目录下的 monorepo 项目
• 需要大量计算资源或长时间运行进程的开发工作
• 偏好自托管基础设施，以便完全控制开发环境

社区 Web 客户端

目前存在多个优秀的社区开发的 Web 客户端：

• https://github.com/sugyan/claude-code-webuisupport
• https://github.com/wbopan/cui
• https://github.com/siteboon/claudecodeui

Claude Code Viewer 的独特之处：虽然这些工具作为通用型 Web 客户端表现出色，但 Claude Code Viewer 专门设计为一款 会话日志查看器，具备以下特点：

• 信息零丢失：通过严格的 Zod 模式验证，确保每一条对话细节都被完整保留。
• 渐进式信息展示：可展开的内容和子会话模态窗口有助于管理信息密度。
• 内置 Git 操作：提供全面的差异对比视图，并支持直接提交代码，适用于远程开发工作流。
• 会话流程分析：能够跨多个会话完整追踪对话过程。
• 系统监控：实时监控版本及功能兼容性。
• 国际化支持：多语言界面，便于全球开发团队使用。

每款工具都有其适用场景，请根据您的工作流和优先级选择最适合的一款。

远程开发

Claude Code Viewer 在设计时充分考虑了远程托管的需求。为了更好地支持远程开发工作流，它提供了以下功能：

• 移动端优化的 UI：响应式界面，配备专用的移动端侧边栏和触控优化的操作控件。
• 内置 Git 操作：可以直接在 Web 界面中查看并提交更改。
• 实时通知：任务完成后会发出音频提示，帮助开发者保持对工作流的关注。
• 系统监控：可在不同环境中监控 Claude Code 的兼容性和功能可用性。

该应用采用客户端-服务器分离的架构，支持远程托管。基础密码认证功能已实现，可通过 --password 命令行选项或 CCV_PASSWORD 环境变量进行配置。启用后，用户需输入预设密码才能访问应用。不过，这仅是一种简单的单密码认证机制，不具备多用户支持、基于角色的访问控制或 OAuth 集成等高级功能。如果您需要更复杂的认证方式，请仔细评估安全需求，并在基础设施层面实施相应的访问控制措施（例如，使用带有 OAuth 的反向代理、VPN 或 IP 白名单）。

隐私

有关隐私和网络通信的信息，请参阅 PRIVACY.md。

许可证

本项目采用 MIT 许可证开源。

贡献

详细的开发环境搭建和贡献指南请参阅 docs/dev.md。

Claude Code Viewer 快速上手指南

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：macOS 或 Linux（不支持 Windows）。
• Node.js：版本需为 22.13.0 或更高。
• Claude Code：版本需为 v1.0.125 或更高。

提示：国内用户若下载 Node.js 较慢，推荐使用 cnpm 镜像源或从 Node.js 中文镜像站 下载安装包。

安装步骤

您可以选择无需安装的临时运行方式，或全局安装以便长期使用。

方式一：直接运行（推荐尝试）

无需预先安装，通过 npx 直接启动最新版本的服务器：

npx @kimuson/claude-code-viewer@latest --port 3400

方式二：全局安装

将工具安装到全局环境，方便随时调用：

npm install -g @kimuson/claude-code-viewer

加速建议：如果 npm 安装速度慢，可先切换至国内镜像源：

npm config set registry https://registry.npmmirror.com

基本使用

1. 启动服务

安装完成后（或使用 npx 时），在终端执行以下命令启动 Web 服务器。默认端口为 3000，此处指定为 3400 以避免冲突：

claude-code-viewer --port 3400

若需远程访问或设置密码保护，可使用如下命令：

claude-code-viewer --hostname 0.0.0.0 --port 3400 --password your-secret

2. 访问界面

打开浏览器，访问本地地址：

http://localhost:3400

您将看到现代化的 Web 界面，在此可以：

• 开启新的对话会话。
• 恢复正在运行或历史的任务。
• 实时监控任务执行日志。
• 浏览和管理所有会话记录。

3. 移动端使用 (PWA)

该工具支持渐进式 Web 应用 (PWA)。在手机浏览器访问服务器地址后，点击“添加到主屏幕”，即可获得类似原生 App 的体验，并支持任务完成时的推送通知。