Skip to main content

​
AI Companion System

The companion system transforms your agent into a virtual companion with personality, emotional awareness, and a gamified growth system.

​
Features

15 Species + 9 Hats

Choose from 15 companion species and 9 hats, each rendered as custom SVG icons with rarity-based glow effects.

Agent Appearance Sync

Companion automatically changes species and hat when you switch agents — robot for Developer, owl for Researcher, fox for Writer. Custom agents with emoji avatars are mapped automatically.

23-State Animation Engine

Sprite overlay driven by a state machine with 23 step_key mappings. Three animation modes: transient (brief reactions), sticky (persistent states), and release (return to idle). Heartbeat timeout auto-recovery prevents stuck animations.

Desktop Pet Overlay

On Tauri Desktop, the companion floats as a transparent always-on-top window with drag support, 5 size presets, position memory, and right-click context menu. On WebUI/SaaS, it renders as an inline widget.

Growth & Evolution

5-tier rarity system (Common → Legendary) with stat evolution, XP progression, daily snack interactions, and birthday detection.

Anti-Fatigue UX

Routine errors are mapped to silent “review” animations instead of distressing failure faces. Approval requests trigger a friendly waving animation, not a loading spinner.

Community Petdex Gallery

Browse and install hundreds of community-created SpriteSheets from petdex.dev via a built-in gallery with Canvas thumbnails, lazy loading, search, and 1-click install. No manual URL entry required.

Dynamic Sprite Compatibility

The resolveAnimRow engine uses alias-based mapping to automatically adapt Codex 9-row, Legacy 8-row, and custom spritesheet formats. Any community sprite “just works” without manual configuration.

Cross-Device Config Sync

Companion preferences including selected sprite are persisted server-side via the /companion/config API. Switch devices or browsers without losing your personalization.

​
Configuration

  1. Navigate to Settings > Companion to enable the system
  2. Select a species and hat from 15 + 9 options
  3. Switch to the Gallery tab to browse community SpriteSheets from petdex.dev — search, preview, and install with one click
  4. Your selected sprite and configuration are automatically synced across devices via the server API
  5. The companion automatically syncs with your active agent’s avatar

​
How It Works

The companion system operates on two visual layers:
  • SVG Layer (default): Lightweight icon-based rendering embedded near the chat input. Automatically reflects the active agent’s identity through species and hat changes.
  • Sprite Layer (optional): Full Canvas 2D animation engine supporting Codex 8×9 standard SpriteSheets (1536×1872px). On Desktop, renders in a native transparent window; on WebUI, renders as a draggable overlay. The resolveAnimRow engine automatically detects Codex (9-row) vs Legacy (8-row) layouts and maps animation states via aliases, ensuring all community sprites display correctly.
The state machine receives events from the agent’s SSE stream and maps them to animations:
  • workflow_planning → Thinking (sticky)
  • workflow_execution → Running (sticky)
  • approval_waiting → Waving (sticky)
  • consensus_reference_done → Celebrating (transient)
  • model_failover → Failed (transient)
All state is managed via Zustand with localStorage persistence. Companion preferences sync to the server via the /companion/config API.

​
Verified Quality

The companion system is backed by 229 unit tests across 9 test files, with core module coverage:
  • PetStateMachine: 100% line coverage
  • CompanionSprite: 91.83% line coverage
  • tauriPetBridge: 100% line coverage
  • companionGenerator: 99.13% line coverage