How the Menu Bar Tracks Agent Activity

I hate it when background processes feel like a black box. You see a generic icon in your menu bar and have no idea if the tool is actually working, stuck, or just idling. I prefer a status indicator that tells me exactly what’s happening without making me hunt through logs or open a separate dashboard.

Here is how our menu bar logic handles agent states so you always know what your sessions are doing.

What You’ll Need

• Paired nodes (visible via node.list).
• Access to agent events via the control channel.

Quick Start

1. Trigger a Job: Start a command execution. You will see the menu bar icon switch from the normal “idle” critter to a “working” state with a badge and animation.
2. Check the Status Row: Open the menu to see the first row. It follows the format <Session role> · <activity label>, such as Main · exec: pnpm test.
3. Observe Priority: If you have multiple sessions, the “main” session always wins. The icon only switches to a non-main session if the main one is idle.
4. Verify Activity Glyphs: Different tasks show different icons in the badge. For example, reading a file shows a 📄 (read) while running a command shows a 💻 (exec).

Visual States and Glyphs

The agent uses a Swift IconState enum to decide what you see:

enum IconState {
  case idle
  case workingMain(ActivityKind)
  case workingOther(ActivityKind)
  case overridden(ActivityKind) // Used for debug overrides
}

The specific glyphs mapped to activity kinds are:

• exec → 💻
• read → 📄
• write → ✍️
• edit → 📝
• attach → 📎
• Default → 🛠️

Debug Overrides

If you want to test the UI without running real jobs, I recommend using the debug override. Go to Settings ▸ Debug ▸ Icon override and choose from these options:

• System (auto) (The default behavior)
• Working: main
• Working: other
• Idle

This maps directly to IconState.overridden and stays active regardless of actual agent activity.

Troubleshooting

• Health status is missing: This is expected behavior. We hide the health status while work is active to keep the menu clean. It returns once all sessions are idle.
• Icon doesn’t update during rapid bursts: We use a TTL (Time To Live) grace period on tool results. This prevents the badge from flickering when tools finish and start in quick succession.

AI Setup Assistant

What’s Next

• Control Channel Event Handling
• Node Management and Pairing