Your MacBook's notch, turned into a live control surface for AI coding agents,
media and system controls.
The Notch lives in the notch at the top of your screen. When a coding agent is working, a small pixel mascot shows what it is doing. Hover over the notch to see every session, get a heads-up the moment an agent needs your permission or asks a question, and keep an eye on your music and crypto prices.
- See every agent at a glance. Claude Code, Codex, Gemini CLI, Cursor, OpenCode, Antigravity and Kiro sessions show up automatically, including subagents.
- Know when an agent needs you. A permission prompt makes the notch pop open with a shock ring; a question drips out of it. The card shows exactly what the agent wants, and one click takes you to the agent to answer. A finished run gets a burst of confetti.
- A mascot that is alive. Each state has its own motion and colour. It startles when it needs you, celebrates when it is done, and falls asleep when it has been idle for a while.
- Media, HUD and crypto. Now playing with controls and synced lyrics, a volume and brightness HUD that replaces the macOS one, and pinned Binance prices.
- Your calendar. What's next and the days ahead from iCloud, Google, Microsoft and any CalDAV account on your Mac, with a one-click Join for Meet, Zoom and Teams calls.
- Asks before it touches anything. On first launch the notch introduces itself and lists the agents it found; nothing is written to their config until you say yes.
- Works on any Mac. Macs without a notch get a drawn notch in the same place.
When an agent needs you, the notch comes to you. A permission prompt pops it open, a question drips out of it, and a finished run spills confetti:
Closed, the notch shows the most important thing right now:
Open (hover over the notch), it shows the full panel:
| Agents and subagents | A permission prompt |
|---|---|
 |
 |
| A question, with its answers | Now playing, with synced lyrics |
 |
 |
| Crypto watchlist | Settings |
 |
 |
