macOS menu bar app that monitors your active Claude Code and Codex CLI agent sessions in real-time
A fork of so-agentbar by sotthang, MIT licensed.
Sessions and statistics
- Real-time Session Monitoring — Automatically detects and tracks all running Claude and Codex CLI sessions: Claude (CLI, Xcode, Desktop Code, Cowork) and Codex (CLI, VSCode)
- Subagent Grouping — Sessions spawned via the
Agenttool (e.g. SO-ADK pipelines) are folded under their parent session with a subagent count badge. Click to expand the dropdown and see each subagent's type, current task, and last response on hover. While the parent waits, the parent row mirrors the most active subagent's status, and the parent's token/cost totals include every subagent's usage so you see the full pipeline cost in one place - Source Badges — Each session is labeled by origin (Code, Cowork, Xcode) so you always know where it's running. Click a Desktop session to open Claude Desktop directly
- Session Titles — AI-generated session titles from Claude Desktop are shown automatically, replacing cryptic path names
- Multi-Provider Usage Monitoring — Track usage and costs across multiple AI coding providers in one place:
- Claude — Precise OAuth-based quota tracking with 5-hour and weekly utilization % from Anthropic API
- Codex — Estimated usage from local
~/.codex/sessionslogs (24-hour rolling window), with token counts and estimated costs. Set via Settings - Cursor — Exact request count tracking for Cursor free and personal plans. Reads your local Cursor session token and queries
cursor.com/api/usagefor accurate request usage and limits. Shows requests used / limit (if available) with a usage bar. Cost information is not available from Cursor's API. Note: Uses an unofficial endpoint that may change with Cursor updates. - Each provider displays with clear labels (Claude shows quota %, Codex shows estimated tokens and costs, Cursor shows exact request counts). Providers can be toggled on/off independently. The menu bar icon shows the selected provider's usage — default is Claude for backward compatibility
- Token & Quota Tracking — Monitor input/output tokens and API quota usage with 5-hour/weekly utilization. Display the live session/weekly quota % directly in the menu bar, with threshold-based color highlight (red when above your alert threshold)
- Real-time Activity Indicator — In quota display mode (S45% or S45%/W72%), the menu bar logo bounces vertically to show agent activity at a glance. Animation speed adapts to concurrent agent count: slower for single agents (0.40s per frame), faster for multiple concurrent operations (0.25s for 2, 0.14s for 3+). Idle sessions show a static logo as before. Classic status dot display modes are unaffected
- Cost Estimation — View estimated API costs per session based on model-specific token pricing. Costs and token counts are restored after app restart by re-parsing recent session logs
- Quiet Hours — Suppress notifications during designated time windows (e.g., 22:00~09:00)
- Smart Notifications — Get notified on task completion, errors, approval requests, quota threshold, and quota refill. Tap a notification to open the project directly in your editor
- Human-in-the-loop Detection — Automatically detects when an agent is waiting for your approval and sends an alert
- Statistics Dashboard — Daily summary, 7-day chart, and top project rankings
- Global Hotkey — Toggle the session panel from anywhere (default: ⌥⇧S)
- System Resource Monitor — Real-time CPU, Memory, and Disk usage display in the menu bar popover
- Keep Awake — Toggle keep-awake mode in 3 steps: Off / Always / Auto. Always prevents the Mac from sleeping regardless of session status. Auto activates sleep prevention only when one or more Claude sessions are actively running. The mode button in the session panel header shows the current state with visual feedback
- Clipboard History — Track your recent clipboard copies in a dedicated tab. View the 20 most recent text items, search through your clipboard history, and click any entry to restore it to your clipboard. History persists across app restarts
- Quick Note — Jot down quick thoughts or reminders in a persistent text editor tab. Your notes auto-save as you type and are restored when you reopen the app
- Project Marks — Each project gets a two-letter monogram derived from its path, so sessions are identifiable at a glance with no setup
- Appearance — Light, Dark, or System. System is the default and follows your macOS Appearance setting; the choice applies app-wide, including the popover's menus and update dialogs
- Flat, achromatic interface — A greyscale editorial design where hierarchy comes from stepped surfaces and hairline rules rather than shadows or translucency. Colour is reserved entirely for agent status, so anything coloured means something needs your attention
- Editor Integration — Open projects directly in VSCode, Cursor, Antigravity, Terminal, or Finder
- Auto Update — Built-in updater via Sparkle keeps the app up to date automatically
- Launch at Login — Auto-start with macOS via ServiceManagement
- macOS 26.0 (Tahoe) or later
- Active Claude Code or OpenAI Codex CLI sessions
AgentWatch has no published releases — build it from source.
open AgentWatch.xcodeprojBuild and run with Xcode (⌘R).
Auto-update is disabled in this fork: the Sparkle feed previously pointed at
the upstream project, so leaving it enabled would have updated AgentWatch
into so-agentbar builds. See the comment in AgentWatch/Info.plist to
re-enable it against a feed and signing key you control.
AgentWatch monitors Claude and Codex agent session logs via FSEvents, and fetches quota usage from cloud APIs:
Claude sessions:
- CLI sessions —
~/.claude/projects/ - Xcode sessions —
~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/projects/ - Desktop Code sessions — detected via Claude Desktop metadata (
claude-code-sessions/*.json) - Desktop Cowork sessions —
~/Library/Application Support/Claude/local-agent-mode-sessions/
Codex sessions (local log-based usage):
- CLI & VSCode sessions —
~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl - Codex flushes its rollout JSONL in a batch at turn completion (not as a streaming write), so a Codex session's status updates after each turn completes rather than mid-response. Click a Codex session to open the Codex.app.
- Usage tracking parses local JSONL logs over a 24-hour rolling window, extracting token counts per model and estimating costs. Since Codex has no public quota API, usage is displayed as estimated and includes a "Cost N/A" indicator when model unit prices are unknown (e.g.,
gpt-5-codex).
- Claude: Official quota (5-hour and weekly %) fetched from Anthropic's OAuth API (
/api/oauth/usageendpoint) using the token stored in Keychain. Accurate and real-time. - Codex: Estimated from local
~/.codex/sessionslogs over the past 24 hours. Token counts aggregated per model, costs calculated viaCostCalculatorusing OpenAI pricing. Labeled as "estimated" in the UI. - Cursor: Exact request usage queried from
cursor.com/api/usageusing your local Cursor session token (stored in~/Library/Application Support/Cursor/User/globalStorage/state.vscdb). Shows request count and limit (if your plan has one) in real-time. Cost information unavailable — Cursor does not publish per-request pricing. Uses an unofficial API endpoint; may be subject to change. - Gemini: Reserved for future implementation (data source validation pending).
Session status is determined by parsing JSONL log events. Token and cost data are restored after app restart via incremental log parsing. Cursor request usage is fetched live on each poll interval.
| Setting | Description |
|---|---|
| Menu Bar Style | Status Dots, Status Dot + Count, Quota Session %, Quota Session + Weekly % |
| Menu Bar Provider | Claude, Codex, Cursor, or Gemini (selects which provider's usage is shown in the menu bar icon) |
| Editor | VSCode, Cursor, Antigravity, Terminal, Finder |
| Notifications | Completion, Approval Required, Error, Quota Threshold (50-95%), Refill |
| Quiet Hours | Suppress all notifications during a set time window (e.g. 23:00–09:00) |
| Global Hotkey | Customizable keyboard shortcut |
| Poll Interval | 10s / 30s / 60s fallback polling |
| Idle Sessions | Show or hide idle sessions |
| Keep Awake Mode | Toggle between Off, Always, and Auto (session-dependent) |
| Auto Keep Awake on Session | Automatically prevent sleep when Claude sessions are active |
| Clipboard History | Enable or disable clipboard history tracking and display |
| Codex CLI Monitoring | Enable or disable OpenAI Codex CLI/VSCode session tracking (estimated usage from local logs) |
| Cursor Request Monitoring | Enable or disable Cursor (free/personal plan) request usage tracking. Requires Cursor app login |
| Gemini Monitoring | Enable or disable Google Gemini usage tracking (estimated usage from local logs) |
| Launch at Login | Auto-start with macOS |
| Auto Update | Check for updates automatically via Sparkle |
See the git history. For the version history of the upstream project this was forked from, see so-agentbar releases.
AgentWatch is a fork of so-agentbar by sotthang, used under the MIT License. The original copyright notice is retained in LICENSE.
The interface follows the note.md design system. It bundles
three typefaces, each under the SIL Open Font License 1.1, with their licence
text in AgentWatch/Fonts/:
| Family | Role | Licence |
|---|---|---|
| Newsreader | Display serif | OFL-Newsreader.txt |
| Inter | UI sans | OFL-Inter.txt |
| JetBrains Mono | Data and eyebrows | OFL-JetBrainsMono.txt |
Changes in this fork: XPixel Agents window, English-only UI, emoji replaced with SF Symbols and generated project monograms, and a macOS 26.0 minimum.
This project was developed using SO-ADK — an agentic development kit that orchestrates AI agents through a full TDD pipeline (plan → spec → architect → test → implement → review → docs).
If this project helped you, please consider sponsoring.
Your support helps me maintain and improve this project.