NotchTune

Monitor your agents and music all in one place.

NotchTune is a native macOS companion that turns your Mac's notch, or a compact top bar on external displays, into a live control surface for music and terminal-native AI agents. It combines playback controls, agent monitoring, approvals, questions, and session jump-back in one lightweight local app.

Highlights

• Dynamic notch switching: NotchTune moves between Music and Agents automatically, so the island can show the thing that matters now: current playback, active agent work, permission prompts, questions, or recently completed sessions.
• Music controls: Control Spotify or Apple Music from the notch, including playback, track details, artwork, progress, shuffle, repeat, love, volume, and quick open actions.
• Agent monitoring: Track local coding-agent sessions from the menu bar or notch, including running state, waiting approvals, questions, completions, subagents, and usage summaries.
• Myspace: Save dictated thoughts, drop in images or files, and keep time-based reminders in a local personal space.
• Mirror: A tab that turns the notch into a hand mirror: your camera, flipped like a mirror, with zoom and a camera picker. The camera is only on while the tab is open.
• Haptics: On a Force Touch trackpad, feel the notch's buttons, tab switches, a full ripple for play and pause, a lighter flick for skip and back, a rising "yes" for Allow and Send, a double knock for Deny and delete, a swoosh when you jump to a terminal, and a soft nudge when an agent finishes. Each one can be retuned or turned off in Personalization.
• Character personalization: Choose from twenty pixel characters for the island, from the dino and Claude's Clawd to a goopy blob and Italian-brainrot favourites like Tung Tung Tung Sahur, set how much they move (Calm, Lively or Still), and style the MacBook notch and an external display separately or together with Sync.
• Notification sounds: 32 original bundled sounds, loudness-matched to the macOS alerts, alongside system and custom sounds.
• Finished-task summaries: When Claude Code or Codex finishes, the completion card shows what changed (files edited, tests run and their result, turn time), worked out locally from the session's own events.
• Meeting heads-up: Opt in to see your next calendar meeting in the notch a few minutes ahead, with a Join button for video links and an optional quiet mode during meetings. Calendars are read on your Mac only.
• Notch-aware layouts: Runs as a real notch surface on MacBook displays and falls back to a clean top-center bar on external or non-notch screens.
• Local, native, and open source: Built with SwiftUI and AppKit. No Electron shell, no telemetry, and no remote server dependency.
• Automatic updates: NotchTune updates itself quietly in the background, the way Figma does. It downloads only what changed since your version (a small Sparkle delta patch, with the full app as the fallback), prepares it, and shows an Update button in the notch and Restart to Update in Settings. One click swaps in the new version and relaunches, with no installer or disk image. Leave it, and it installs when NotchTune quits, or after a day once you've stepped away and no agent needs you. You can turn automatic downloads off in Settings.

Supported Integrations

NotchTune currently supports Spotify and Apple Music for playback.

For coding agents, it supports Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Antigravity, Kimi CLI, Qoder, Qwen Code, Factory, and CodeBuddy through local hooks, transcript discovery, and process matching where available.

Jump-back works with Terminal.app, Ghostty, cmux, Kaku, WezTerm, iTerm2, Warp, and tmux, as well as Codex.app and editors with integrated terminals: Cursor, VS Code, Windsurf, Trae, and the JetBrains IDEs.

Quick Start

Install The App

NotchTune needs an Apple Silicon Mac on macOS 14 or later.

Download the latest NotchTune.dmg from Releases, open it, and drag NotchTune.app into Applications. Run it from there: it can't update itself from the disk image or from Downloads.

This release isn't notarized yet, so macOS blocks the first launch. Right-click → Open no longer gets past that on macOS 15 and later. Try to open NotchTune, then go to System Settings → Privacy & Security and choose Open Anyway. If macOS says NotchTune is damaged, or you'd rather use Terminal, run:

xattr -dr com.apple.quarantine "/Applications/NotchTune.app"

The first launch opens a short setup assistant and a guided tour of the notch, covering your coding agents, permissions, and the look of the island. Both are in Settings → General if you want them again, and Settings → Setup manages agent hooks at any time. Grant Accessibility permission if macOS asks; NotchTune uses it to detect terminal windows and jump back to active sessions.

Updates

You only install NotchTune once. After that it keeps itself up to date:

1. It checks for a new version every hour (or right away from Settings → General → Check for Updates…).
2. It downloads the update in the background. Usually that is a small patch with just what changed, often under 1 MB; if there's no patch for your version, it downloads the full app instead.
3. When the update is ready, an Update button appears in the notch and Restart to Update in Settings. Click either one and NotchTune swaps in the new version and relaunches in a second or two, with no disk image or installer.
4. If you don't click it, the update installs when NotchTune quits. If it's still waiting a day later, it installs by itself once you've been away from the Mac for a few minutes, as long as no agent is waiting for you and Mirror is closed.

To decide for yourself, turn off Settings → General → Download updates automatically. NotchTune still checks, tells you in Settings when a version is out, and leaves the rest to you.

Permissions you grant (camera for Mirror, calendars, Accessibility) are remembered between launches and across updates: releases are signed with one stable certificate, so macOS sees each update as the same app. Coming from 2.2.0 or earlier, macOS asks once more after that first update.

Run From Source

Clone the repo and run the app locally:

git clone https://github.com/dw2lam/NotchTune.git
cd NotchTune
zsh scripts/launch-dev-app.sh

To build the hook helper used by agent integrations:

swift build -c release

Or open the package in Xcode:

open Package.swift

Development

This repository is a Swift package with native app, core bridge, hook helper, and setup targets. For more details on the project architecture, read the documentation index.

The helper scripts are the recommended way to exercise app-bundle behavior locally because they refresh the generated assets, helper binaries, and local dev bundle.

Useful commands:

swift build
swift test
zsh scripts/harness.sh
zsh scripts/launch-dev-app.sh
zsh scripts/package-app.sh
zsh scripts/make-release-deltas.sh <tag>   # delta patches + appcast for a release

Credits

NotchTune builds on work from:

• Tuneful, originally developed by Martin Fekete, for native macOS playback controls and interface ideas.
• Octane0411, for the dynamic notch integration and terminal-native AI tracking foundations that helped shape NotchTune.

What's Next

Opt-in screen context for AI assistance, more connectors, personalization options, and deeper agent workflows are planned as NotchTune continues to grow into a local-first control surface for music, personal notes, and coding agents.