notch-agent
TeamNoSleepz/notch-agent
A lightweight macOS menu bar app that turns your MacBook's notch into a live Claude Code status indicator.
Instalação
npx convez-ai TeamNoSleepz/notch-agent1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
While Claude is thinking, running tools, or waiting for input, a pixel grid animates inside your notch — so you always know what's happening without switching to the terminal.
- Three states: idle, working, awaiting input — each with distinct animation and color
- Live count of running
claudeprocesses on the right side of the notch - Optional sound alerts when Claude finishes or needs your attention
- Zero screen real estate used — lives entirely inside the hardware notch
Install
Requirements: macOS 13+, Claude Code, Xcode Command Line Tools
xcode-select --install # skip if already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/TeamNoSleepz/notch-agent/main/install.sh)"
Open /Applications/NotchAgent.app, then click the menu bar icon → enable Launch at Login.
What the installer does
- Clones the repo to
~/.notch-agent - Builds a release binary, wraps it into
NotchAgent.app, installs to/Applications - Injects Claude Code hooks into
~/.claude/settings.json— 8 events pointing at~/.notch-agent/hooks/notch-agent-hook.py
Running the installer again updates to the latest version.
States
| State | Animation | Color |
|---|---|---|
| Idle | Slow animated trail | Grey |
| Working | Animated trail with glow | Cream + orange glow |
| Awaiting input | Trail cycling down center column | Red |
Settings
Click the menu bar icon → Settings:
- Color palette — Default (cream/red/grey)
- Sounds — chime when Claude interrupts you or finishes a task
Uninstall
~/.notch-agent/uninstall.sh
Removes hooks from ~/.claude/settings.json, deletes /Applications/NotchAgent.app, removes ~/.notch-agent, and cleans up /tmp/notch-agent*.
[!WARNING] If you installed manually (git clone), run
uninstall.shbefore deleting the repo. Dead hook paths in~/.claude/settings.jsoncause errors on every Claude session. Fix by removingnotch-agent-hookentries manually from that file.
FAQ
Does this work on Macs without a notch? No — the notch panel requires the physical notch cutout. MacBooks from 2021 and later have it.
Does it work on external displays? The notch panel only appears on the built-in display. The menu bar icon and process count work on any display.
Why does install require Xcode Command Line Tools? NotchAgent is built from source using Swift. Xcode Command Line Tools provides the Swift compiler — it's a ~500MB download but you likely already have it.
Does it affect performance? No. The app is a lightweight SwiftUI panel with no background polling — it only reacts to hook events fired by Claude Code.
The hook events stopped firing after sleep. What do I do? Restart NotchAgent from the menu bar icon. A known limitation of the Unix socket after system sleep on some macOS versions.
How it works
Claude Code
│ hook fires on every event (PreToolUse, Stop, etc.)
▼
hooks/notch-agent-hook.py
│ sends JSON payload to /tmp/notch-agent.sock
│ fire-and-forget, exits immediately
▼
NotchAgent.app
│ Unix socket server reads event → maps to state
▼
Notch panel + menu bar icon
Hook events → states:
| Event | State |
|---|---|
PreToolUse, UserPromptSubmit, PostToolUse, PostToolUseFailure, SubagentStart, SubagentStop, PreCompact, PostCompact | Working |
Stop, StopFailure, SessionStart, PermissionRequest, Notification (idle) | Awaiting input |
SessionEnd, Notification (other) | Idle |
Notch panel — an NSPanel at mainMenu + 3 window level, sized to the physical notch using auxiliaryTopLeftArea / auxiliaryTopRightArea. Mouse events pass through.
Indicator — 3×3 grid of 5×5pt cells. Five animation patterns (snake, single horizontal, single vertical, staggering horizontal, staggering vertical) picked randomly each time Claude starts working.
Development
swift build && .build/debug/NotchAgent
Auto-rebuild on file changes:
./dev.sh
Build the .app bundle only (no install):
./scripts/bundle.sh
Project structure
notch-agent/
├── Sources/NotchAgent/
│ ├── main.swift # NSPanel, NSStatusItem, IndicatorView, AppDelegate
│ ├── StateWatcher.swift # ClaudeState — Unix socket server + agent counter
│ ├── SettingsWindowController.swift # Settings UI, AppPreferences, color palettes
│ └── Resources/ # App icon, status bar icon
├── hooks/
│ ├── notch-agent-hook.py # Claude Code hook — sends events via Unix socket
│ ├── notch-agent-hook.sh # Shell wrapper for the hook
│ └── watch.sh # File watcher for dev rebuilds
├── scripts/
│ ├── bundle.sh # Creates NotchAgent.app bundle
│ └── install.sh # bundle.sh + copy to /Applications
├── install.sh # curl one-liner entry point
├── setup.sh # Build, install app, wire hooks
├── uninstall.sh # Full cleanup
├── dev.sh # Auto-rebuild on file changes
└── Package.swift
Contributing
Issues and PRs welcome. For large changes, open an issue first to discuss.