Introduction

Pick a character. Connect it to your agent’s state. Give the quiet moments in your product a little personality.

Overview#

Agent Mascots is a free, open-source (MIT) React package of animated characters for AI agents and the interfaces around them. Each character responds to a small set of states, so you map your agent's status to a state and the mascot does the rest: spring-eased motion, eyes that follow the cursor, sparkles when a task finishes. There are no runtime dependencies beyond React 19.

Installation#

One package, one import path per pack. Your bundler only ships the packs you import. Requires React 19. Components include "use client", so they work in Next.js App Router pages as-is.

Terminal

npm i agentmascots

Usage#

Render the component and map your agent's status to a state.

agent-status.tsx

import { SpaceMascot } from "agentmascots/space";

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

export function AgentStatus({ 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} />;
}

Pack data (character lists, state names, spaceStill() SVG strings) can be imported in server components. Only the mascot components themselves are client components.

Packs#

Import	Component	Style
agentmascots/space	SpaceMascot	13 flat space shapes
agentmascots/fuzzy	FuzzyMascot	Fuzz Club: 3D fur plush in CSS 3D, no WebGL
agentmascots/distinguished	DistinguishedMascot	Plush cast, felt / plastic / plain
agentmascots/sorcerers	SorcererMascot	Flat vector cast

Want to compose your own characters? agentmascots/plush exports the plush renderer, drawing helpers and every plush pack's data, and agentmascots/motion exports the shared spring engine.

States#

State	Motion	Use when
`idle`	Gentle float with blinking eyes.	Waiting for user input
`listening`	Leans in, eyes wide.	Mic open, voice input
`thinking`	Sway, eyes glance up, thought dots.	Reasoning, planning, long tasks
`working`	Focused, busy motion.	Running a tool, reading, editing
`speaking`	Mouth and body pulse.	Streaming a reply
`celebrating`	Happy hop with sparkles.	Task complete, tests passed
`sleeping`	Slow breathing, closed eyes, floating z’s.	Idle timeout, rate limited

Props#

Prop	Type	Description
character	pack-specific union	Which character to render. Typed per pack, so your editor autocompletes the cast.
state	"idle" \| "listening" \| "thinking" \| "working" \| "speaking" \| "celebrating" \| "sleeping"	Current state. Transitions are spring-eased.
size	number \| string	Rendered size in px or any CSS length. Default 96.
color	string	Override the character's body color.
track	boolean	Eyes and lean follow the cursor. Default true.
speed	number	Animation speed multiplier. Default 1.
title	string	Accessible label. Pass an empty string to mark as decorative.
className / style	string / CSSProperties	Standard passthrough.

Plush packs also take texture ("felt" | "plastic" | "plain") and particleColor. SpaceMascot also takes eyeColor and thoughtDots. Motion pauses off-screen and in background tabs, and respects prefers-reduced-motion.

Customizing#

Open any character in the Studio to change body color, eyes, eye color, expression, accessory, blush, animation speed, and default size. Playing is free; exporting the customized component is coming soon. Until then you can tweak any pack in code with the color, speed and size props.

Availability#

The packs are free and open source. Studio export and the AI generator are next.

Free packs on npmAvailable
Mascot Studio (preview)Available
Studio exportPlanned
AI generatorPlanned
Agent-readable catalogPlanned

Explore the characters