Miko Desktop Companion
A pixel desktop pet that mirrors 38 Agent states.
Usage
Basic
The state property binds directly to the Agent lifecycle: idle on standby, working while executing tool calls, running during step dispatch, thinking during inference, and success when complete; with interactive and random enabled, it also plays autonomous idle behaviors, click reactions, and Shiny Devil mutations.
States
Miko features 38 customized pixel animations derived from authentic cat behaviors, playful professions, and whimsical fantasy (loaf posture, paw tapping, fast running gallop, coffee sipping, guitar playing, DJ mixing, ninja stealth, magic casting, master chef, fishing time, astronaut space walk, heart beaming, dumbbell workout, umbrella stroll, yawning sleepyhead, shiny devil, airplane ears, stretching, face washing, curious tilting, scratching, purring, fish snack, swaying dance, penlight cheering, handheld gaming, cyberpunk hacking, confetti celebration, cardboard box peek, etc.).
Best Practices
- Lifecycle Mapping: Align precisely with Agent events:
session_starttoidle,UserPromptSubmittothinking,tool_calltorunningorworking,Stoptosuccess,PermissionRequesttoalert, and idle timeouts tosleepingorsleepy. - Interaction & Devil Mutation: Pass
interactiveto enable tactile click feedback; autonomous exploration or clicking has a chance to mutate into the "Shiny Devil" form (horns, bat wings, arrow tail, golden glints), which can also be forced via thedemonprop. - Pure Vector Performance: No external sprite sheets or canvas animation loops required. All elements are clean SVG
<rect>blocks accelerated by CSS@keyframeswith sub-kilobyte footprint. - Proportions: Use standard
'xs' | 'sm' | 'md' | 'lg'sizes or numerical values. The 36:20 aspect ratio with flat horizontal base docks neatly in status bars, CoreBox corners, or conversation headers. - Monochrome & Accessibility: Defaults to a lighter companion violet (
#9726D9, a softer step from the Tuff brand violet#810DC6), shifts to deep obsidian crimson (#4C0519) in devil form, and is customizable via thecolorprop. Includes built-inrole="img"and accessible ARIA announcements.
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
state | MikoState | 'idle' | Current action state, supporting 38 states in total. |
size | MikoSize | 'md' | Size preset ('xs' 22px, 'sm' 30px, 'md' 50px, 'lg' 66px) or custom dimension. |
color | string | '#9726D9' | Main body color. |
labels | Partial<MikoLabels> | {} | Localized accessibility label overrides. |
ariaLabel | string | Generated | Overrides the default accessible announcement. |
interactive | boolean | false | Enables click feedback, hover glow, and click reactions. |
random | boolean | false | Enables autonomous random cycling through casual idle behaviors. |
randomInterval | number | 5000 | Interval in milliseconds between random state changes. |
demon | boolean | false | Forces the "Shiny Devil" mutated form. |
mutationChance | number | 0.06 | Probability (0 ~ 1) of mutating into the Shiny Devil form during interaction or random state cycles. |
Events
| Name | Type | Description |
|---|---|---|
click | [event: MouseEvent] | Triggered when clicking on the companion. |
stateChange | [state: MikoState] | Triggered when the active state changes (via random timer or reaction). |
update:state | [state: MikoState] | Enables v-model:state two-way state binding. |
mutate | [isDemon: boolean] | Triggered when mutating into or reverting from the Shiny Devil form. |
Overview
- Renders an ultra-sharp pixel SVG with
role="img"andshape-rendering="crispEdges". - 38 supported states:
idle,working,running,demon,coffee,guitar,sleepy,ninja,fishing,magic,umbrella,heart,workout,dj,chef,space,thinking,success,alert,error,sleeping,juggling,sweeping,reading,dizzy,peeking,stretching,bathing,curious,scratching,purring,eating,dancing,cheering,gaming,hacking,celebrating, andbox. - Driven entirely by native CSS
@keyframeswithout external GIF or PNG assets.
Technologies
- Source located at
packages/tuffex/packages/components/src/miko/. - Fixed 1.8:1 aspect ratio with internal
viewBox="0 0 36 20".