Skip to content

About

A menubar which helps manage AI coding agents.

Resources

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

AgentMenuBar

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.

AgentMenuBar popover showing running, waiting, and finished agent sessions

Why this exists — agent overload

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.

How it works

  1. Listening to the agent CLI's documented hook events:
    • Factory Droid: Notification, Stop, SessionStart, SessionEnd, UserPromptSubmit, plus PreToolUse/PostToolUse for interactive AskUser prompts.
    • Codex CLI: SessionStart, UserPromptSubmit, Notification, PermissionRequest, PreToolUse(request_user_input), PostToolUse, and turn-scoped Stop.
    • Cursor CLI (cursor-agent): sessionStart, beforeSubmitPrompt, beforeShellExecution/beforeMCPExecution, afterShellExecution/afterMCPExecution, afterFileEdit, postToolUse, turn-scoped stop, and sessionEnd.
    • Claude Code: SessionStart, UserPromptSubmit, Notification (permission_prompt/elicitation_dialog only), PermissionRequest, PostToolUse, SubagentStop, turn-scoped Stop, and SessionEnd.
  2. Capturing each session's ITERM_SESSION_ID at start.
  3. 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.

Supported CLIs

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.

Status

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/.

Architecture

 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_ID captured once at SessionStart.
  • 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).

Quick start

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).

Codex check

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-mode request_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.

Manual test (no real agent required)

make run
# in another terminal, inside iTerm:
make test-event   # runs scripts/send-test-event.sh: SessionStart, UserPromptSubmit, Notification, Stop

You'll see four notifications and one row in the popover, ending in "Finished task".

Status states

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.

Known limits (by design in v1)

  • 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-agent exposes no notification/permission-request event, and its interactive AskQuestion picker 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.json file 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 for UNUserNotificationCenter.

Requirements

  • macOS 13+ (Ventura) — tested on 26 (Tahoe)
  • Xcode CLT / Swift 5.9+
  • iTerm2
  • jq, nc, osascript (all preinstalled on macOS)

Layout

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

Make targets

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

Roadmap (post-v1)

  • Proper .app bundle for Login Items and signed UNUserNotificationCenter notifications.
  • "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 beforeShellExecution approximation.

License

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.

About

A menubar which helps manage AI coding agents.

Resources

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages