> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Companion System

> Gamified AI companion with 15 species, emotional awareness, and growth progression.

# AI Companion System

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

## Features

<CardGroup cols={2}>
  <Card title="15 Species + 9 Hats" icon="paw">
    Choose from 15 companion species and 9 hats, each rendered as custom SVG icons with rarity-based glow effects.
  </Card>

  <Card title="Agent Appearance Sync" icon="shuffle">
    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.
  </Card>

  <Card title="23-State Animation Engine" icon="wand-magic-sparkles">
    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.
  </Card>

  <Card title="Desktop Pet Overlay" icon="desktop">
    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.
  </Card>

  <Card title="Growth & Evolution" icon="arrow-up">
    5-tier rarity system (Common → Legendary) with stat evolution, XP progression, daily snack interactions, and birthday detection.
  </Card>

  <Card title="Anti-Fatigue UX" icon="shield-heart">
    Routine errors are mapped to silent "review" animations instead of distressing failure faces. Approval requests trigger a friendly waving animation, not a loading spinner.
  </Card>

  <Card title="Community Petdex Gallery" icon="store">
    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.
  </Card>

  <Card title="Dynamic Sprite Compatibility" icon="puzzle-piece">
    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.
  </Card>

  <Card title="Cross-Device Config Sync" icon="cloud">
    Companion preferences including selected sprite are persisted server-side via the `/companion/config` API. Switch devices or browsers without losing your personalization.
  </Card>
</CardGroup>

## 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