realfishsam/agent-notch

What it solves

Agent Notch provides a visual status indicator for AI agents (specifically Claude Code and Codex) on macOS, allowing users to see at a glance whether their agents are currently working, idle, or have finished their tasks without needing to keep terminal windows open.

How it works

The tool uses a zero-config approach to detect agent activity by polling the system every 3 seconds. It identifies running claude or codex processes attached to a TTY and maps them to their respective transcript files on disk.

Activity is determined by a hybrid check: if the process is alive and the transcript has been updated within the last 30 seconds, the agent is marked as "busy" and its mascot walks next to the MacBook notch. If the process is gone for two polling cycles, it is marked as "done" (indicated by a green blob). A clickable panel provides a detailed view of sessions, grouped by the user's latest prompt, with subagents organized in dropdowns.

Who it’s for

macOS users who run AI agents like Claude Code or Codex in their terminals and want a non-intrusive way to monitor multiple agent sessions and their progress from anywhere in the OS.

Highlights

• Zero-config setup: No APIs, hooks, or accounts required.
• Notch integration: Visual mascots walk beside the MacBook notch to indicate active work.
• Session management: A transparent, click-through panel displays active sessions, the models being used, and subagent hierarchies.
• Customizable mascots: Supports various official Codex Pets spritesheets.
• Low overhead: Uses ps and lsof for liveness detection and monitors transcript write times for activity status.