A macOS menu-bar app that tracks running AI-agent sessions across terminal tabs, surfaces the ones waiting for your input, and one-click-focuses the exact tab. Factory Droid, Codex CLI, Cursor CLI (cursor-agent), and Claude Code are supported through thin hook bridges; other CLIs can plug in by normalising their hook payloads into the same socket event shape.
We started running half a dozen long-running coding agents in parallel — different repos, different tasks, all in their own iTerm tabs — and immediately hit "agent overload":
- Some are thinking, some are stuck waiting for a permission prompt or a clarifying question, some are done and idle.
- Every CLI plays the same little sound when it needs you, and none of them tell you which tab to look at.
- Cmd-tabbing through iTerm windows to find the one with the orange dot doesn't scale past three or four agents.
AgentMenuBar is the dashboard we wanted: at a glance, how many agents are running, waiting on you, or finished; one click to jump straight to the exact iTerm tab; and the menu-bar glyph flashes orange the moment anything goes from running to waiting, so you can stop watching for it.
- Listening to the agent CLI's documented hook events:
- Factory Droid:
Notification,Stop,SessionStart,SessionEnd,UserPromptSubmit, plusPreToolUse/PostToolUsefor interactiveAskUserprompts. - Codex CLI:
SessionStart,UserPromptSubmit,Notification,PermissionRequest,PreToolUse(request_user_input),PostToolUse, and turn-scopedStop. - Cursor CLI (
cursor-agent):sessionStart,beforeSubmitPrompt,beforeShellExecution/beforeMCPExecution,afterShellExecution/afterMCPExecution,afterFileEdit,postToolUse, turn-scopedstop, andsessionEnd. - Claude Code:
SessionStart,UserPromptSubmit,Notification(permission_prompt/elicitation_dialogonly),PermissionRequest,PostToolUse,SubagentStop, turn-scopedStop, andSessionEnd.
- Factory Droid:
- Capturing each session's
ITERM_SESSION_IDat start. - Showing one row per active agent in a popover, with click-to-focus that selects the exact iTerm window + tab.
No accessibility automation, no terminal scraping. Hooks + iTerm's own session UUID + AppleScript only.
| Agent CLI | Hook source | Waiting signal | Done signal | Notes |
|---|---|---|---|---|
| OpenAI Codex CLI | ~/.codex/hooks.json |
PermissionRequest, Notification, and PreToolUse(request_user_input) |
turn-scoped Stop |
Works after reviewing/trusting the hook in /hooks. Tested with real Codex UserPromptSubmit/PostToolUse hooks and manual lifecycle events. |
| Factory Droid | ~/.factory/settings.json |
Notification and PreToolUse matcher AskUser |
turn-scoped Stop or SessionEnd |
Existing Droid sessions need restart after hook changes because Droid snapshots hooks at startup. |
Cursor CLI (cursor-agent) |
~/.cursor/hooks.json (shared with the Cursor IDE) |
beforeShellExecution / beforeMCPExecution (command/MCP approval gate) |
turn-scoped stop or sessionEnd |
Install via make install-cursor-hooks (kept out of the default install-hooks because the file is shared with the IDE). Cursor has no notification/permission-request event and its AskQuestion picker doesn't fire tool hooks, so a clarifying question isn't observable — see Known limits. beforeSubmitPrompt/stop only fire in interactive mode, not headless -p. |
| Claude Code | ~/.claude/settings.json |
PermissionRequest and Notification (permission_prompt/elicitation_dialog) |
turn-scoped Stop (deferred — see below) or SessionEnd |
Included in the default install-hooks. The jq merge only touches the hooks key, so other settings (model, permissions, …) are preserved. idle_prompt notifications (the ~60s post-turn nudge) are intentionally ignored so a finished turn doesn't get repainted as waiting. Stop doesn't finish outright: it moves to awaitingBackgroundWork until same-tab sub-agents or native background tasks (run_in_background shells, Monitor watchers) drain, tracked via SubagentStop and transcript scanning. Restart in-flight sessions and use /hooks to verify. |
Both CLIs use the same socket bridge and persisted session store. CLI-specific behavior lives in AgentEventAdapter, so adding another agent should mean adding a thin hook wrapper plus one adapter instead of changing the UI or store shape.
For the full process, see Adding a New CLI Agent.
v1. End-to-end pipeline is implemented and smoke-tested for Factory Droid, Codex CLI, Cursor CLI, and Claude Code (build → install → hook event → socket → persisted row → popover state). Build is clean. The Cursor and Claude Code lifecycles were verified through the bridge into the running app — Cursor (sessionStart → beforeSubmitPrompt → beforeShellExecution → afterShellExecution → stop) and Claude Code (SessionStart → UserPromptSubmit → PermissionRequest → PostToolUse → Stop → Notification(idle_prompt)) mapping to idle → running → waiting → running → awaitingBackgroundWork → awaitingBackgroundWork (the trailing idle nudge is ignored, not treated as a fresh question; SessionStore promotes to finished once no background work remains outstanding). State transitions are also covered by unit tests in Tests/.
Agent hook ──stdin JSON──▶ hooks/{factory,codex,cursor,claude-code}-event-bridge.sh
│
│ tags agent_kind and augments with
│ $ITERM_SESSION_ID, $TERM_PROGRAM, $PPID
▼
Unix domain socket: ~/Library/Application Support/AgentMenuBar/sock
│
▼
AgentMenuBar.app (Swift / SwiftUI)
│
AppleScript│
▼
iTerm2
- Canonical session id: agent-provided
session_id. - Focus key:
ITERM_SESSION_IDcaptured once atSessionStart. - Storage:
~/Library/Application Support/AgentMenuBar/sessions.json(atomic rename). - Debug log:
~/Library/Logs/AgentMenuBar/events.log(raw augmented payloads even when the app is offline).
make build # swift build (debug)
make install-hooks # additive merge into ~/.factory/settings.json and ~/.codex/hooks.json
make run # launches the menu bar app (no Dock icon)Open a supported terminal tab and run codex, droid, or claude. You should see a row appear in the menu bar popover. When the agent asks for input or approval, the row moves to waiting; clicking the row jumps to that exact terminal tab. (For Cursor CLI, run make install-cursor-hooks separately first — see Supported CLIs.)
For Codex CLI, open /hooks once after installing to review and trust the new hook definition. Codex loads hooks from ~/.codex/hooks.json; Factory Droid loads hooks from ~/.factory/settings.json.
To remove the hooks: make uninstall-hooks (your other hooks are preserved).
After make install-hooks and /hooks trust, start or continue a Codex session in iTerm. The app should:
- add/update a row on
UserPromptSubmit - turn the row orange on
PermissionRequest,Notification, or Plan-moderequest_user_input - turn it blue again on
PostToolUse - mark it green on
Stop
If Codex prints that hooks need review, open /hooks again; Codex records trust against the current hook definition hash, so edits require re-trust.
make run
# in another terminal, inside iTerm:
make test-event # runs scripts/send-test-event.sh: SessionStart, UserPromptSubmit, Notification, StopYou'll see four notifications and one row in the popover, ending in "Finished task".
| State | Colour | When |
|---|---|---|
| idle (READY) | cyan | After SessionStart/sessionStart — session alive, no prompt submitted yet |
| running | blue | After a prompt submit, or any tool/file/shell activity |
| waitingForInput | orange | On Factory Notification, Factory AskUser, Codex PermissionRequest, Codex Notification, Codex Plan-mode request_user_input, Cursor beforeShellExecution/beforeMCPExecution, or Claude Code PermissionRequest/Notification(permission_prompt|elicitation_dialog). Claude Code idle_prompt (post-turn idle nudge) is not a waiting signal — a finished turn stays DONE. |
| awaitingBackgroundWork (BACKGROUND) | purple | Claude Code only: after Stop, while a same-tab sub-agent or native background task (run_in_background shell, Monitor watcher) is still outstanding |
| finished | green | After Stop/stop or SessionEnd/sessionEnd (Claude Code: once awaitingBackgroundWork drains) |
| stale | grey | A previously-running session whose process disappeared |
The menu bar icon is grey when nothing's tracked, shows a count when sessions are active, and turns orange with an alert glyph when at least one session is waitingForInput.
- macOS only (built for macOS 13+; tested on 26).
- iTerm only — sessions started outside iTerm appear in the list but can't be focused.
- Factory Droid, Codex CLI, Cursor CLI, and Claude Code only. Other CLIs need a hook wrapper and an
AgentEventAdapter. - Cursor CLI waiting-state is approximate.
cursor-agentexposes no notification/permission-request event, and its interactiveAskQuestionpicker doesn't fire tool hooks, so the only hook-observable "needs you" moment is a shell/MCP approval gate (beforeShellExecution/beforeMCPExecution). With auto-run enabled this shows as a brief orange flicker rather than a sustained wait; a clarifying question won't turn the row orange at all. The~/.cursor/hooks.jsonfile is shared with the Cursor IDE, so installing also tracks IDE agent sessions (which appear as unfocusable rows since they aren't bound to a terminal tab). - No accessibility / screen-scraping.
- Notifications are emitted via
osascript display notification(so they appear under "Script Editor" in the system notification source). This is deliberate — it avoids needing a signed bundle forUNUserNotificationCenter.
- macOS 13+ (Ventura) — tested on 26 (Tahoe)
- Xcode CLT / Swift 5.9+
- iTerm2
jq,nc,osascript(all preinstalled on macOS)
docs/
adding-new-cli.md integration runbook for future CLI agents
popover.png screenshot used above
hooks/
agent-event-bridge.sh shared hook bridge: tag agent + forward to socket
factory-event-bridge.sh shell that Factory invokes
codex-event-bridge.sh shell that Codex invokes
cursor-event-bridge.sh shell that Cursor invokes (normalises conversation_id/workspace_roots)
claude-code-event-bridge.sh shell that Claude Code invokes
settings-hooks-block.json Factory reference snippet
codex-hooks-block.json Codex reference snippet
cursor-hooks-block.json Cursor reference snippet
claude-code-hooks-block.json Claude Code reference snippet
scripts/
send-test-event.sh fake-event harness for development
Sources/AgentMenuBar/
App/AgentMenuBarApp.swift @main, MenuBarExtra, accessory policy, server boot
Domain/ DroidSession, AgentKind, AgentEventAdapter,
HookEvent, SessionStatus,
RepoInfo, TranscriptReader
Store/ SessionStore (state machine) + JSON persistence
IPC/ BSD UDS server + JSON decoder
Focus/ITermFocuser.swift AppleScript focus by iTerm session UUID
UI/ MenuBarLabel, popover list, row
Notifications/ osascript-based notifier
| Target | What it does |
|---|---|
make build |
swift build (debug) |
make release |
swift build -c release |
make run |
build + launch (debug) |
make run-release |
build + launch (release) |
make stop |
kill any running AgentMenuBar |
make install-hooks |
additive jq merge into Factory, Codex, and Claude Code hook settings, backup first |
make uninstall-hooks |
inverse, prunes empty groups, backup first |
make install-factory-hooks |
additive jq merge into ~/.factory/settings.json, backup first |
make install-codex-hooks |
additive jq merge into ~/.codex/hooks.json, backup first |
make install-claude-hooks |
additive jq merge into ~/.claude/settings.json (preserves other keys), backup first |
make uninstall-claude-hooks |
inverse for Claude Code, prunes empty groups, backup first |
make install-cursor-hooks |
additive jq merge into ~/.cursor/hooks.json (shared with the IDE), backup first |
make uninstall-cursor-hooks |
inverse for Cursor, prunes empty groups, backup first |
make test-event |
send the demo event sequence to the running app |
make tail-events |
tail ~/Library/Logs/AgentMenuBar/events.log |
make clean |
swift package clean |
- Proper
.appbundle for Login Items and signedUNUserNotificationCenternotifications. - "Snooze attention" / per-session mute.
- Other terminals: Terminal.app, Warp, Ghostty (via per-terminal focuser adapters).
- More generic agent providers once their hook surfaces stabilise. Factory Droid, Codex CLI, Cursor CLI, and Claude Code are supported as of this version; for Cursor, a dedicated waiting/permission event would let us drop the
beforeShellExecutionapproximation.
Functional Source License, Version 1.1, MIT Future License (FSL-1.1-MIT) — copyright © 2026 Mindstone Learning Limited. You can use, modify, and redistribute the Software for any purpose other than offering it as a competing commercial hosted service. The license auto-converts to plain MIT on 2030-05-20.
