Agent Monitor: native desktop widgets for Claude Code and Codex. Usage limits at a glance, plus a live list of sessions stuck on approvals, questions or your next prompt.
My usual afternoon looks like this: three or four Claude Code and Codex sessions running in parallel, in different projects, in different windows. One is refactoring an API, one is writing tests, one is fixing a landing page.
And every twenty minutes I discover that one of them has been sitting there for a quarter of an hour, politely waiting for me to approve npm run deploy. Another one asked me a question and went idle. A third finished ages ago and I never noticed.
The agents got fast. I became the bottleneck. So I built a small thing to fix that.
Meet Agent Monitor
Agent Monitor is a native macOS app with WidgetKit widgets and a menu bar icon. It answers two questions without me opening anything:
- Who is waiting on me, and why?
- How much of my usage limits is left?
The Waiting on you list puts blockers first, in red: a tool call that needs approval, a question from the agent, a plan to review. Below them are sessions that finished their turn and want the next prompt. Each row shows the session title, the project folder and how long it's been waiting.
Click a row and you land in that exact session: in the Claude or Codex desktop app, or in the right Terminal / iTerm2 tab. The menu bar icon shows a live count and turns red when something is blocked.
The second half is usage. Claude Code and Codex both meter you on a rolling 5-hour window and a weekly one. Hitting either in the middle of a task is annoying, and checking means typing a slash command or digging through a settings page. So there are rings and bars with countdowns to each reset, amber at 75% and red at 90%.
How "waiting on you" actually works
Both Claude Code and Codex support lifecycle hooks: shell commands the agent runs on events like Stop, PermissionRequest or UserPromptSubmit, with a JSON payload on stdin. The event names are almost identical between the two, which made supporting both pretty cheap.
The installer adds one hook entry per event to ~/.claude/settings.json and ~/.codex/hooks.json. It points at the app's own binary:
{ "hooks": { "PermissionRequest": [ { "hooks": [{ "type": "command", "command": "'/Applications/AgentMonitor.app/Contents/MacOS/AgentMonitor' --hook claude", "timeout": 5 }] } ] } } When the agent fires an event, the binary reads the JSON, maps it to a state and writes a tiny file per session:
| Event | State |
|---|---|
PermissionRequest, Claude Notification: permission_prompt | Needs approval |
Claude AskUserQuestion, elicitation_dialog | Question for you |
Claude ExitPlanMode | Plan to review |
Stop with nothing running in the background | Your turn |
UserPromptSubmit, PostToolUse | working (hidden) |
SessionEnd, or the agent process is gone | removed |
The hook has one hard rule: print nothing and always exit 0. Hooks in both agents can block actions or inject context depending on what they output. A monitoring tool must never do that, so the handler is deliberately mute, even when the payload is garbage.
A few details that took more than one try:
-
Stopdoesn't always mean "done". If the session still has background tasks or scheduled jobs, the agent isn't really waiting on you. Those sessions stay in the "working" state. - Sessions die without saying goodbye. You close a terminal tab, and
SessionEndnever arrives. The hook records the agent's PID, and the app checks it withkill(pid, 0). If the process is gone, the row disappears. - Jumping to the exact session. The Claude desktop app passes its session id to hooks in an environment variable, and both apps have deep links (
claude://code/continue?session=…,codex://threads/<id>). For terminals, the hook finds the controlling TTY of the agent process, and a bit of AppleScript selects that tab in Terminal or iTerm2. Neither deep link is a documented API, so this may break someday. - Don't trash the user's config. The installer merges into existing hook settings, recognizes its own entries by command, and saves a backup next to the file. Disconnecting removes only its own hooks.
Why there's a menu bar app at all
WidgetKit extensions are sandboxed. They can't read the Keychain, where Claude Code keeps its OAuth token, or ~/.codex/auth.json. So the architecture is boring on purpose:
- A small non-sandboxed menu bar app fetches usage every two minutes and watches the sessions folder.
- It writes a JSON snapshot and calls
reloadTimelines. - The widget only has read access to that one folder and just draws.
Usage comes from the same endpoints the official tools use internally: api.anthropic.com/api/oauth/usage for Claude and chatgpt.com/backend-api/wham/usage for Codex. If the Codex one isn't reachable, the app falls back to the latest rate_limits event in your local Codex session logs. Both endpoints are undocumented, so I put that in big letters in the README.
Tokens never leave your Mac except to those same Anthropic and OpenAI endpoints. No analytics, no telemetry, no servers of mine.
Things macOS taught me along the way
Widgets lag, by design. macOS gives a background app a redraw budget of roughly every 15 to 30 minutes. That's fine for usage rings and not fine for "an agent needs you right now". That's why the real-time part lives in the menu bar, and the widget is the overview.
The widget gallery caches aggressively. Rebuild the app with a changed view, and the gallery happily keeps showing the old one. The fix that actually works: bump the build number on every install and restart the widget daemon (killall chronod). The install script now does both.
Screenshots are rendered from code. Every image in this post, the cover included, is generated by a small Swift script that imports the real widget views and renders them with SwiftUI's ImageRenderer on top of demo data. When the UI changes, I re-run one script and the README stays honest. I'd recommend this to anyone shipping a SwiftUI app with a README.
Try it
You need macOS 14+, Xcode (WidgetKit extensions can't be built with the Command Line Tools alone) and Claude Code and/or Codex signed in. No Apple Developer account needed: the app is signed to run locally.
git clone https://github.com/paveler/agent-monitor.git cd agent-monitor ./scripts/install.sh Then right-click the desktop → Edit Widgets… → Agent Monitor, and connect your agents from the menu bar icon → Integrations.
It's MIT-licensed and about 1,400 lines of Swift. Ideas on the list: notifications near the limit, a usage history sparkline, and more agents (Gemini CLI, Cursor). PRs and issues welcome, especially if an undocumented endpoint changes under us.
How do you keep track of parallel agent sessions? Curious if anyone has a better workflow than "check every window every ten minutes".