You need macOS 14 or later. The app is universal, so it runs on Apple silicon and Intel Macs.
brew install --cask vallykrie/tap/the-notch- Download the latest
The-Notch-<version>.dmgfrom the releases page. - Open it and drag The Notch into Applications.
Open The Notch from Applications. It has no Dock icon; it appears in the notch at the top of your screen.
If macOS says it cannot verify the developer, right-click the app → Open → Open. You only need to do this once. Beta builds are not notarised yet, and this step stops being needed once they are.
Move your pointer onto the notch and the panel opens. Move away and it closes. Out of the box it has three tabs at the top: Media, Agents and Calendar. Crypto and Notes are off until you switch them on in Settings. The gear on the right opens Settings.
The first time it runs, the notch introduces itself and asks before touching anything: it lists the agents it found, and you can untick any of them. Once you say yes, The Notch looks for installed agents every 30 seconds and adds its hook to each one you agreed to. If you said "not now", nothing is written; Settings → Replay intro… asks again.
| Agent | Where the hook goes |
|---|---|
| Claude Code | ~/.claude/settings.json |
| Codex | ~/.codex/hooks.json (desktop and CLI activity are also read from local session files) |
| Gemini CLI | ~/.gemini/settings.json |
| Cursor | ~/.cursor/hooks.json |
| OpenCode | ~/.config/opencode/plugins/the-notch.js |
| Antigravity | ~/.gemini/config/hooks.json |
| Kiro | ~/.kiro/hooks/the-notch.json |
Your existing hooks from other tools are kept. The Notch merges its entry in, never replaces the
file, and saves a backup next to it (*.the-notch-backup.<date>) before the first change.
Start a new agent session after installing, because agents only load hooks when a session starts. To check the connection, go to Settings → Connections…. Each agent shows Receiving activity, Waiting for session, Not connected or Not detected.
Codex: to see Codex prompts in the notch, open
/hooksin Codex and trust The Notch's hook. Codex asks again whenever a hook changes.
If the app is not running, agents behave exactly as before. The hook never blocks them.
The closed notch shows the mascot for the agent you most recently gave work to, and how many agents are running. The colour tells you the situation from across the room:
| Colour | Meaning |
|---|---|
| Blue / cyan | Working, running a tool, or waiting for your next prompt |
| Purple | Thinking or compacting its context |
| Orange | Needs your approval. The agent is stopped until you answer. |
| Yellow | Asked you a question |
| Green | Done |
| Dim green | Idle. It has been quiet for 5 minutes. |
When an agent is blocked on you, an orange ring also travels around the notch.
When an agent asks for permission, the notch pops open; when it asks a question, a drop forms under the notch and the notch swallows it as it opens. The card shows who is asking and for how long on the left, and on the right the command, or the question with its numbered answers. Press Answer in … to jump to the agent, and answer there as usual. The card tells you which key to press. It clears itself once the agent moves on, or press ✕ Dismiss. If you leave a prompt unanswered, the notch nudges you again every few seconds.
When a run finishes, the notch breathes out and drops a little confetti onto your desktop. Turn that off with Settings → Celebrate done.
Each row shows the project, what the agent is doing right now, elapsed time, tokens and cost. Subagents appear indented under the session that started them.
- Hover over a row and click – to hide it. It comes back if that session does something new.
- Clear idle removes every idle session at once.
- Sessions that go quiet become Idle after 5 minutes and leave the list after 15 minutes.
The Media tab shows what is playing from Spotify or Apple Music, with play/pause, skip and a progress bar. While music plays, the closed notch shows the artwork and a live waveform. When nothing is playing, the tab links straight to each installed player.
Press the lyrics button (the three lines in the controls) to follow the song's lyrics, synced to
playback. The controls move to a slim strip and the lyrics take the panel, and the closed notch
floats the line being sung in a small pill underneath it. Move your pointer near the pill and it
splashes out of the way, so you can click whatever it was covering. Lyrics come from LRCLIB,
a free lyrics database: the track's title and artist are sent there only while lyrics are on.
If the lookup fails, it retries on its own a couple of times; if lyrics still don't appear, press
Try again. Titles that players decorate (- Remastered 2009, - From "…", (feat. …)) are
also searched without the extra part.
Turn on Settings → Replace OS HUD to see volume and brightness changes in the notch instead of the macOS overlay. The app asks for the permission it needs to read the media keys.
Switch it on in Settings › Crypto first. In the Crypto tab, use Add pair to search Binance Spot pairs (such as BTC/USDT) and
build a watchlist. Pin a pair to keep its live price in the closed notch. It uses Binance's
public feed, so there is no account or API key. See Crypto feed details.
The Calendar tab shows a week strip with a dot for each event, and the selected day's events underneath, with a countdown to the next one. Swipe the strip with two fingers (or use the ‹ › arrows) to page through weeks, and click a day to list it. Click Connect calendars once and macOS asks for calendar access; the notch never asks on its own.
It reads the calendars macOS already syncs, so one connection covers every account:
- Apple: iCloud and On My Mac calendars appear straight away.
- Google, Microsoft (Outlook.com, Exchange, Office 365) and CalDAV: add the account in System Settings › Internet Accounts (or use Add account… in the notch) and turn on Calendars for it.
Click an event to open it in Calendar. If it has a Meet, Zoom, Teams, Webex or similar link, Join opens the call. In Settings › Calendar you can pick which calendars are shown and whether to list all-day events. Nothing leaves your Mac.
Switch it on in Settings › Notes. The Notes tab is a scratchpad: somewhere to write a prompt before you give it to an agent, or jot anything down without opening another app. Click into it and type; it saves as you go, and the notch stays open while you type (press Esc to let it close).
- Four pages, 1–4 (⌘1–⌘4), for keeping a few things apart.
- Copy (⌘↩) copies the page and closes the notch, so you can paste straight into your terminal or chat.
- Clear empties the page.
| Section | Options |
|---|---|
| Media | Show media, Hide when paused |
| Agents | Show agents, Attention ring, Sound cues, Keep done (how long finished sessions stay), Connections… |
| Calendar | All-day events, Calendars… (show or hide each one), Add account… |
| System | Replace OS HUD, HUD dwell (how long it stays on screen) |
| Behaviour | Expand on hover, Hover speed, Launch at login, Celebrate done, Replay intro…, Donate… |
Quit is in the top-right corner of Settings.
brew uninstall --cask the-notchOr quit the app and drag it from Applications to the Bin. The hooks it added to your agents are harmless without the app: they fail open and let the agent carry on.
Requires Xcode with the macOS 14 SDK. From the repository root, make a local unsigned Debug build:
xcodebuild -project "The Notch.xcodeproj" \
-scheme "The Notch" \
-configuration Debug \
-destination 'platform=macOS' \
CODE_SIGNING_ALLOWED=NO \
buildReleases are built by CI from v* tags; see Releasing.
| Command | What it checks |
|---|---|
bash tools/hook-harness/run-all.sh |
The hook bridge: happy path, allow, deny, timeout, concurrent sessions, malformed input. It never touches the real socket or agent config. Needs Go 1.22+. |
bash tools/session-tests/run.sh |
The session lifecycle (idle after 5 min, removed after 15 min, what is always kept) |
bash tools/trading-tests/run.sh |
The crypto store and watchlist migration |
bash tools/calendar-tests/run.sh |
Calendar meeting-link detection, week span, day grouping and order |
NOTCH_FRAMES=<dir> "<app>/Contents/MacOS/The Notch" |
Renders every surface to PNGs. The screenshots above come from this. |
python3 scripts/render-app-icon.py |
Regenerates the app icon. See App icon. |
- Roadmap: phases and progress
- Architecture
- Hook protocol
- Mascot design explorations: live HTML previews of the concepts behind the mascot
Issues and pull requests are welcome. See CONTRIBUTING.md. To report a security problem privately, see SECURITY.md.
The Notch is free and open source, and it will stay that way. If it saves you time, you can help fund its development:
- Sponsor on GitHub, monthly or one-time
- Or use Settings → Donate… inside the app
Starring the repo and telling a friend helps too.
The Notch is released under the MIT License. Copyright (c) 2026 Vallykrie. Bundled third-party components and their notices are listed in THIRD_PARTY_LICENSES.
The Notch is an independent project and is not affiliated with or endorsed by any other notch utility or AI agent vendor. Claude, Codex, Gemini and other product names are trademarks of their respective owners.