Pets & floating status
Ghostex can show a draggable animated pet overlay on the desktop. The pet doubles as a compact status surface — click activity items to jump to sessions, or sleep the pet from Settings.
OptionalFloatingSprites
Enable the pet
| Option | What it does |
|---|---|
petOverlayEnabled | Settings → Status Indicators → "Wake Pet". Off by default on new installs. |
selectedPetId | Choose the pet sprite. Default: boo. |
You can also wake the pet from the command palette (search “pet” in command mode with a leading >).
Available pets
| Option | What it does |
|---|---|
boo | A friendly ghost for quiet workspace focus. (Default) |
codex | The original Codex companion. |
dewey | A tidy duck for calm workspace days. |
fireball | Hot path energy for fast iteration. |
rocky | A steady rock when the diff gets large. |
seedy | Small green shoots for new ideas. |
stacky | A balanced stack for deep work. |
bsod | A tiny blue-screen companion. |
null-signal | Quiet signal from the void. |
Floating overlay behavior
- The pet renders in a borderless, non-activating floating NSPanel that stays above other windows.
- Drag the pet to reposition it; Ghostex remembers the anchor side and origin.
- Activity items show working and attention sessions — click to focus the session in Ghostex.
- Status counters mirror menu bar working/done indicators when visible.
- Sleep the pet from the overlay or disable petOverlayEnabled in Settings.
Relationship to status indicators
The pet overlay is independent from the AppKit floating session status indicator and menu bar counters. You can show the pet while hiding other status surfaces, or vice versa:
| Option | What it does |
|---|---|
hideFloatingSessionStatusIndicators | Hides the numeric floating status panel (separate from the pet). |
hideMenuBarSessionStatusIndicators | Hides menu bar working/done counters. |
sessionStatusIndicatorSize | Controls the non-pet floating indicator size (medium default). |
Credits
Boo is bundled from verified CodexPetHub pet assets. The pet system draws inspiration from the Codex on Linux pets implementation. Pet metadata is static in-app data — spritesheets only, no executable behavior.