项目总览
定位、适用场景、技术栈与仓库形态。
项目面向已经在终端使用 claude CLI 的开发者：在手机上与同一个 Agent 对话交互，体验与效果完全等同于坐在电脑前操作终端。
一句话定位
移动端聊天式 Web UI，通过官方 @anthropic-ai/claude-agent-sdk 驱动本机已登录的 claude CLI。项目不打包独立的模型后端，不另搞平行的 Agent 逻辑；无缝继承同一套 CLAUDE.md、MCP 工具、自定义 Skills、Hooks 以及本地会话历史（Transcripts）。
核心适用场景
- 长耗时任务在后台跑，人离开电脑。终端执行中的工具审批、人机提问和后台子代理完成事件实时推送到手机通知栏，轻点即可放行或驳回。
- 同一会话，跨设备无缝续接。手机端与终端基于同一份本地 CLI Transcript 会话记录流转；在路上掏出手机起头，回到办公室敲
claude --resume即刻连上。 - 多项目工作区快速切换。基于严格的工作区路径白名单，支持在多个本地 Git 仓库或 Worktree 之间一键切换并并发监视进展。
- 原生触控与移动端优化。专为触屏调优的输入框、斜杠命令面板（
/菜单）、相册图片直传、长按快捷操作与代码块折叠，而不是机械地缩放终端窗口。
如果只是偶尔临时查看电脑屏幕，远程桌面已足够。Claude Chat Mobile 面向的是「将移动端打造成电脑 CLI 随身等价入口」的高频生产力需求。
技术栈与基础选型
运行时
Node ≥20 · ESM 规范 · Express 5 · Socket.IO 4 · compression
Agent 驱动
@anthropic-ai/claude-agent-sdk 0.3.263 · 本机 claude CLI鉴权 / 推送
jose 6（JWT 验证）· web-push（VAPID 协议）· 可选 ntfy前端架构
原生 ESM PWA 架构；依赖完全本地自托管（Tailwind / marked / highlight.js / DOMPurify）
测试体系
内置
node --test（S0–S7 执行槽分层）· Playwright 移动端 UI E2E · 容器沙箱 HOME 隔离配置管理
ccm.config.json（结构化配置，支持工作区热重载与统一 Schema）开源许可
AGPL-3.0-only · NOTICE 补充条款（严守自托管权益）
仓库结构与代码地图
| 目录路径 | 职责范围 | 关键约束 |
|---|---|---|
app/server.js | 运行时启动入口 | 薄封装：加载环境变量、注入安全时戳并引导 app/src/server/app.js |
app/src/ | 服务端业务域 | 按域严密分层（agent, sessions, server, auth, files, ops, shared） |
app/public/ | 前端 PWA 界面 | 纯静态无打包构建，静态资源与 logic 纯函数与后端零构建同源复用 |
scripts/ | 维护者与装机工具 | setup.js、doctor.js、config.js、device.js、release.sh |
desktop/ | macOS 状态栏应用 | 原生 Swift 状态栏菜单栏工具（CCM.app）与 LaunchAgent 模板 |
tests/ | 测试体系唯一根目录 | unit/、invariants/、integration/、e2e/、gates/、infra/ |
docs/ | 架构真相源文档 | architecture.md、hard-rules.md、testing.md、display-contracts.md |
架构脆弱点警示：项目根路径计算
app/src/** 下计算项目根目录必须向上穿透三层（如 app/src/server/app.js 或 app/src/shared/data-dir.js）。因为 data/、scripts/ 与 ccm.config.json 位于仓库顶级根目录，若少算一层会导致数据和配置文件静默解析到 app/ 目录下且毫无报错。
分支纪律与工作流
- dev：日常开发与新特性主干，日常改动一律在 dev 上进行。
- master：生产稳定分支与 GitHub 默认分支，受分支保护。仅在发版时通过
scripts/release.sh执行 fast-forward 合并与分发裁剪。 - gh-pages：独立展示与全景手册分支，纯静态产物托管。
- promo：宣发文案创作工作区，非源码逻辑。
装机与运行前置条件
- Node.js 运行环境。需 Node ≥20（推荐 LTS 版本），纯 ESM 模式运行。
- 本机可用且已登录的 claude CLI。执行
which claude确认命令可寻址，且能在本地终端正常交互。 - Anthropic 订阅或 API 凭据。使用官方订阅沿用 CLI 登录凭据；如使用第三方网关，必须在启动 server 的 shell 中
export ANTHROPIC_*。写入配置文件（无论是ccm.config.json还是.env）都会在启动期被无条件剥除并告警，以确保配置文件不压过 shell 中的 provider 凭据（遵循终端等价性）。 - 操作系统支持。以 macOS（原生支持桌面菜单栏 CCM.app 与 launchd）和 Linux（systemd / Docker）为一等支持平台。