Menu bar

Menu Bar Status Logic

What is shown

• We surface the current agent work state in the menu bar icon and in the first status row of the menu.
• Health status is hidden while work is active; it returns when all sessions are idle.
• The “Nodes” block in the menu lists devices only (paired nodes via
  text

  Copy

  node.list
  ), not client/presence entries.
• A “Usage” section appears under Context when provider usage snapshots are available.

State model

• Sessions: events arrive with
  text

  Copy

  runId
  (per-run) plus
  text

  Copy

  sessionKey
  in the payload. The “main” session is the key
  text

  Copy

  main
  ; if absent, we fall back to the most recently updated session.
• Priority: main always wins. If main is active, its state is shown immediately. If main is idle, the most recently active non‑main session is shown. We do not flip‑flop mid‑activity; we only switch when the current session goes idle or main becomes active.
• Activity kinds:
  • text

    Copy

    job
    : high‑level command execution (
    text

    Copy

    state: started|streaming|done|error
    ).
  • text

    Copy

    tool
    :
    text

    Copy

    phase: start|result
    with
    text

    Copy

    toolName
    and
    text

    Copy

    meta/args
    .

IconState enum (Swift)

• text

  Copy

  idle
• text

  Copy

  workingMain(ActivityKind)
• text

  Copy

  workingOther(ActivityKind)
• text

  Copy

  overridden(ActivityKind)
  (debug override)

ActivityKind → glyph

• text

  Copy

  exec
  → 💻
• text

  Copy

  read
  → 📄
• text

  Copy

  write
  → ✍️
• text

  Copy

  edit
  → 📝
• text

  Copy

  attach
  → 📎
• default → 🛠️

Visual mapping

• text

  Copy

  idle
  : normal critter.
• text

  Copy

  workingMain
  : badge with glyph, full tint, leg “working” animation.
• text

  Copy

  workingOther
  : badge with glyph, muted tint, no scurry.
• text

  Copy

  overridden
  : uses the chosen glyph/tint regardless of activity.

Status row text (menu)

• While work is active:
  text

  Copy

  <Session role> · <activity label>
  • Examples:
    text

    Copy

    Main · exec: pnpm test
    ,
    text

    Copy

    Other · read: apps/macos/Sources/OpenClaw/AppState.swift
    .
• When idle: falls back to the health summary.

Event ingestion

• Source: control‑channel
  text

  Copy

  agent
  events (
  text

  Copy

  ControlChannel.handleAgentEvent
  ).
• Parsed fields:
  • text

    Copy

    stream: "job"
    with
    text

    Copy

    data.state
    for start/stop.
  • text

    Copy

    stream: "tool"
    with
    text

    Copy

    data.phase
    ,
    text

    Copy

    name
    , optional
    text

    Copy

    meta
    /
    text

    Copy

    args
    .
• Labels:
  • text

    Copy

    exec
    : first line of
    text

    Copy

    args.command
    .
  • text

    Copy

    read
    /
    text

    Copy

    write
    : shortened path.
  • text

    Copy

    edit
    : path plus inferred change kind from
    text

    Copy

    meta
    /diff counts.
  • fallback: tool name.

Debug override

• Settings ▸ Debug ▸ “Icon override” picker:
  • text

    Copy

    System (auto)
    (default)
  • text

    Copy

    Working: main
    (per tool kind)
  • text

    Copy

    Working: other
    (per tool kind)
  • text

    Copy

    Idle
• Stored via
  text

  Copy

  @AppStorage("iconOverride")
  ; mapped to
  text

  Copy

  IconState.overridden
  .

Testing checklist

• Trigger main session job: verify icon switches immediately and status row shows main label.
• Trigger non‑main session job while main idle: icon/status shows non‑main; stays stable until it finishes.
• Start main while other active: icon flips to main instantly.
• Rapid tool bursts: ensure badge does not flicker (TTL grace on tool results).
• Health row reappears once all sessions idle.

Related

• macOS app
• Menu bar icon