{"slug": "notchagent-native-macos-notch-control-for-ai-agents-running-under-herdr", "title": "NotchAgent – native macOS notch control for AI agents running under herdr", "summary": "NotchAgent, a native macOS notch control surface for AI coding agents running under herdr, is now available. The app provides a color-coded status line below the MacBook notch, allowing users to monitor, approve, deny, answer, and jump to agents without switching terminal panes. It requires macOS 14+ on Apple Silicon and the herdr state authority to be installed and running.", "body_md": "A native macOS notch control surface for AI coding agents running under\n[herdr](https://herdr.dev) in your preferred terminal. **Monitor, approve or deny, answer, and\njump to** your agents from the MacBook notch — without hunting through terminal\npanes for the one that needs you.\n\nherdr is the state authority (it normalizes 15+ agents into one status model and\na JSON socket API); this app is a **socket client + notch NSPanel UI**. The core\nhydrates from snapshots, reconciles agent state continuously, and treats events as\nan accelerator. The UI stays thin and every response remains explicitly user-driven.\n\n- Shows a minimal color-coded status line below the notch, revealing the agent count on hover or keeping it visible if you prefer.\n- Opens the relevant interaction when an agent becomes blocked and needs input.\n- Collects every herdr session in one overview with status, prompt, elapsed time, and a direct jump back to its terminal pane.\n- Turns supported approvals and questions into explicit, clickable actions while preserving a terminal fallback for anything uncertain.\n- Displays and cycles Claude and Codex interaction modes from the focused\npanel's\n**Mode** button, including Claude Auto mode when it is available. - Supports display placement, global hotkeys, sounds, Do Not Disturb, and launch at login without adding a Dock icon.\n\n| Minimal blocked indicator | Agent count on hover |\n|---|---|\n\n- macOS 14+ on Apple Silicon, Swift 6.2 toolchain (Xcode 16+).\n, with a terminal client attached to it, before NotchAgent can discover or control agents.[herdr](https://herdr.dev)must be installed and running- No third-party dependencies (Foundation/AppKit/SwiftUI + POSIX sockets).\n\nWith Homebrew:\n\n```\nbrew install --cask ykushch/tap/notchagent\n```\n\nAlternatively, download `NotchApp-<version>.zip`\n\nfrom GitHub Releases, extract\nit, and move `NotchApp.app`\n\nto `/Applications`\n\n.\n\nRelease bundles are ad-hoc signed rather than notarized, so macOS may block the\nfirst launch. Right-click the app and choose **Open**, or remove quarantine:\n\n```\nxattr -dr com.apple.quarantine /Applications/NotchApp.app\n```\n\nTo build an app bundle from source:\n\n```\n./bundle.sh && open build/NotchApp.app\n```\n\nOn first launch, grant **Notch Agent** access in **System Settings → Privacy &\nSecurity → Accessibility**. This permission is required for global shortcuts and\nagent actions; if a stale denied entry exists, remove it with the − button first.\n\n```\nswift build            # all targets\nswift test             # full test suite (swift-testing)\n```\n\nGitHub Actions builds and tests every push and pull request to `main`\n\non the\n`macos-15`\n\nrunner with Xcode 16.4. A pushed version tag runs the same tests,\nbuilds `NotchApp-<version>.zip`\n\n, verifies the app and archive signatures,\npublishes a GitHub Release with generated notes, and updates the Homebrew cask.\n\nThe release workflow needs one repository secret named `HOMEBREW_TAP_TOKEN`\n\n.\nCreate a fine-grained personal access token restricted to the\n`ykushch/homebrew-tap`\n\nrepository with **Contents: Read and write**, then add it\nunder **Settings → Secrets and variables → Actions** in this repository. The\nbuilt-in `GITHUB_TOKEN`\n\npublishes the release itself and does not need another\nsecret.\n\nOnce that secret is configured, releasing is just:\n\n```\ngit tag -a v1.2.3 -m \"NotchAgent 1.2.3\"\ngit push origin v1.2.3\n```\n\nTags must contain numeric dot-separated versions (`v1.2.3`\n\n); the workflow passes\nthe version to `bundle.sh`\n\nand writes the resulting archive SHA-256 into the tap.\n\nDogfoods the whole core (client + store + classifier + actions) before/without\nthe UI. Thin wrapper: all logic lives in the `HerdrClient`\n\nlibrary.\n\n```\nswift run notchctl list                      # list all agents + rollup status (F1)\nswift run notchctl watch                     # stream status changes; classify blocks (F1/F2/F4)\nswift run notchctl read  <pane>              # show the classified prompt for a pane (F4)\nswift run notchctl --json read <pane>         # normalized evidence + proposed response plans\nswift run notchctl --json inspect <fixture>   # verify and inspect an offline .fixture directory\nswift run notchctl --json dry-run <pane> option 2 # re-read + plan; never send input\nswift run notchctl resolve <pane> <choice>   # choice = approve | deny | <option number> (F3/F4)\nswift run notchctl reply <pane> <text...>    # free-text reply, submits with enter (F4/F9)\nswift run notchctl jump  <pane>              # focus the pane + present its terminal (F5)\n```\n\nGlobal flags: `--json`\n\n(machine-readable output), `--sock <path>`\n\n(explicit\nsocket path; otherwise resolved from `HERDR_SOCKET_PATH`\n\n→ `HERDR_SESSION`\n\n→\n`~/.config/herdr/herdr.sock`\n\n).\n\nExample:\n\n``` bash\n$ swift run notchctl list\n● w3:p1           working  claude   /Users/you/project *\n○ w1:p1           idle     claude   /Users/you/other\n```\n\n`resolve`\n\n/`reply`\n\nread the pane's current prompt via `pane.read --source detection`\n\n,\nclassify it, and send validated key-combo tokens (herdr rejects `prefix+`\n\nbindings).\nUnknown prompt shapes fall back to a raw view — the tool never fabricates a keystroke.\n\n`read --json`\n\nreports the normalized provider and screen adapter, stable\nfingerprint, interaction kind/content, choices/steps, presentation state,\ncapabilities, confidence, pane revision, and every proposed response plan or\nexplicit refusal. Output keys are sorted so identical evidence produces\nbyte-identical JSON. Raw terminal bytes are deliberately excluded; use\n`capture`\n\nfor raw evidence and `inspect`\n\nfor normalized diagnostics.\n\n`inspect <path>`\n\nverifies and parses a content-addressed `.fixture`\n\ndirectory\nwithout connecting to herdr. A standalone detection file is also supported with\n`--agent ID`\n\nand optional `--visible FILE`\n\n, `--pane ID`\n\n, and `--revision N`\n\n.\n\n`dry-run <pane> <intent>`\n\nreads the interaction once, immediately re-reads it,\ncompares stable fingerprints, and plans from the fresh presentation. Its core\nboundary has no action/transport sender and cannot write input. Supported intents\nare `option N`\n\n, `check N`\n\n, `uncheck N`\n\n, `type TEXT`\n\n, `text TEXT`\n\n,\n`option-text N TEXT`\n\n, `add-notes`\n\n, `clear-notes`\n\n, `previous`\n\n, `next`\n\n, `step N`\n\n,\n`submit`\n\n, `approve`\n\n, `deny`\n\n, and `cancel`\n\n. Pass\n`--expected-fingerprint HEX`\n\nto audit a previously observed identity.\n\n```\nswift run NotchApp\n```\n\nRuns as an **accessory app** (no Dock icon, never steals focus). A non-activating\nalways-on-top `NSPanel`\n\nsits around the notch: a minimal status line reveals the\nagent count on hover (or stays visible by preference), and a blocked agent opens\ndirectly into its actionable interaction.\nSee [ Sources/NotchApp/README.md](/ykushch/agsig/blob/main/Sources/NotchApp/README.md) for the manual\ntest checklist.\n\n`Sources/HerdrClient/`\n\n— the M1 core (socket client, models, state store, prompt classifier, action layer). Seefor architecture + the protocol facts that shaped it.`CLAUDE.md`\n\n`Sources/notchctl/`\n\n— the CLI harness.`Sources/NotchApp/`\n\n— the notch UI (M2).`Tests/HerdrClientTests/`\n\n— swift-testing suite over recorded fixtures.", "url": "https://wpnews.pro/news/notchagent-native-macos-notch-control-for-ai-agents-running-under-herdr", "canonical_source": "https://github.com/ykushch/agsig", "published_at": "2026-07-22 21:43:42+00:00", "updated_at": "2026-07-22 21:52:54.311866+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["NotchAgent", "herdr", "Apple", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/notchagent-native-macos-notch-control-for-ai-agents-running-under-herdr", "markdown": "https://wpnews.pro/news/notchagent-native-macos-notch-control-for-ai-agents-running-under-herdr.md", "text": "https://wpnews.pro/news/notchagent-native-macos-notch-control-for-ai-agents-running-under-herdr.txt", "jsonld": "https://wpnews.pro/news/notchagent-native-macos-notch-control-for-ai-agents-running-under-herdr.jsonld"}}