How to Create a Mesh Avatar From One Illustration

Mesh Avatar Studio splits avatar creation between a coding agent (Claude Code or Codex) that prepares the rig, and you, who fine-tune it in the local editor with a live preview. Four steps, three checks — expect roughly half an hour for your first avatar.

Start with the right image

The single biggest quality factor is the input illustration:

• Best: a front-facing, head-and-shoulders PNG with a transparent background.
• Works with warnings: strong three-quarter view, hands or objects covering the face, hair heavily overlapping the face.
• Cannot be represented yet: hats and objects held in front of the face move rigidly with the head.
• No illustration at all? Generate a character first with --random.

The 4-step workflow

1. Ask your agent to create the avatar

   Open Claude Code or Codex in the repository folder and give it the image:

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

   The agent creates a project under projects/<name>/, surveys the image on zoomed grids, drafts the rig part by part (head ellipse, eye openings, mouth line, hair strands, body), builds the animation layers and renders a set of fixed review poses — turning, blinking, mouth open, expressions — checking its own output at each stage.

   With the Codex CLI signed in, one command does everything without questions:

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

2. Open the project and check it

   npm run dev, then Open project and pick your project. Under the preview: Pose test turns and tilts the head and closes the eyes; Lip sync holds kana vowels or plays kana text at 4–12 morae per second; Fine-tune adjusts movement, size and closing. If your avatar has overlays such as glasses, the preview lists them so you can toggle each.

3. Fix what looks wrong by dragging

   Select a part on the left — its control dots highlight on the image. Drag them until placement is right; the preview follows immediately. Eye and hand outlines, and the head/hair/bun areas used for the hair mask, also decide how the image is cut into layers: after changing those, click Save and rebuild layers in the banner (takes a few seconds).

4. Get drawn eyes and mouths (recommended)

   Mesh deformation alone moves eyes and mouth, but drawn closed eyes and vowel mouths make blinking and talking look dramatically more natural. In Drawn variants, check Eyes, Mouth or both, copy the prepared message, and paste it into Codex (which draws them with built-in image generation and imports them automatically) or Claude Code (which prepares masks and prompts for any image generator). Optional Expressions add sad/surprised eyes and angry/sad closed mouths.

What the agent checks behind the scenes

A good agent run is not a single prompt — the official agent guide mandates verification loops: a vision calibration test before starting (models that cannot read pixel coordinates fail early), overlay checks after drafting the rig, layer-mask checks after the build, and a full motion review in fixed poses (rest, half/closed eyes, mouth open, ±30° turns, tilts, expressions, hair sway). Frames that fail loop back: adjust, rebuild, render again — capped at three rounds before it reports what still fails. See how the agent works for the internals.

Recommended setups

Reading pixel coordinates from images needs strong vision. If your agent runs a different model, the official guide says it should tell you the result may fall short.

Privacy during creation

Your image stays on your machine inside projects/ (never committed). The one exception: generating drawn variants with Codex image generation sends the image and a mask to OpenAI — the command asks before doing it, and --no-variants keeps everything local.