Bar Bud is ApexDock's animated companion at the launcher position (where Spotlight or the start button would be). It replaces the static grid icon with a sprite that reacts to what your agents and assistant are doing — listening, thinking, running tools, waiting for input.
ApexDock ships with Pip bundled at Resources/BarBuddies/pip, so a fresh install has a Bud available before you add anything custom.
Enabling
Settings → Bar Bud. Pick a Bud from the catalog (Pip is selected by default). Toggle off to fall back to the plain launcher icon.
Clicking the Bud opens the command palette the same way the start button does, plus a short click reaction animation.
Custom Buds
Drop a Bud package into either folder and it appears in the catalog on next launch:
~/Library/Application Support/ApexDock/pets/
${CODEX_HOME:-$HOME/.codex}/pets/
The Codex pets folder is shared so any Bud built for Codex's pet runtime works in ApexDock too, and vice versa.
Package shape
<bud-name>/
pet.json
spritesheet.png # or .webp
pet.json:
{
"id": "my-bud",
"displayName": "My Bud",
"description": "A compact Bar Bud for ApexDock.",
"spritesheetPath": "spritesheet.png"
}
The spritesheet is a fixed atlas:
| Image size | 1536 × 1872 |
| Grid | 8 columns × 9 rows |
| Cell size | 192 × 208 |
| Unused cells | Transparent |
Row semantics
| Row | State | When ApexDock plays it |
|---|---|---|
| 0 | idle | No active agent sessions |
| 1 | running-right | Reserved for future directional movement |
| 2 | running-left | Reserved for future directional movement |
| 3 | waving | An agent needs your input or approval |
| 4 | jumping | Click / boop reaction, success completion |
| 5 | failed | Errored agent session |
| 6 | waiting | Multiple sessions queued, or generic waiting state |
| 7 | running | Active tool-running work |
| 8 | review | Streaming, thinking, reading, or composing a reply |
Reduced-motion mode pins the Bud to row 0.
Speech bubble
While the assistant is talking or thinking, a SwiftUI speech bubble floats above the Bud with the live transcript. The bubble is rendered by ApexDock — don't bake captions or UI labels into the spritesheet.
The bubble follows the same listening / thinking / speaking states the bar's waveform does, just in conversational form. It dismisses on its own when the assistant finishes.
Notes
- The Bud is mutually exclusive with consolidated agent icons in the launcher slot — when a Bud is selected, the start button defers to it.
- Crashed sprite loads quietly fall back to the standard grid icon; the Bud doesn't block launching the palette.
- Bud packages don't run code. The runtime only reads
pet.jsonand the spritesheet image.