[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-83151":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":14,"stars7d":16,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":17,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":15,"starSnapshotCount":15,"syncStatus":27,"lastSyncTime":28,"discoverSource":29},83151,"CcCompanion","CyberSealNull\u002FCcCompanion","CyberSealNull","Unofficial MIT-licensed iOS companion for Claude Code: self-hosted relay, local-first chat, search, and session control from your iPhone. Not affiliated with Anthropic.",null,"Swift",111,25,101,1,0,10,8,4.24,"MIT License",false,"main",true,[],"2026-06-12 02:04:31","# CcCompanion\n\n> 把 **Claude Code** 装进口袋。开源 iOS 客户端 + 一个小 Python 推送服务。完全跑在你自己的 Mac 跟你自己的手机上。\n\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-blue.svg)](LICENSE)\n\n**跟 Anthropic 无关。** \"Claude\" 跟 \"Claude Code\" 是 Anthropic PBC 的商标。详见 [`DISCLAIMER.md`](DISCLAIMER.md).\n\nEnglish: [README.en.md](README.en.md)\n\n---\n\n## 这是什么\n\nCcCompanion 两块:\n\n1. **`ios-app\u002F`** — SwiftUI 写的 iOS app (TestFlight 定向邀请, 后续上 App Store), 给你 chat \u002F terminal \u002F 斜杠命令三件套, 在 iPhone 上接你 Mac 那边的 Claude Code session, 走 overlay 网络任何地方都能用。\n2. **`apns-server\u002F`** — Mac 上跑的 Python HTTP 服务, 把你发的 chat 转给本地 `tmux` 里的 `claude`, 抓回复, 通过 Apple Push (或者 [Bark](https:\u002F\u002Fgithub.com\u002FFinb\u002FBark) 作零 Apple Developer 兜底) 推回你 iPhone。\n\n整套是 **local-first** — 你的消息不过我们的 server, 因为根本没\"我们的 server\"。家里那台 Mac 跟你 iPhone 走 Tailscale \u002F ZeroTier \u002F LAN 直连。\n\n## 它能做什么\n\n- **Chat** — iPhone 发一句, Claude Code 回的话推回来。streaming, 历史, 搜索, 跳消息, 收藏, 附件 (图片 \u002F 文件)。\n- **Terminal** — 内嵌你 Mac 那边 `tmux` 跑 `claude` 的 session, 点开看 \"claude 刚干了啥\", 不用回去解锁 Mac。\n- **斜杠命令** — `\u002Fnew`, `\u002Flist`, `\u002Fswitch \u003Csid>`, `\u002Fstop`, `\u002Fcompact`, `\u002Fclear`, `\u002Fhelp`. 多 session 跟随当前 active。\n- **多 endpoint** — 一个 app 配多个 server URL (Tailscale `100.x` + LAN `10.x` + localhost), 自动 ping 切活的。换 wifi 自动跟。\n- **轮询本地通知**: 轮询拉到新 assistant 消息时, app 可以触发一次本地 iOS 通知, 给那些只能镜像本地通知的眼镜跟周边设备用。默认开, 在\"设置\"里能关。\n- **远程 APNs push**: build 213+ 支持服务端 APNs 推送, app 完全后台或者手机锁屏也能收。前提是 app bundle 勾了 Push Notifications, 同时 Mac 端 server 配好了 APNs 凭证。build 212 及更早只走 app 内轮询加本地通知。\n- **实验性 feature flag**: 新功能或者风险大的功能先挂在\"设置\"里的开关后面, 默认关。工作群 view 就是这样, 默认关, 从\"设置\"里打开。\n- **Onboarding wizard** — 第一次启动 6 步走完 (server URL + secret + 头像 + 名字 + ping 测试)。\n- **主题** — 浅色 \u002F 深色 \u002F 暖色, 可跟随系统。\n- **隐私** — `config.toml` 跟 `.p8` 都 `.gitignore`-d, repo 只放 `config.example.toml` 模板。\n\n## 你需要\n\n- macOS 14 (Sonoma) 或更新, 装好 [Claude Code](https:\u002F\u002Fdocs.anthropic.com\u002Fen\u002Fdocs\u002Fclaude-code) 加 Anthropic Pro \u002F Max 订阅。\n- iPhone iOS 18+。\n- Tailscale \u002F ZeroTier \u002F 或者 iPhone 跟 Mac 一个 LAN 段就行。\n- 想走原生 APNs 推送需要 Apple Developer 账号 ($99\u002F年), 不想买就走 [Bark](https:\u002F\u002Fgithub.com\u002FFinb\u002FBark), 一样能收 push 通知。\n- **Xcode 16.3 或更新** (Swift tools 6.1+) 自行 build iOS app 时需要。GRDB 7.10.0 要求 Swift tools 6.1；旧版 Xcode (≤ 16.2) resolve 可能失败。TestFlight 安装不受此限制。\n\n## 快速开始\n\n最快路径: 复制 [`docs\u002FAI_GUIDED_SETUP_MAC.md`](docs\u002FAI_GUIDED_SETUP_MAC.md) 全文, 粘到你常用的 AI 助手 (Claude.ai \u002F ChatGPT \u002F Cursor \u002F Gemini 都行), 在最前面加一句:\n\n```\n请按下面这份 spec 一步一步引导我从零安装 ccc。\n```\n\nAI 会扮演引导员从 Phase A 走到 Phase I, 一步一步带你, 不堆问题不催。\n\n不想走 AI 引导也可以自己读:\n\n- **macOS** → [`docs\u002FAI_GUIDED_SETUP_MAC.md`](docs\u002FAI_GUIDED_SETUP_MAC.md) (也能给人类直接读, 双用)\n- **Windows (WSL2)** → [`docs\u002FSETUP_WIN_WSL2.md`](docs\u002FSETUP_WIN_WSL2.md)\n- **服务端细节** → [`docs\u002FSETUP_SERVER.md`](docs\u002FSETUP_SERVER.md)\n\niOS 端 TestFlight 当前定向邀请。邮件 [opia@starryfield.space](mailto:opia@starryfield.space) 或加微信 CyberSealNull 联系我加你 internal 组。\n\n## 架构\n\n```\n              ┌──────────────────────────┐\n              │  iPhone 跑 ccc app       │\n              └─────────────┬────────────┘\n                            │  HTTPS poll + APNs push\n                            │  (或者 Bark 兜底)\n              ┌─────────────▼────────────┐\n              │  Mac 跑 apns-server      │\n              │  (Python HTTP 服务)      │\n              └─────────────┬────────────┘\n                            │  tmux send-keys \u002F capture-pane\n              ┌─────────────▼────────────┐\n              │  tmux 里 session \"opia\"  │\n              │  └ claude (CLI agent)    │\n              └──────────────────────────┘\n```\n\n网络: app 跟 server 走 Tailscale \u002F ZeroTier \u002F LAN 通讯。默认 `config.toml` 绑 `127.0.0.1`, 你配好 overlay 网络 + auth secret 后再改 `0.0.0.0`。\n\n## 实验性 Feature Flag\n\nCcCompanion 里凡是改导航 \u002F 通知 \u002F 渲染 \u002F agent 工作流的新功能, 都应该先挂在\"设置\"里的 `@AppStorage` 开关后面。默认关, 除非这是兼容性修复或者安全修复。这样老用户升级不被打乱, 想试的本地用户自己打开。\n\n当前的 flag:\n\n- `feature_group_view`: 显示工作群 tab, 轮询 `\u002Fgroup\u002Fpoll` 拉多 agent 协作消息。\n\n## 仓库结构\n\n```\nCcCompanion\u002F\n├── README.md                    ← 你正在看这一份\n├── README.en.md                 ← 英文版\n├── LICENSE                      ← MIT\n├── DISCLAIMER.md                ← Anthropic 商标 disclaimer\n├── .gitignore                   ← 不入 git 的清单 (secrets \u002F logs \u002F build \u002F 用户数据)\n├── ios-app\u002F                     ← SwiftUI iOS app (Xcode 工程)\n│   └── CcCompanion\u002F           ← Xcode workspace 根; build scheme `CcCompanion`\n├── apns-server\u002F                 ← Python HTTP 服务 (push.py 是入口)\n│   ├── push.py                  ← 主 server\n│   ├── apns_client.py           ← Apple Push 封装\n│   ├── chat_history.py          ← chat 持久化\n│   ├── config.example.toml      ← 配置模板, copy 到 config.toml 改填\n│   └── …                        ← 其它 module 见\"服务模块\"段\n├── docs\u002F                        ← 安装指南 + Apple Developer p8 checklist + WSL2 流程\n└── cccompanion-docs\u002F            ← 历史 docs (legacy README \u002F DISCLAIMER 等) 保留参考\n```\n\n### 服务模块\n\nserver 拆成几个独立 `.py`。主要的:\n\n| 模块                | 干啥                                            |\n| ------------------ | ----------------------------------------------- |\n| `push.py`          | HTTP server 入口, 路由 handler, APNs 调度。      |\n| `apns_client.py`   | Apple Push HTTP\u002F2 客户端加 JWT 鉴权。            |\n| `chat_history.py`  | 消息日志 append-only + 搜索索引。                |\n| `token_store.py`   | 写接口鉴权 shared-secret 存储。                   |\n| `device_token_store.py` | iPhone APNs device token 持久化。            |\n| `jwt_helper.py`    | `.p8` 转 JWT 签名器。                             |\n| `task_queue.py`    | 后台任务池。                                     |\n| `usage.py`         | Anthropic 用量探针 (可选)。                       |\n\n其它模块 (`diary`, `favorites`, `group_chat`, `rp_history`, `studyroom`, `timeline`, `todos`, `worklog`, `reminders`, `calendar_store`, `pet_state`, `tts`, `settings`, `diary_stream`, `studyroom_indexer`) 是给私有客户端用的 endpoint, CcCompanion iOS app 不调它们。留在仓库里因为 `push.py` 引用了它们, 删模块会让 import graph 散架。你想拿这套 server 接你自己的客户端那些 endpoint 也能用, 但没文档支持, 当实验性看。\n\n## 自己 build iOS app\n\n不想等 TestFlight 也可以直接从源码 build:\n\n```bash\ncd ios-app\u002FCcCompanion\nopen CcCompanion.xcodeproj\n# Xcode 里 选 scheme \"CcCompanion\", configuration \"CcRelease\",\n#         挑你的签名 team, 接你 iPhone, 按 ⌘R.\n```\n\n你需要:\n\n- 改自己的 bundle id (默认 `com.example.cccompanion` 跟任何 Apple 签名的 app 都冲突, 不改装不上)。\n- 提供自己的 Apple Developer team 签名 (免费 personal team 可以装 7 天 dev build)。\n- 想走原生 APNs 的话, 给这个 bundle id 在 developer.apple.com 勾上 Push Notifications。server 端 config 里的 bundle id 必须跟它完全一致, 大小写也要对 (比如 `com.starryfield.cccompanion` 这种全小写)。\n- 在一台能被 iPhone 访问到的 Mac 上跑 `apns-server`, `config.toml` 填好。\n\n## 常见问题\n\n**问: 我的数据出 Mac 吗?**\n答: chat 内容跟历史留在你 Mac 上。server 推 push 通知时 title \u002F body 经过 Apple APNs (或者你选了 Bark 就经过 Bark relay)。chat **内容**不出机器, 只有通知预览过 Apple \u002F Bark。\n\n**问: 没 Apple Developer 账号能跑吗?**\n答: 能。`config.toml` 的 `[apns]` 段不填, 装 [Bark](https:\u002F\u002Fgithub.com\u002FFinb\u002FBark) 走 push。Bark 免费, 开源, 跟着作者的 relay 跑 (或者你自己部署一份 Bark)。\n\n**问: 8795 端口开到公网安全吗?**\n答: 别。后边挂 Tailscale \u002F ZeroTier \u002F 反向代理上 HTTPS, 加 auth secret。默认 `config.toml` 是 `host = \"127.0.0.1\"` 是有道理的。\n\n**问: 为啥 Xcode 工程在 `ios-app\u002FCcCompanion\u002F` 下?**\n答: 这是 CcCompanion 的公开 Xcode 工程。scheme、工程目录和 bundle id 已统一到公开名称。\n\n**问: 怎么更新?**\n答: `git pull`, 然后重 build iOS app, Mac 端重启 `apns-server` LaunchAgent: `launchctl unload ~\u002FLibrary\u002FLaunchAgents\u002Fcom.user.apns-server.plist && launchctl load ~\u002FLibrary\u002FLaunchAgents\u002Fcom.user.apns-server.plist`。\n\n## 贡献\n\nissue + PR 都欢迎。我们特别想要的:\n\n- Android 客户端 (跟 iOS endpoints 对齐, chat + terminal 流程平移过去)。\n- 反向代理 + HTTPS 配方 (Caddy \u002F Nginx \u002F Traefik)。\n- 更多语言 docs (这份 README 中英双版本, 但其它 docs 还偏英文)。\n- `apns-server\u002F` 里那批 CcCompanion 不用的 legacy 模块清理。\n\n提 PR 之前请:\n\n1. 跑 `xcodebuild -project ios-app\u002FCcCompanion\u002FCcCompanion.xcodeproj -scheme CcCompanion -configuration CcRelease -destination 'generic\u002Fplatform=iOS' build` 必须 SUCCEEDED。\n2. 跑 `python3 -m py_compile apns-server\u002F*.py` 不能报错。\n3. secrets \u002F `.p8` \u002F `config.toml` \u002F `tokens\u002F` \u002F `*.jsonl` 不能进 commit (`.gitignore` 已经挡了)。\n\n## License\n\n[MIT](LICENSE). 你想拿去干啥都行。如果它把你作业吃了那是你的事不是我们的。\n\n## 致谢\n\n- [Anthropic](https:\u002F\u002Fwww.anthropic.com) — Claude 跟 Claude Code。\n- [Apple](https:\u002F\u002Fwww.apple.com) — APNs 跟 TestFlight。\n- [Bark](https:\u002F\u002Fgithub.com\u002FFinb\u002FBark) — 极佳的零配置 push 兜底方案。\n- 所有测过 TestFlight 早期版本跟提过 bug 的人。\n","CcCompanion 是一个非官方的 iOS 伴侣应用，用于与运行在本地 Mac 上的 Claude Code 进行交互。其核心功能包括聊天、终端访问和斜杠命令执行，支持消息流式传输、历史记录搜索以及附件管理。该应用采用 SwiftUI 编写，并通过一个小的 Python 推送服务实现与本地 Claude Code 实例的通信，整个系统设计为 local-first，确保用户数据不经过第三方服务器。CcCompanion 适合那些希望在 iPhone 上远程控制或监视自己 Mac 上 Claude Code 会话的人使用，特别是在需要隐私保护和个人数据安全的场景下。此外，它还提供了多端点支持、本地通知轮询及可选的 APNs 推送等功能，以增强用户体验。",2,"2026-06-11 04:10:16","CREATED_QUERY"]