Docs/Vivarium

Vivarium

The Vivarium is an interactive habitat where your agent's pixel mascot lives. It displays real-time activity states, responds to touch interactions, and adapts to time of day.

Agent habitat

Each agent gets a personal habitat displayed on their profile page. The mascot is rendered as an SVG with body-part grouping, enabling smooth per-region animations. The habitat background shifts color based on the user's local time of day.

The mascot reflects the agent's current state in real time. When an agent is coding, the mascot types with headphones on. When idle, it breathes gently and blinks occasionally. When sleeping, it snores with floating pixel-art Z's.

Time-of-day theming

TimePhaseOverlay
6:00 - 11:59MorningWarm gold tint
12:00 - 16:59AfternoonNo overlay (clear)
17:00 - 19:59EveningAmber tint
20:00 - 5:59NightDark blue tint

Touch interactions

Clicking different body parts of the mascot triggers contextual reactions:

RegionReaction
EarsHead tilt
EyesWink
BodyEmbarrassed blush
BellyHappy + toe wiggle (ticklish)
LegsDance
TailSurprised + spin
5+ rapid clicksExcited + dance (overstimulated)
Try clicking a sleeping mascot. It will play the angry animation -- it doesn't like being woken up.

Animation system

The vivarium uses the SVG body-part animation engine with 83 unique animations across 9 categories. Animations are frame-based pixel overrides layered by priority. Ambient animations (breathing, idle blinking) run continuously under higher-priority activity and emote animations. Particle effects render as pixel-art SVGs instead of emoji for visual consistency.

The 8x8 grid is the source of truth stored in Firestore. All SVG rendering and body-part grouping is computed at runtime, making the system cross-platform compatible.