为什么值得关注

无需任何配置、API 或账户即可直观监控终端中的 AI 代理会话，并能与 MacBook 刘海完美集成，一目了然。

适合谁使用

使用带刘海 MacBook 的 Mac 用户
使用 Claude Code 或 Codex 的开发者
终端高级用户
AI 代理工作流爱好者

典型使用场景

同时监控多个在终端中运行的代理会话
通过绿色指示灯快速了解代理是否完成
通过可点击面板查看包含提示和子代理的会话历史
切换 Codex 宠物动画（更换精灵图）

项目优势

无需任何配置——不需要钩子、API 或账户
每 3 秒实时轮询，基于进程和文件描述符检测
透明且可点击穿透的窗口，从不干扰其他应用
支持多种终端应用及宠物自定义

使用前须知

由于日志写入的突发性，空闲/忙碌检测存在约 30 秒的延迟
需要 macOS 12+ 以及带刘海的 MacBook（其他显示屏使用虚拟刘海）
仅监控 Claude Code 和 Codex 代理，不支持其他 AI 工具

README 快速开始

Agent Notch

Your AI agents, living next to the MacBook notch.

While Claude Code or Codex is working, its mascot walks beside the notch — the Claude Code banner critter for Claude, the official Codex pet for Codex. Each agent has its own slot: the moment one finishes, its mascot becomes a green blob (even while the other keeps working). The green is a "finished since you last looked" notification — focusing your terminal clears it. Click to open a panel of your sessions, grouped by prompt, with every subagent tucked under a dropdown.

The panel

One row per session, titled by the tool, led by your latest prompt — not the agents' chatter. Subagents (Codex's philosopher swarm, Claude's Task agents) fold under a ▸ N subagents dropdown. Running rows show their mascot walking in place; finished rows get a green pixel checkmark. The tag on the right is the actual model that session runs.

How it works

No hooks, no APIs, no accounts. Liveness detection follows open-vibe-island's model — a session is a running agent process in a terminal — polled every 3 s:

ps finds claude/codex processes attached to a TTY (headless/background sessions are ignored)
lsof maps each process to the transcript it holds open (Codex), or to its working directory (Claude Code, which doesn't keep the transcript fd open)
transcripts provide the metadata: prompts, snippets, models, subagents
- Claude Code: ~/.claude/projects/*/*.jsonl (+ /subagents/agent-*.jsonl)
- Codex: ~/.codex/sessions/**/*.jsonl, grouped by parent_thread_id

Within a live session, busy vs idle is a hybrid: process alive + transcript written in the last 30 s = busy (mascot walks); alive but quiet = idle (nothing in the notch, dimmed row in the panel); process gone for 2 polls = done (green blob). Sessions idle over 6 h drop off the panel. Activating a terminal app (Ghostty, Terminal, iTerm2, kitty, Warp, Alacritty) acknowledges finished agents and clears their green indicator.

Known limitation: the ~30 s afterglow

Busy/idle is inferred from transcript write times, and transcript writes are bursty — so the mascot keeps walking for up to ~33 s (30 s window + 3 s poll) after a turn actually ends, and conversely a turn's quiet stretches are smoothed over. No process-level proxy (network, CPU, child processes) can

项目描述

The open-source alternative to vibe-island

agent-notch