ContextQMD
Back to Openclaw

Menu bar icon

docs/platforms/mac/icon.md

2026.7.12.8 KB
Original Source

Menu Bar Icon States

Scope: macOS app (apps/macos). Rendering: CritterIconRenderer.makeIcon(...). Animation/state wiring: CritterStatusLabel + CritterStatusLabel+Behavior.swift.

States

StateTriggerVisual
IdleDefaultNormal blink/wiggle animation
PausedisPaused=trueStatus item uses appearsDisabled; no motion
Voice wake (big ears)Wake word heardEars scale to 1.9x with earHoles=true (circular holes for readability); drops after silence
WorkingisWorking=true or an active IconStateFaster leg wiggle (legWiggle up to 1.0) plus a small horizontal offset; additive to idle wiggle

A tool-activity badge (SF Symbol puck, e.g. chevron.left.slash.chevron.right for exec) can render on top of the same critter icon when a session has an active job or tool. That badge comes from IconState/ActivityKind; see Menu bar for the full state model.

Voice wake ears

  • Trigger: AppStateStore.shared.triggerVoiceEars(ttl: nil), called from the voice-wake capture pipeline (VoiceWakeRuntime) and from voice-wake debug/test tooling (VoiceWakeTester, VoiceWakeOverlayController).
  • Stop: stopVoiceEars(), called when capture finalizes.
  • Silence window before finalizing: 2.0s normally, 5.0s if only the trigger word was heard and no further speech followed (VoiceWakeRuntime.silenceWindow / triggerOnlySilenceWindow).
  • While boosted, idle blink/wiggle/leg/ear timers are suspended (earBoostActive gates the animation task in CritterStatusLabel+Behavior).

Shapes and sizes

  • Canvas: 18x18pt template image, rendered into a 36x36px bitmap backing store (2x) so the icon stays crisp on Retina.
  • Ear scale defaults to 1.0; voice boost sets earScale=1.9 and earHoles=true without changing the overall frame.
  • Leg scurry uses legWiggle up to 1.0 with a small horizontal jiggle.

Behavioral notes

  • No external CLI/broker toggle for ears or working state; both are driven internally by app signals (AppState.setWorking, AppState.triggerVoiceEars) to avoid accidental flapping.
  • Keep any new TTL short (well under 10s) so the icon returns to baseline quickly if a job hangs.