# code-notch

**Repository Path**: fa0/code-notch

## Basic Information

- **Project Name**: code-notch
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-10
- **Last Updated**: 2026-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CodeNotch

本地优先的 macOS 顶部 Dynamic Island 风格状态栏小窗。常驻顶栏、鼠标悬停展开,显示当前活跃的 coding agent 会话,点击跳回对应宿主(终端 tab 或 IDE)。

支持的 agent: **Claude Code CLI / Claude Desktop（含 Cowork）** / **Cursor IDE** / **OpenAI Codex**。对标 [Vibe Island](https://vibeisland.app/)。

## 仓库结构

按 **agent / server / client** 三层组织:

```
.
├── agent/                     # Mac 端 (产品本体)
│   ├── CodeNotch/             # macOS app 源码
│   ├── CodeNotch.xcodeproj/   # Xcode 工程
│   ├── scripts/               # 打包 / 公证 / OTA 发布脚本
│   ├── docs/                  # agent 技术文档
│   ├── Version.xcconfig       # 版本号唯一来源
│   └── appcast.xml            # Sparkle OTA feed
├── server/                    # 远程推送 server (可选,内置 web dashboard)
│   └── public/                # 浏览器 dashboard
├── client/                    # 远端客户端
│   ├── ios/                   # iPhone app (dashboard 的 SwiftUI 重写)
│   └── firmware/              # 桌面摆件固件 (ESP32-S3 / 黄山派)
├── AGENTS.md                  # 总入口:仓库分层、跨层契约、通用工作流
└── README.md
```

三层各自独立:**agent** 是产品本体,单独用就够;**server** 是可选远端通道;**client** 是接在 server 上的远端查看/操作端。浏览器 dashboard 由 server 内置直出(`server/public/`),不在 `client/` 下。

---

## agent —— macOS app

灵动岛风格的顶栏小窗,实时显示本机正在跑的 agent 会话(项目 / 最近 prompt / 状态 / 模型),点击跳回对应宿主。**单独使用即可,不依赖 server**。

文档入口:

- [`agent/AGENTS.md`](agent/AGENTS.md) —— 架构总览、构建/运行、核心约定 & 关键文件
- [`agent/docs/`](agent/docs/) —— 状态检测、会话发现、rate-limit、审批、SSH 远程、OTA 发版

---

## server —— 远程推送 server (可选)

让远端客户端实时查看 Mac 上正在跑的 agent 会话,代答 Claude / Codex 的问题与审批,并向终端 tab、Claude Desktop 会话或 Codex Desktop 任务投递回复文本。

支持的远端客户端:

- **浏览器 dashboard** (server 内置)
- **stdin REPL** (server 进程自身的命令行)
- **桌面摆件 / 小屏硬件** (如 ESP32 + LCD)

**默认 off**。启用与否不影响本地功能,默认状态下「本地优先,不引入远端服务」依然成立。

文档入口:

- [`server/AGENTS.md`](server/AGENTS.md) —— 架构、运行/测试、核心约定 & 关键文件
- [`server/README.md`](server/README.md) —— 入门 & 部署
- [`server/API.md`](server/API.md) —— 接口规格入口(总览 + 共享层),分 [`API-agent.md`](server/API-agent.md)(Mac 端)/ [`API-dashboard.md`](server/API-dashboard.md)(浏览器)两份

---

## client —— 远端客户端

接在 server 上的远端查看/操作端,协议完全复用 Dashboard ↔ Server 契约,**server 端零改动**。

- [`client/AGENTS.md`](client/AGENTS.md) —— 两类客户端的构建、协议对齐约定与主机侧测试
- [`client/ios/`](client/ios/) —— iPhone 原生 app,web dashboard 的 SwiftUI 重写
- [`client/firmware/`](client/firmware/) —— 桌面摆件固件,只显示聚合状态,不下载聊天记录:
  - `esp32-s3-touch-amoled-1.8/` —— Waveshare ESP32-S3 AMOLED (ESP-IDF)
  - `huangshan-pi/` —— 黄山派 (RT-Thread)