# agent-pet
> A tiny animated companion-pet widget for any web app. Self-hostable, no backend, ~10 KB gzip. Vanilla DOM — no React, no Preact, no framework runtime.
[](https://www.npmjs.com/package/agent-pet)
[](LICENSE)
[](https://bundlephobia.com/package/agent-pet)
[](https://agent-pet.pages.dev)
[](https://agent-pet.pages.dev)
Drop a single `
```
The script resolves the spritesheet URL automatically and applies the standard 8×9 Codex atlas layout. Try `homelander`, `guga`, `furina`, `patamon`, `clippy`, `totoro` — the slug after `/pets/` in any codex-pets.net URL works as the id.
### Try it in a sandbox
Open a blank [CodePen](https://codepen.io/pen/), [JSFiddle](https://jsfiddle.net/), or [JS Bin](https://jsbin.com/), and paste this into the HTML pane:
```html
```
Save / Run — the pet appears bottom-right and reacts to the buttons. Or save it as `try.html` locally, double-click to open in a browser; no server needed.
For a hosted, more complete demo (state buttons, pet catalog with thumbnails, hide-to-dock, opt-in chat input) see [agent-pet.pages.dev](https://agent-pet.pages.dev) — right-click → "View Source" to copy the working HTML.
## Features
- **Zero backend** — pure static JS. The widget makes no network calls beyond the one you point it at.
- **Self-contained** — no peer dependencies, no framework runtime. Pure vanilla DOM; ~10 KB gzip total.
- **Shadow DOM isolation** — won't conflict with host page styles.
- **Draggable + persistent** — position and pet selection persist via `localStorage`.
- **9 distinct animations** — drives all rows of the Codex atlas spec (idle, thinking, building, delegating, leaving, greeting, waiting, success, error).
- **Speech bubbles** — `AgentPet.say(text, { link })` for inline status with optional click-through.
- **Versioned URLs** — pin to `/v0.8/` for stability; immutable + 1-year cache.
- **SRI-pinnable** — SHA-384 hashes published per release.
- **Versatile mounting** — auto-mount or programmatic; mount into any element via `target`.
---
## Integration paths
### 1. CDN script tag (recommended for most sites)
**Minimal — emoji glyph, zero config:**
```html
```
**Animated pet from codex-pets.net by id:**
```html
```
**Your own Codex-format spritesheet:**
```html
```
We don't bake a default spritesheet into the bundle — they're 80–150 KB each and belong to their creators. Roll your own following the [Codex Atlas Format](#codex-atlas-format), or browse [codex-pets.net](https://codex-pets.net/) and [j20.nz/hatchery/](https://j20.nz/hatchery/).
### 2. Self-hosted
The bundle is plain static JS — download it, serve it from your own host:
```bash
curl -O https://agent-pet.pages.dev/v0.8/agent-pet-widget.iife.js
```
Serve via your CDN, nginx, S3, GitHub Pages — anywhere. Then:
```html
```
The bundle makes no calls back to any origin. The only outgoing request from `data-codex-pet` is the spritesheet `` to codex-pets.net's storage; for zero external requests, vendor the spritesheet locally:
```bash
# In a checkout of this repo
pnpm vendor-pet homelander
# → public/sprites/homelander.webp
# Then in your HTML
```
Vendor multiple at once: `pnpm vendor-pet homelander guga totoro`.
### 3. npm package (offline / SDK use)
Install once from npm. Works fully offline — no CDN, no manual file copying.
```bash
pnpm add agent-pet
```
The package exposes three subpath entries; pick the one that fits your app:
| Subpath | Use case | React peer dep? |
|---|---|---|
| `agent-pet` | React apps — import the React components | **Yes** (React 18+) |
| `agent-pet/widget` | Svelte / Vue / Solid / Angular / vanilla — self-contained ES module factory, vanilla DOM, no framework runtime | No |
| `agent-pet/iife` | Direct path to the IIFE bundle if you want a script-tag dist | No |
#### React apps — `agent-pet`
```tsx
import { PetProvider, PetOverlay } from 'agent-pet';
import 'agent-pet/css';
function App({ appState }) {
return (
);
}
```
#### Any other framework — `agent-pet/widget`
A self-contained ES module that exports `createAgentPetAPI()` plus `createRegistry()` for multi-pet apps. Pure vanilla DOM (~11 KB gzip), no framework runtime. Your bundler (Vite/webpack/Rollup) tree-shakes and inlines it like any other dep — no manual copy step.
```ts
import { createAgentPetAPI } from 'agent-pet/widget';
const pet = createAgentPetAPI();
pet.mount({ name: 'Rex', imageUrl: '...', useCodexAtlas: true });
pet.setState('thinking');
```
##### Framework-specific snippets
**Svelte 5:**
```svelte
```
**Vue 3:**
```ts
import { onMounted, onUnmounted, ref, watch } from 'vue';
import { createAgentPetAPI, type AgentPetAPI } from 'agent-pet/widget';
const pet = ref();
const working = ref(false);
onMounted(() => { pet.value = createAgentPetAPI(); pet.value.mount({ name: 'Buddy' }); });
onUnmounted(() => pet.value?.unmount());
watch(working, v => pet.value?.setState(v ? 'thinking' : 'idle'));
```
**Solid:**
```tsx
import { createSignal, createEffect, onCleanup } from 'solid-js';
import { createAgentPetAPI } from 'agent-pet/widget';
const pet = createAgentPetAPI();
pet.mount({ name: 'Buddy' });
onCleanup(() => pet.unmount());
const [working, setWorking] = createSignal(false);
createEffect(() => pet.setState(working() ? 'thinking' : 'idle'));
```
**Angular:**
```ts
import { Component, OnDestroy, effect, signal } from '@angular/core';
import { createAgentPetAPI, type AgentPetAPI } from 'agent-pet/widget';
@Component({ /* ... */ })
export class App implements OnDestroy {
pet: AgentPetAPI = createAgentPetAPI();
working = signal(false);
constructor() {
this.pet.mount({ name: 'Buddy' });
effect(() => this.pet.setState(this.working() ? 'thinking' : 'idle'));
}
ngOnDestroy() { this.pet.unmount(); }
}
```
The `agent-pet/widget` entry is one ES module — your bundler treats it like any other npm dep. No script tags, no `window.AgentPet` global, no manual file copying. SSR-safe (the API gates DOM access internally).
---
## Script-tag attributes
| Attribute | Type | Default | Purpose |
|---|---|---|---|
| `data-codex-pet` | string | – | Pet id at codex-pets.net (auto-resolves URL + atlas) |
| `data-name` | string | `"Buddy"` | Display name in speech bubble |
| `data-glyph` | string (emoji) | `"🐶"` | Emoji shown when no `imageUrl` set |
| `data-accent` | CSS color | `"#7eb8da"` | Theme color (border, links) |
| `data-image-url` | URL | – | Spritesheet URL |
| `data-use-codex-atlas` | flag | – | Apply standard 8×9 Codex atlas layout |
| `data-storage-key` | string | `"agent-pet:config"` | localStorage key (multi-instance) |
| `data-auto-mount` | `"false"` | auto-mount | Set `"false"` to mount programmatically |
| `data-observe` | keywords | – | Opt into page event observers (`forms`, `nav`, `all`) |
Bare attributes like `data-use-codex-atlas` (no value) read as truthy.
## API
```ts
AgentPet.setState(state) // persistent mood — pet stays in this state
AgentPet.play(action, opts?) // one-shot action — auto-reverts to setState
AgentPet.say(text, opts?) // open speech bubble; opts: { ttl?, link? }
AgentPet.configure(opts) // change name/glyph/accent/imageUrl/atlas
AgentPet.observe(opts) // wire DOM events (form submit, nav, etc.) to states
AgentPet.mount(opts?) // mount into DOM (auto-called unless data-auto-mount="false")
AgentPet.unmount() // remove from DOM
AgentPet.on('stateChange', handler)
AgentPet.off('stateChange', handler)
AgentPet.mounted // boolean — currently in the DOM?
// Multi-pet registry (window.AgentPet only)
AgentPet.create(id, opts?) // create + mount a named pet
AgentPet.get(id) / has(id) / list() // lookup
AgentPet.remove(id) // unmount + forget
```
### `setState` vs `play`
Use **`setState()`** for the pet's persistent mood — it holds until you change it:
```ts
AgentPet.setState('thinking'); // stays in 'thinking' until next setState
```
Use **`play()`** for transient feedback — the pet plays the action once, then reverts to whatever `setState` was last:
```ts
AgentPet.setState('idle');
AgentPet.play('greeting'); // wave once, then back to idle
AgentPet.play('success', { loops: 2 }); // celebrate twice
AgentPet.play('jumping', { durationMs: 800 }); // explicit duration
```
Calling `setState()` while a `play()` is in flight cancels the auto-revert — explicit state takes precedence.
### States
Each state maps to a distinct row of the Codex atlas:
| State | Atlas row | Suggested use |
|---|---|---|
| `idle` | idle | Default ambient state |
| `thinking` | review | Awaiting LLM / processing input |
| `building` | running | Long-running task in progress |
| `delegating` | running-right | Forwarding to subsystem |
| `leaving` | running-left | Wrapping up / going away |
| `greeting` | waving | Hello / welcome / first appearance |
| `waiting` | waiting | Awaiting user input |
| `success` | jumping | Operation completed successfully |
| `error` | failed | Operation failed |
The atlas row name also works directly as a `setState()` argument, e.g. `setState('running-right')` is equivalent to `setState('delegating')`. Useful when you're driving from raw Codex vocabulary.
Aliases: `hello`/`welcome` → `greeting`; `away` → `leaving`; `done`/`completed` → `success`.
### `configure()` options
```ts
AgentPet.configure({
name: 'Rex',
glyph: '🦖', // emoji shown if no imageUrl
accent: '#e74c3c', // theme color (border, links)
imageUrl: '/sprites/rex.webp', // spritesheet URL
useCodexAtlas: true, // applies the standard 8×9 Codex layout
storageKey: 'my-pet', // localStorage key (for multi-instance pages)
});
```
`configure()` patches localStorage and dispatches an `agent-pet:config-changed` window event so multiple consumers stay in sync.
### `mount()` options
```ts
AgentPet.mount({
target: document.getElementById('sidebar'), // defaults to document.body
...configureOptions
});
```
Calling `mount()` twice is idempotent — it unmounts the previous instance first.
### Page event observers (opt-in)
Wire the widget to common page events so it reacts automatically — no JS glue:
```js
AgentPet.observe({
formSubmit: 'thinking', // any