# agentmascots

> Free, open-source (MIT) React package of animated, cursor-tracking mascots for AI agents. Map an agent's status to a `state` (idle, listening, thinking, working, speaking, celebrating, sleeping) and the mascot animates with spring physics. No dependencies beyond React 19. Gallium (https://trygallium.com) is the website; the npm package is `agentmascots`.

## Install

- `npm i agentmascots` (requires React 19). Works in Next.js App Router: components include "use client".
- Import one pack per file, e.g. `import { SpaceMascot } from "agentmascots/space"`. Bundlers ship only the packs you import.
- Pack data (character lists, state names) is safe to import in server components. Only the mascot components are client components.

## Packs

- [Space Collection](https://trygallium.com/packs/space): `agentmascots/space` exports `SpaceMascot` (flat space shapes). Characters: luna, nebula, quasar, pulsar, cosmo, meteor, corona, comet, orbit, vega, rover, flare, atlas.
- [Fuzz Club](https://trygallium.com/packs/fuzzy): `agentmascots/fuzzy` exports `FuzzyMascot` (3D fur plush in CSS 3D (no WebGL)). Characters: clover, flower, ghost, square, puff, drop.
- [Distinguished Individuals](https://trygallium.com/packs/distinguished): `agentmascots/distinguished` exports `DistinguishedMascot` (flat vector). Characters: bleu, butter, rose, plum, mint.
- [Sorcerers in Therapy](https://trygallium.com/packs/sorcerers): `agentmascots/sorcerers` exports `SorcererMascot` (flat vector). Characters: infinite, sukuna, toji.

## 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} />;
}
```

## Docs

- [Full reference for LLMs](https://trygallium.com/llms-full.txt): every prop, state, character and common mistake
- [Human docs](https://trygallium.com/docs)
- [npm](https://www.npmjs.com/package/agentmascots)
- [Source](https://github.com/fzsheik/thing)