Mesh Avatar Studio

日本語 · 简体中文

Turn a single illustration into an animated 2D mesh avatar: it blinks, talks, turns its head, breathes and sways its hair. A coding agent prepares the avatar from your image; you fine-tune it in a local editor with a live preview.

See it move on the landing page. To move it with your own face and voice without installing anything, open the Player in Chrome or Edge.

Try the sample

Requires Node.js 22.17+ and Git.

npx create-mesh-avatar-studio
cd mesh-avatar-studio
npm run dev

The first command downloads the repository, installs its packages and checks the tools Studio needs. If you cloned the repository yourself, run npm install, then npm run doctor for the same check. Only Node.js is needed for the editor and the Live page. uv and Python rebuild layers, and Playwright Chromium renders the motion review when an agent creates an avatar; the check warns about each one that is missing.

Open the URL printed in the terminal (for example http://127.0.0.1:5173/). The editor opens the bundled sample, Miko in a qipao. Pick a part on the left, drag its dots on the image and watch the preview on the right. The sample is read-only; when you change it, choose Copy and keep editing to continue in your own copy.

Using Windows

Use git clone to download the repository when possible. If you use a ZIP, open its Properties in File Explorer and select Unblock, if shown, before extracting it.

Create projects/ yourself under your Windows account before asking an agent to work in it (npx create-mesh-avatar-studio creates it for you). Folders created by another account or an agent running in a sandbox can have permissions that prevent the editor from reading them. If a project cannot be read, use the folder's Properties → Security settings to grant your account access to the whole project, including its files and subfolders through permission inheritance.

How it works

Making an avatar from your own illustration takes four steps. Steps 1 and 4 are done by a coding agent (Claude Code or Codex) working in this repository; steps 2 and 3 happen in the editor.

1. Ask your agent to create the avatar

Open Claude Code or Codex in this repository folder and give it your illustration:

Create an avatar from this image following docs/agent-guide.md: /path/to/your-image.png

The agent follows the agent guide: it checks how accurately it reads coordinates, places the rig on zoomed grids, cuts the image into layers and reviews the avatar in fixed poses. The project is saved in projects/<name>/, which is never committed. Best results come from a front-facing, head-and-shoulders PNG with a transparent background. When no project is open, the editor shows this request ready to copy.

Recommended setups:

Agent	Model
Claude Code	Claude Opus 5.5
Codex	GPT-6.1 Sol

One command with Codex

With the Codex CLI installed and signed in, one command creates the project, has Codex follow the agent guide without questions and opens the editor on the result:

npm run create -- /path/to/your-image.png

Codex also draws closed eyes, mouth shapes and expressions with OpenAI image generation, and first closes an open mouth in the illustration so the avatar rests with it closed. This sends the image and masks to OpenAI, so the command asks first; add --yes to agree in advance, or --no-variants to keep everything on your machine. It usually takes tens of minutes. Codex writes its notes to projects/<name>/HANDOVER.md. It runs with --approve-for-me, so its requests to run tools outside its sandbox, such as Chromium for the pose review, are reviewed automatically instead of by you. npm run create -- --help lists the options.

Without an illustration, --random has Codex draw a new anime-style girl first and builds the avatar from her. Her looks are chosen at random; --prompt describes what you want instead, and --seed repeats the same random choices. The drawing is kept in work/random/, and the choices in projects/<name>/work/character.json.

npm run create -- --random
npm run create -- --random --prompt "silver short hair, school uniform"

2. Open the project and check it

Start the editor (npm run dev), choose Open project and pick your project from the list. The pencil next to a project renames it, together with its folder under projects/. If the avatar has overlay layers such as glasses (built/overlays/), the preview lists them under Overlays so you can switch them on and off. In the preview, use Pose test to turn and tilt the head and close the eyes. In Lip sync, choose a mouth style and try it with kana text. Open Fine-tune to adjust movement, size and closing, or preview a local audio file.

3. Fix what looks wrong by dragging

Select a part on the left. Its dots are highlighted on the image; drag them to fix the placement. The preview follows your changes immediately. Some values also decide how the image is cut into layers: eye and hand outlines, and the head, hair and bun areas used for the hair mask. After changing those, a banner appears; choose Save and rebuild layers there. It takes a few seconds.

Zoom with a pinch or Ctrl/Cmd+scroll, pan with two fingers or by dragging empty space, and use Fit selected part to jump to the current part.

This is the beginning of the README. Read the rest at the original. Read the full README ↗