Agent Notch 是一个 macOS 顶部刘海区域状态指示工具，用 Swift 编写，用来在 MacBook 刘海旁显示 Claude Code 和 Codex 等 AI 编程代理的运行状态。它不依赖 API、账号或 hooks，而是通过轮询系统进程、TTY、lsof 和本地 transcript 文件来判断会话是否运行、忙碌、空闲或已完成。适合经常同时运行 Claude Code / Codex 的开发者，用一个轻量可视化方式管理多个 AI agent 会话。
适用领域
AI 编程助手 / macOS 桌面工具 / 开发者效率工具 / 终端会话监控 / Claude Code / Codex 辅助工具 / Swift 原生应用
配置难度
低到中等。普通 macOS 开发者只需安装 Swift 工具链、编译并运行即可；但若要排查识别失败、适配新的 agent、修改状态检测逻辑或打包为正式 macOS App，则需要一定 Swift、macOS 进程管理和文件系统监控经验。
商业价值
对个人开发者和小团队的价值主要在提升 AI 编程任务的可见性和工作流体验，减少频繁切换终端查看 Claude Code / Codex 是否完成的成本。它不是核心生产系统，但可作为 AI 开发环境的辅助效率组件。对于企业场景，可参考其零配置、本地进程检测和 transcript 解析思路，构建内部 AI agent 监控面板；但直接商用前需要评估隐私、稳定性、上游兼容性和维护成本。
01
技术亮点
- 零账号、零 API、零 hooks：无需登录第三方服务，也无需修改 Claude Code / Codex 配置。
- 轻量实现：单个 Swift 文件可直接 swiftc 编译运行。
- 原生 macOS 体验：利用刘海区域显示状态，不明显打扰工作流。
- 可视化状态清晰：运行中显示动画，完成后显示绿色提示，空闲会话在面板中变暗。
- 支持 Claude Code 和 Codex 的会话识别，并能解析 prompt、模型、子 agent 等信息。
- 点击指示器可打开会话面板，按 prompt 聚合展示 session，子 agent 可折叠。
- 窗口透明且大部分区域 click-through，不会阻挡菜单栏或其他应用。
- MIT 许可证，便于个人或团队二次开发。
02
目标用户
- 使用 macOS，尤其是带刘海 MacBook 的开发者
- 频繁使用 Claude Code 或 OpenAI Codex 进行代码生成、重构、调试的工程师
- 同时运行多个 AI agent 任务，需要快速查看任务状态的用户
- 偏好零配置、本地运行、无需账号授权工具的开发者
- 想替代 vibe-island / open-vibe-island 类工具的用户
03
配置要求
- 系统要求：macOS 12+。
- 主要适配带刘海的 MacBook；无刘海显示器会在顶部居中位置模拟虚拟刘海。
- 需要本地正在运行的 Claude Code 或 Codex 进程，并且这些进程需要绑定到 TTY；后台或 headless 会话会被忽略。
- Claude Code transcript 默认读取路径：~/.claude/projects/*/*.jsonl，以及对应 subagents 目录。
- Codex transcript 默认读取路径：~/.codex/sessions/**/*.jsonl。
- 终端激活确认支持 Ghostty、Terminal、iTerm2、kitty、Warp、Alacritty 等终端应用。
- Codex 宠物可通过写入配置文件切换，例如：echo dewey > ~/.config/agent-notch/pet。
- 可选宠物包括 codex、dewey、fireball、rocky、seedy、stacky、bsod、null-signal。
04
适用场景
- 在 Claude Code 或 Codex 正在处理任务时，在 MacBook 刘海旁显示动态宠物或 mascot
- 快速判断某个 AI agent 是否仍在运行、是否已经完成、是否处于空闲状态
- 点击刘海旁指示器打开面板，查看所有当前会话、prompt、模型和子 agent
- 通过绿色提示识别自上次查看后已经完成的 AI agent 任务
- 监控 Codex 子任务、Claude Task agents 等多 agent 场景
- 在不修改 Claude Code / Codex 配置的情况下获得基础状态通知
05
部署与配置
- 确认系统为 macOS 12 或更高版本。
- 安装 Swift 编译环境，通常可通过 Xcode Command Line Tools 获得。
- 克隆仓库：git clone https://github.com/realfishsam/agent-notch.git
- 进入项目目录：cd agent-notch
- 编译：swiftc -O main.swift -o AgentNotch
- 运行：./AgentNotch &
- 如需开机启动，进入 System Settings → General → Login Items，将 AgentNotch 添加到登录项。
06
风险与注意事项
- 状态判断是启发式的，依赖进程、TTY、lsof 和 transcript 文件写入时间，可能出现误判。
- busy/idle 判断存在约 30 秒 afterglow，任务实际结束后动画可能继续显示最多约 33 秒。
- 不使用 hooks 的设计降低了侵入性，但也牺牲了状态判断精确度。
- 只监控绑定到终端 TTY 的本地会话，后台任务、headless agent 或远程服务器上的任务无法被检测。
- 依赖 Claude Code 和 Codex 当前 transcript 文件结构，如果上游工具改变存储路径或格式，可能失效。
- 主要面向 macOS 和刘海屏场景，不适合 Windows、Linux 或跨平台使用。
- 项目星标较少，生态和长期维护稳定性需要进一步观察。
- 读取本地 AI 会话 transcript 元数据，虽然不需要联网，但对隐私敏感团队仍需审查源码。
2026-07-28
第22名
新收录 · github_search
2026-07-27
第27名
新收录 · github_search
2026-07-26
第23名
新收录 · github_search
2026-07-25
第24名
新收录 · github_search
2026-07-24
第28名
新收录 · github_search
