# agentmascots: full reference

Gallium (https://trygallium.com) is the website; the npm package is `agentmascots` (MIT, https://www.npmjs.com/package/agentmascots, source https://github.com/fzsheik/thing).

## What it is

Animated mascot components for AI agent UIs (chat avatars, status indicators, loaders, empty states). Each mascot reacts to a small set of states. Eyes follow the cursor (`track`), motion is spring-eased, and it pauses off-screen and in background tabs and respects `prefers-reduced-motion`. SVG plus requestAnimationFrame, no canvas or WebGL, no dependencies besides React 19.

## Install

```sh
npm i agentmascots
```

Requires React 19. Components ship with "use client", so they can be used from Next.js App Router server components without adding the directive yourself.

## Import paths

- `agentmascots/space`: `SpaceMascot`, Space Collection (flat space shapes)
- `agentmascots/fuzzy`: `FuzzyMascot`, Fuzz Club (3D fur plush in CSS 3D (no WebGL))
- `agentmascots/distinguished`: `DistinguishedMascot`, Distinguished Individuals (flat vector)
- `agentmascots/sorcerers`: `SorcererMascot`, Sorcerers in Therapy (flat vector)
- `agentmascots/plush`: PlushMascot renderer, drawing helpers and all plush pack data, for building custom characters
- `agentmascots/motion`: the shared spring engine and geometry helpers

Each pack entry also exports its data, e.g. `spaceCharacters`, `spaceStates`, `fuzzyCharacters`, and the component's prop types.

## Usage

```tsx
import { SpaceMascot } from "agentmascots/space";

type AgentStatus = "idle" | "planning" | "running" | "replying" | "done" | "away";

export function AgentAvatar({ status }: { status: AgentStatus }) {
  const state = {
    idle: "idle", planning: "thinking", running: "working",
    replying: "speaking", done: "celebrating", away: "sleeping",
  } as const;
  return <SpaceMascot character="luna" state={state[status]} size={96} />;
}
```

## States

Every pack supports the same seven states:

- `idle`: waiting for input
- `listening`: mic open, voice input
- `thinking`: reasoning, planning, long tasks
- `working`: running a tool, reading, editing
- `speaking`: streaming a reply
- `celebrating`: task complete, tests passed
- `sleeping`: idle timeout, rate limited

Suggested mapping from agent status to state: waiting for user -> idle, microphone open -> listening, model reasoning or planning -> thinking, running tools -> working, streaming tokens -> speaking, success -> celebrating, idle timeout or rate limit -> sleeping.

## Props (all packs)

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| character | union of that pack's ids | first character | typed per pack; an unknown id is a type error |
| state | "idle" \| "listening" \| "thinking" \| "working" \| "speaking" \| "celebrating" \| "sleeping" | "idle" | spring-eased transitions |
| size | number or CSS length | 96 | |
| color | string | character color | overrides body color |
| track | boolean | true | eyes and lean follow the cursor |
| speed | number | 1 | animation speed multiplier |
| title | string | none | accessible label; empty string marks it decorative |
| className, style | | | passthrough |

Extra props: `agentmascots/space`: eyeColor, particleColor, thoughtDots; `agentmascots/distinguished`: particleColor; `agentmascots/sorcerers`: particleColor.

## Characters per pack

### Space Collection (`agentmascots/space`, `SpaceMascot`)

- `luna`: Luna. The original moon. Calm, round, always listening.
- `nebula`: Nebula. A soft cloud of half-formed ideas.
- `quasar`: Quasar. Square-jawed, bright, and very on-task.
- `pulsar`: Pulsar. Four points of pure signal.
- `cosmo`: Cosmo. A lucky clover that drifted into orbit.
- `meteor`: Meteor. Leaning in, always mid-sprint.
- `corona`: Corona. Petals of plasma around a gentle core.
- `comet`: Comet. A droplet with somewhere to be.
- `orbit`: Orbit. Long, low, and easygoing.
- `vega`: Vega. The sharpest star in the system.
- `rover`: Rover. A tiny lander with a pointed hat.
- `flare`: Flare. Bursts with energy, settles with style.
- `atlas`: Atlas. Steady, six-sided, carries the whole crew.

### Fuzz Club (`agentmascots/fuzzy`, `FuzzyMascot`)

- `clover`: Clover. Four leaves of pure luck, zero leaves of chill.
- `flower`: Flower. Blooms when you ship. Wilts on merge conflicts.
- `ghost`: Ghost. Haunts your inbox. Politely.
- `square`: Square. Fits in every grid. Refuses to be a button.
- `puff`: Puff. A small cloud with big opinions.
- `drop`: Drop. One drip of motivation, refilled hourly.

### Distinguished Individuals (`agentmascots/distinguished`, `DistinguishedMascot`)

- `bleu`: Monsieur Bleu. Has opinions about your font pairing.
- `butter`: Professor Butter. Tenured. Unbothered. Reading your PR.
- `rose`: Madame Rose. Too cool to blink. Deploys on Fridays.
- `plum`: Baron Plum. Old money. New frameworks.
- `mint`: Lord Mint. Dresses for the launch he wants.

### Sorcerers in Therapy (`agentmascots/sorcerers`, `SorcererMascot`)

- `infinite`: Mr. Infinite. Problem: has never once been inconvenienced.
- `sukuna`: Finger Food. Problem: twenty fingers, zero chill.
- `toji`: Zero Energy. Problem: no cursed energy. Plenty of gambling debt.

## Common mistakes

- Passing a character id from another pack. `character` is typed per pack: Space ids do not work in `agentmascots/fuzzy`.
- Importing from the package root. There is no root export; always import from a pack path such as `agentmascots/space`.
- Using React 18. The package requires React 19.
- Copying package source into the app. Install from npm and customize with props.
- Expecting the Studio to export code yet. Export is not available; use the npm package.

## Links

- Website: https://trygallium.com
- Docs: https://trygallium.com/docs
- Short index: https://trygallium.com/llms.txt
- npm: https://www.npmjs.com/package/agentmascots
- Source: https://github.com/fzsheik/thing