realfishsam/agent-notch

# Agent Notch 你的 AI agent，就住在 MacBook 灵感触控槽（刘海）旁边。 当 **Claude Code** 或 **Codex** 正在工作时，它的吉祥物会在灵感触控槽旁走动——Claude 对应 Claude Code 的横幅小生物，Codex 对应官方的 Codex 宠物。每个 agent 都有自己的专属位置：一旦其中一个完成，它的吉祥物就会变成一个绿色的团子（即使另一个还在工作中）。这个绿色是一个“自你上次查看后已完成”的通知——聚焦你的终端窗口即可将其清除。点击可打开一个会话面板，按 prompt 分组，每个 subagent 都折叠在下拉菜单中。

## 面板 每个会话占一行，以工具名称命名，并由**你**的最新 prompt 领衔——而不是 agent 的闲聊。Subagent（Codex 的 philosopher 群体，Claude 的 Task agent）折叠在 `▸ N subagents` 下拉菜单中。运行中的行会显示其吉祥物在原地走动；已完成的行会得到一个绿色的像素对勾。右侧的标签是该会话实际运行的 model。

## 工作原理 无需 hooks、API 或账号。活跃状态检测遵循 [open-vibe-island](https://github.com/Octane0411/open-vibe-island) 的模型——*一个会话就是终端中正在运行的 agent 进程*——每 3 秒轮询一次： - `ps` 查找连接到 TTY 的 `claude`/`codex` 进程（忽略 headless/后台会话） - `lsof` 将每个进程映射到其打开的 transcript（Codex），或其工作目录（Claude Code，因为它不保持 transcript 的 fd 打开） - transcript 提供元数据：prompt、代码片段、model、subagent - Claude Code：`~/.claude/projects/*/*.jsonl`（+ `/subagents/agent-*.jsonl`） - Codex：`~/.codex/sessions/**/*.jsonl`，按 `parent_thread_id` 分组 在活跃会话中，*忙碌与空闲*的判断是混合的：进程存活 + 过去 30 秒内写入了 transcript = 忙碌（吉祥物走动）；存活但无操作 = 空闲（灵感触控槽中不显示任何内容，面板中的行变暗）；进程在 2 次轮询后消失 = 完成（绿色团子）。空闲超过 6 小时的会话将从面板中移除。激活终端应用（Ghostty、Terminal、iTerm2、kitty、Warp、Alacritty）即表示确认已完成的 agent，并清除其绿色指示器。 ### 已知限制：约 30 秒的余晖 忙碌/空闲状态是根据 transcript 写入时间推断的，而 transcript 的写入具有突发性——因此，在任务实际结束后，吉祥物会继续走动最多约 33 秒（30 秒窗口 + 3 秒轮询），反之，任务中的短暂安静期也会被平滑处理。没有任何进程级别的代理（网络、CPU、子进程）可以完全解决这个问题：只有 agent 自己知道它的任务何时结束。精确的修复方法是使用 agent hooks（像 open-vibe-island 那样，通过 `UserPromptSubmit`/`Stop` 写入状态文件），但为了保持零配置、无 hooks 的设计，这里特意跳过了这一步。如果这种余晖让你感到困扰，这就是升级的路径。 折叠后的窗口是透明的，除了微小的指示器区域外完全支持点击穿透（click-through），因此它绝不会阻挡下方的菜单项或应用。在全屏空间中，该栏会横跨整个顶部边缘。 ## Codex 宠物 Codex 动画使用的是官方的 Codex Pets 雪碧图（spritesheet，位于 `pets/` 中）。使用以下命令切换宠物： ``` echo dewey > ~/.config/agent-notch/pet ``` 选项：`codex`、`dewey`、`fireball`、`rocky`、`seedy`、`stacky`、`bsod`、`null-signal`。几秒钟内生效，无需重启。（雪碧图 © OpenAI，来自其公开的 pets CDN。） ## 构建与运行 ``` swiftc -O main.swift -o AgentNotch ./AgentNotch & ``` - **点击**指示器 → 打开面板。点击任意位置 → 关闭。 - 开机自启：系统设置 → 通用 → 登录项 → 添加 `AgentNotch`。 - 需要 macOS 12+（在带有灵感触控槽的 MacBook 上构建并测试；在无灵感触控槽的显示屏上，它会在虚拟灵感触控槽上居中显示）。

标签：AI代理, UI组件, 桌面辅助工具, 状态监控, 系统进程监控