Agent Notch

A free, open-source, multi-agent macOS app that turns your Mac's notch into a unified command center for AI coding agents (Claude Code, Codex, and more).

Session state, running tools, token usage, and permission requests appear live in the notch, so you can follow what your agents are doing without switching to a terminal.

Features

• Multi-agent: Claude Code and Codex sessions rendered through one unified model (extensible to other agents)
• Live status: thinking, tool execution, waiting for permission, and completion at a glance
• Permission requests: approve or deny straight from the notch
• Open source and free: shipped as a native, non-sandboxed app

Install

Install from the Homebrew tap:

brew install --cask tosaka07/tap/agent-notch

This installs AgentNotch.app into /Applications and links the bundled CLI as agent-notch on your PATH, which the agent hooks rely on.

Upgrading and uninstalling go through Homebrew as well:

brew upgrade --cask agent-notch
brew uninstall --cask agent-notch

Apple silicon only, and the cask requires macOS 26 (Tahoe) or later.

Requirements

• macOS 26 or later
• Swift tools 6.2 or later — Package.swift is the source of truth for the code
• Xcode 26 or later, to build the .app itself. The Xcode project is generated from xcode/project.yml by XcodeGen and is not committed; mise install provides it. See Why Xcode builds the bundle.

Setup

# Build (debug)
swift build

# Build the neighboring hook helper, then run the GUI app
swift build --product agent-notch
swift run AgentNotch
#   Change log level: AGENT_NOTCH_LOG=debug swift run AgentNotch

# Run it as a bundle instead, which anything sending Apple events needs
./scripts/build_app.sh debug && open build/AgentNotch.app

swift run produces a bare executable, which has no TCC identity of its own. macOS then attributes the Apple events it sends to whichever app started it — the terminal the command was run from. The automation prompt names that terminal, the permission is granted to it rather than to Agent Notch, and NSAppleEventsUsageDescription is never read. Selecting the cmux pane a session runs in, on a terminal jump, is the one feature that sends Apple events; exercise it from a bundle launched with open, which goes through Launch Services and so answers for itself. The bundle is unsigned, so each rebuild changes its identity and the permission has to be granted again.

Why Xcode builds the bundle

Day-to-day development uses SwiftPM. The .app is built by Xcode, and that split is forced rather than chosen.

swift build generates a resource accessor that looks for a package's resource bundle in two places: directly under Bundle.main.bundleURL, and the absolute build directory of the machine that compiled the binary. Inside a .app the first cannot exist — resources belong in Contents/Resources, and putting bundles at the app root makes codesign fail with unsealed contents present in the bundle root. The second exists only for whoever built it. A SwiftPM-built .app therefore works for the person who compiled it and traps on launch on every other machine, dependencies included, and those cannot be patched. Xcode's accessor searches Bundle.main.resourceURL and resolves correctly.

./scripts/verify_app_bundle.sh checks a built bundle for exactly this, and CI runs it.

The first-run onboarding explains the hook changes and installs them only after you approve. Until installation succeeds, Agent Notch does not start its session runtime. Hooks can be checked and reinstalled later from Settings. You can also drive development hook installation explicitly from the CLI:

# CLI (the hook itself; normally invoked by the agent's hook config)
swift run agent-notch install --development
swift run agent-notch remove
swift run agent-notch hook --agent claude   # stdin JSON -> forwarded over the socket
swift run agent-notch hook --agent codex

Release packages must expose the bundled CLI on PATH as agent-notch. For example, a Homebrew Cask should declare the bundled AgentNotch.app/Contents/MacOS/agent-notch as a binary. The production hook definition then stays stable as agent-notch hook ... across app updates.

Tests

swift test
swift test --filter AgentNotchTests.TranscriptParserTests           # One file
swift test --filter AgentNotchTests.TranscriptParserTests/testName  # One test

Architecture overview

The package has two executable targets, two libraries, and one test target. Everything that does not depend on the UI lives in AgentNotchCore, so both the GUI and the CLI can use it. The executables hold nothing but their entry points, because Xcode links the libraries directly when it builds the .app — see Why Xcode builds the bundle.

Target	Role
AgentNotchCore/	Models, event parsers, socket server/client, hook installer (no AppKit/SwiftUI dependency)
AgentNotch/	GUI app. NotchPanel (NSPanel) + SwiftUI views
AgentNotchApp/	@main for the GUI, and nothing else
AgentNotchCLI/	The agent-notch binary (hook entry point + installer)
AgentNotchTests/	Swift Testing suites covering both Core and GUI

Events flow in one direction: the agent fires a hook, the hook forwards the event over a Unix socket, EventProcessor updates session state, and SwiftUI re-renders.

Contributing

Issues and pull requests are welcome. Run swift test before opening a pull request.

License

Agent Notch's original source code is available under the MIT License. Bundled third-party components remain under their respective licenses, which are listed in Settings → About.