DominikScholz/open-bot-avatar

What it is

Open Bot Avatar defines an agent avatar as a single SVG path inside a 0 0 100 100 box plus eye placement, then renders it as a 3D-looking SVG avatar. The volume is inferred from the outline as stacked cross-sections and drawn in a CSS 3D scene, or projected into one flat SVG for stills contract, rendering notes.

It ships as the dependency-free open-bot-avatar package with a browser mountAvatar helper and DOM-free SVG/string rendering functions. A browser-based editor lets you pick, color, import and generate avatars, and a gallery/ directory holds community definitions gallery. It suits developers adding a small animated character to an agent chat UI.

Quick start

Install the package with pnpm:

pnpm add open-bot-avatar

Mount an example avatar into a square element:

import { getExample } from "open-bot-avatar";
import { mountAvatar } from "open-bot-avatar/dom";

const avatar = mountAvatar(document.querySelector("#bot")!, {
  definition: getExample("mug")!,
  color: "#ff6a1a",
  followPointer: true,
});

avatar.update({ mood: "happy" });
avatar.destroy();

The definition option is required; mood accepts "idle", "thinking" or "happy", and pointer following is off by default mount options. For a static image without a DOM, call renderAvatarSvg after validateAvatar accepts your JSON SVG rendering.

There is no React package; the README provides a component that wraps mountAvatar in useEffect for React users React pattern.

Authoring avatars

An avatar definition is v1 JSON with id, name, a body.path and eye coordinates (x, y, spacing, scale) definition example. Check hand-written definitions with validateAvatar, which returns { ok: true, value } or { ok: false, errors }.

To generate one, open the editor, describe the avatar under Generate, send the bundled system prompt to a chat model or agent, and paste the returned JSON into Import making an avatar. The prompt and skill live in skills/generate-avatar/ prompt, skill.

Constraints

Building the repository requires Node 22.18+ and pnpm; the test suite uses Vitest development. The renderer targets the browser for mountAvatar and is DOM-free for the SVG/frame functions. Moods and gaze are limited to the options above; there is no React package, so framework bindings are copied from the README. The project is MIT licensed license.

HotRepo's take

HotRepo recorded the project on the TypeScript new-project list on 2026-11-03, with 102 stars and 13 forks gained inside a growth window of roughly 23 hours from its 2026-11-02 creation. That is a strong opening day for a small, single-purpose rendering library, but the available data covers only one snapshot, so it does not yet show sustained adoption or how the editor and gallery are used over time.