Atoll

Atoll is a personal macOS 26 accessory app that places an OLED-black island over the built-in MacBook notch. Hover the island to open a hub for music, Claude Code sessions, GitHub work, and a keep-awake control.

The app is built with Swift Package Manager and has no Xcode project. The current implementation includes:

• now-playing artwork, transport controls, and playback position, using the vendored mediaremote-adapter when available and a Spotify fallback otherwise;
• live Claude Code session state, hook-driven updates, transcript snippets, session details, and jump actions for Warp or VS Code;
• GitHub pull requests and issues involving the authenticated gh user, with CI, review, mention, and assigned-issue alerts;
• a /usr/bin/caffeinate toggle;
• optional menu-bar decluttering, launch at login, fullscreen hiding, sounds, and notifications;
• a dark SwiftUI settings window for the General, Sessions, GitHub, and Menu Bar options.

Requirements

• macOS 26 or later;
• a Swift 6 toolchain with the macOS 26 SDK;
• claude for Claude Code session tracking (optional);
• the GitHub CLI, authenticated with gh auth login, for GitHub tracking (optional);
• Spotify for the fallback media integration (optional).

Atoll is designed for the built-in display notch. On a Mac without a physical notch it uses a fallback collapsed size; external displays are still reported by the probe, but the app’s island is placed on the built-in display only.

Build and run

Build the debug products:

swift build

Run the accessory app directly:

.build/debug/AtollApp

For a double-clickable, ad-hoc-signed application bundle:

./scripts/make-app.sh
open dist/Atoll.app

To copy the bundle to /Applications:

./scripts/make-app.sh --install
open /Applications/Atoll.app

--install replaces /Applications/Atoll.app. The bundle is ad-hoc signed for personal use; it is not a notarized distribution build. Installing it in /Applications is also required for the Launch at login setting to work reliably.

The app bundle includes the vendored media adapter under Contents/Resources/MediaRemoteAdapter/. A plain debug build falls back to the copy in Libraries/MediaRemoteAdapter/.

Claude Code sessions

When Atoll starts normally, it merges its hooks into ~/.claude/settings.json for these events: SessionStart, UserPromptSubmit, Stop, StopFailure, Notification, PermissionRequest, and SessionEnd. Existing Claude hooks are preserved, and the original file is backed up under ~/.atoll/ before the first change. Atoll also reconciles hook state with claude agents --json roughly every 20 seconds.

The hook socket is normally ~/.atoll/atoll.sock. For isolated development or probe runs, ATOLL_SETTINGS and ATOLL_SOCK can point to alternate paths, and ATOLL_CLAUDE can point to a specific claude executable.

Probe and diagnostics

atoll-probe exercises the engines without launching the full UI:

swift run atoll-probe notch
swift run atoll-probe media
swift run atoll-probe roster
swift run atoll-probe github
swift run atoll-probe tail /path/to/transcript.jsonl
swift run atoll-probe detail <session-id>
swift run atoll-probe serve-test
swift run atoll-probe hooks status
swift run atoll-probe hooks install
swift run atoll-probe hooks remove

notch prints geometry for every display. media, roster, and github emit JSON. serve-test listens on the session socket and prints decoded hook events until interrupted. The hook commands modify the configured Claude settings file, so use ATOLL_SETTINGS when testing against a copy.

For a headless app smoke check that does not start engines, sockets, hooks, or subprocesses:

ATOLL_SMOKE=1 .build/debug/AtollApp

It prints one JSON line containing the panel, screen, and notch geometry, then exits.

Permissions and optional integrations

• The normal menu-bar chevron works without special permissions. The optional ⌘⇧. global hotkey requires Input Monitoring.
• Precise window focusing in Warp uses Accessibility when available; Atoll falls back to activating Warp and opening a tab at the session directory.
• Spotify automation may cause macOS to ask for permission to control Spotify.
• GitHub and Claude integrations degrade to empty or unavailable states if their CLIs are missing or unauthenticated.

Repository layout

• Sources/AtollApp — the @main accessory-app shell and notch panel;
• Sources/AtollUI — island, hub, module, and settings views;
• Sources/ReefKit — geometry, media, sessions, GitHub, menu-bar, and system engines;
• Sources/AtollProbe — diagnostic command-line executable;
• Libraries/MediaRemoteAdapter — vendored media adapter artifacts;
• scripts/make-app.sh — release build and app-bundle assembly;
• scripts/make-icon.swift — regenerates assets/AppIcon.icns.

License

Atoll is licensed under the MIT License. See LICENSE and NOTICE.md for third-party acknowledgements.