Turn your MacBook notch into an AI coding-agent command center.
agent-notch is a fork of the excellent boring.notch by TheBoredTeam. It keeps everything boring.notch does (music, calendar, file shelf, HUD replacement) and adds an Agents panel that tracks your AI coding-agent sessions — Claude Code, Codex CLI, Cursor, and more — and pops the notch open the moment a session finishes or needs your approval, with one click to jump straight back to that session's window.
Inspired by the idea of "the notch as an AI agent command center." It's config-driven, not hardcoded to any one person's setup: connect the tools you use, or wire up your own via a tiny local HTTP contract.
agent-notch runs a tiny HTTP server on 127.0.0.1:47591 (loopback only — never
reachable off your machine). Your AI tools POST a small JSON event to it when
something happens. agent-notch shows it in the Agents panel and, for
needs_approval / finished events, pops the notch open.
See AGENTS_PROTOCOL.md for the full event schema.
| Tool | Integration | How |
|---|---|---|
| Claude Code | ✅ Full hooks | Stop + Notification hooks in ~/.claude/settings.json |
| Codex CLI | ✅ Full hooks | Stop hook in ~/.codex/hooks.json (needs features.hooks = true) |
| Cursor | 🟡 Best-effort beta | Accessibility window-title watcher |
| Perplexity | 🟡 Best-effort beta | Accessibility window-title watcher |
| Grok | 🟡 Best-effort beta | Accessibility window-title watcher (bundle id unverified) |
| Antigravity | 🟡 Best-effort beta | Accessibility window-title watcher (bundle id unverified) |
| OpenCode | 🟡 Best-effort beta | Accessibility window-title watcher (bundle id unverified) |
| Pi | 🟡 Best-effort beta | Accessibility window-title watcher (bundle id unverified) |
| Anything else | ✅ Manual | POST to http://127.0.0.1:47591/event per AGENTS_PROTOCOL.md |
Honest note on the beta watchers: GUI apps have no hook/webhook API, so agent-notch guesses when a session goes idle by polling the app's focused window title via macOS Accessibility. This is approximate — expect false positives and misses. The full-hook integrations (Claude Code, Codex) are exact; the beta watchers are a convenience, not a guarantee.
- Build in Xcode (see Building from source below), or download a release once one is published.
- Grant Accessibility permission if you plan to use the beta GUI watchers: System Settings → Privacy & Security → Accessibility → enable agent-notch. (Not needed for Claude Code / Codex hooks or manual POSTing.)
- Open Settings → Agent Integrations:
- Click Install next to Claude Code and/or Codex CLI. Each backs up the target config file first and is idempotent.
- For Codex, also add
features.hooks = trueto~/.codex/config.tomland complete Codex's one-time trust prompt (agent-notch won't rewrite yourconfig.toml). - Toggle on any beta GUI watchers you want.
- For any tool not listed, POST events yourself per AGENTS_PROTOCOL.md.
The beta watchers use the macOS Accessibility (AX) API to read window titles. Sandboxed (Mac App Store) apps cannot use the AX API at all, so agent-notch is distributed as a non-sandboxed, Developer-ID-style app. If you don't use the beta watchers, you don't need to grant Accessibility.
Requirements (inherited from boring.notch):
- macOS 15.6 or later
- Xcode 26 or later (full Xcode, not just Command Line Tools)
git clone https://github.com/kyletusing34/agent-notch.git
cd agent-notch
open boringNotch.xcodeproj
# Select the "boringNotch" scheme and Run (⌘R)The new code lives in boringNotch/AgentHub/; the hook scripts are in
scripts/. See KNOWN_ISSUES.md for build/verification status.
Screenshots of the Agents panel and notch-pop to be added. (Placeholder.)
agent-notch is a derivative work of TheBoredTeam/boring.notch — huge thanks to TheBoredTeam and all boring.notch contributors. Please star and support the upstream project.
Like boring.notch, agent-notch is licensed under the GNU General Public License v3.0 — see LICENSE. Per the GPL, this fork keeps the original license and credits the upstream project.