Mesh Avatar Studio rigs a 2D illustration, then lets you fix it by dragging

An illustration in, a rigged avatar out

Mesh Avatar Studio turns a single illustration into an animated 2D mesh avatar that blinks, talks, turns its head, breathes and sways its hair. The stated split is between two tools: a coding agent prepares the avatar from your image, and you fine-tune it in a local editor with a live preview.

That division is the design. Claude Code or Codex does the mechanical part, which is placing handles on eyes, mouth and hair across a layered image, and the human does the part that requires taste, which is deciding whether the eyes are in the right place. The README is explicit that best results come from a front-facing, head-and-shoulders PNG with a transparent background, which is a real constraint on what you can feed it.

The project is written in TypeScript and published under the MIT licence. It is a pnpm style npm workspace with packages in a packages directory, the root package.json lists the workspaces as packages/*, and the visible packages are mesh-avatar, mesh-avatar-element and create-mesh-avatar-studio, the last of which is the scaffolding command you run to start a project.

The release history is young and quick. mesh-avatar 0.2.0 was published on 2026-10-14 and 0.2.1 on 2026-10-17, and create-mesh-avatar-studio 0.1.1 on the same day. The last push to the default branch was on 2026-10-19.

The site publishes a landing page and a Player page, and the Player is the quickest way to see what the project does.

Four steps, two of them in the editor

The README lays out the whole workflow, and it is worth reading as a description of the architecture because it shows where the boundaries sit.

Step one is the agent. You open Claude Code or Codex in the repository folder and give it your illustration with the request shown in the agent guide:

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

The agent then follows docs/agent-guide.md, which tells it to check how accurately it reads coordinates, place the rig on zoomed grids, cut the image into layers, and review the avatar in fixed poses. The project is saved under projects/<name>/, a directory that is never committed. When no project is open, the editor shows that same request ready to copy.

Step two is opening the project in the editor and checking it, where Pose test turns and tilts the head and closes the eyes, and Lip sync checks the vowel mouth shapes.

Step three is fixing what looks wrong by dragging. You select a part on the left, its dots are highlighted on the image, and dragging them updates the preview immediately.

Step four is getting drawn eyes and mouths. Without drawings, the eyes and mouth move by mesh deformation alone, and the README is direct that drawn closed eyes and vowel mouths make blinking and talking look much more natural.

The recommended setups are Claude Code with Claude Opus 5.5, and Codex with GPT-6.1 Sol.

Trying the sample on Node.js 22.17

The quick start is three commands, and the requirements are stated plainly: 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 the studio needs. If you cloned the repository yourself, you run npm install and then the same check by hand:

npm install
npm run doctor

The doctor script is the piece worth remembering. Beyond Node.js, the studio needs uv and Python, which rebuild layers, and Playwright Chromium, which renders the motion review when an agent creates an avatar. The check warns about each one that is missing, which means you find out about a missing Python toolchain before an agent run fails halfway.

The development server is Vite, bound to 127.0.0.1, and the root package.json shows the script as vite --host 127.0.0.1. You 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. The sample is read-only, and when you change it you choose Copy and keep editing to continue in your own copy, which is how the project folder gets created.

Windows has one documented wrinkle. Use git clone to download the repository when possible, and if you use a ZIP, open its Properties in File Explorer and select Unblock before extracting. You also create the projects folder yourself under your Windows account before asking an agent to work in it, since folders created by another account or by an agent in a sandbox can carry permissions that stop the editor from reading them.

Dragging handles, and why layers sometimes rebuild

The editing model is direct manipulation with a consequence that catches people out.

You pick a part on the left, its dots light up on the image, and the preview on the right follows your drag immediately. Zoom works with a pinch or Ctrl or Cmd scroll, you pan with two fingers or by dragging empty space, and Fit selected part jumps to the part you are working on.

The catch is that some of the values you drag are not only geometry. Eye and hand outlines, and the head, hair and bun areas, also decide how the image is cut into layers. Change one of those and a banner appears offering Save and rebuild layers, which takes a few seconds. The rebuild is done by uv and Python, which is why those are in the requirements and why the doctor script checks for them.

The layering is what makes the avatar work. A mesh can deform a flat image, but the eyes and the mouth need to be separate pieces that can move independently and that can be replaced by drawn variants, and that separation comes from the cut.

The rest of the toolchain follows the same shape. The scripts in package.json include validate-rig, validate-avatar, pack-avatar and render-poses, each a small Node tool run with the type stripping flag, plus vitest for unit tests, Playwright for the e2e suite and eslint across the sources, tests and site.

Drawn variants, and the gap between the two agents

Step four is where the project stops being automatic, and the difference between the two supported agents matters.

In Drawn variants you check Eyes, Mouth or both, copy the message the editor produces and paste it into Codex opened in the repository folder. Codex draws them with its built-in image generation and imports them, and the editor reloads them automatically. The README says plainly that Claude Code cannot generate images: its message prepares the masks and prompts for you to hand to an image generator.

So the two recommended setups are not interchangeable. With Codex the loop is closed, since the same tool that rigs the avatar also draws the expressions. With Claude Code you end up moving prompts to a separate image generator and bringing the result back, which is more steps but still supported.

Expressions is the optional extra. It adds drawn sad and surprised eyes and closed angry and sad mouths, and the avatar switches to them for those expressions and for emotion tags while still blinking and speaking. The README notes that avatars without them look the same as before, which is a fair description of a feature that adds expressiveness rather than changing the core animation.

The projects directory is where all of this lands, and it is never committed, which means the rig and the layers are local artefacts of a working session rather than versioned source.

One .mavatar file, and a 128 MiB ceiling

Sharing an avatar is done through a single file. Export .mavatar downloads one archive containing the saved rig, the built layers, the drawn expressions and the avatar metadata, and the file format is described in docs/format.md.

One option is on by default. Include source image is enabled, so the recipient can edit the avatar in Studio. Turning it off gives a smaller file, and the README is explicit about what that costs: an imported avatar without the source image can play but cannot be edited or rebuilt. Omitting the source does not remove the built images, so the animation still works.

Import is done from Open project, or by dropping the file there, and Studio creates a new folder under projects/, using a new name if one already exists. Two constraints are worth noting. Import requires the development server to be running, since it goes through npm run dev, and it accepts archives up to 128 MiB.

There is also an ordering rule that matters if you have unsaved edits. Use Save and export in that case, and if you changed an outline, the layers need a rebuild first. A read-only view exports the original files, which is the behaviour of the bundled sample.

For developers, the format is a documented contract rather than an implementation detail, since the pack-avatar and validate-avatar scripts exist to produce and check it.

Live page, OBS, and camera data that stays local

The Live page is where the avatar becomes a streaming avatar, and the privacy story is stated in one sentence that is worth quoting for what it claims: camera video and microphone audio stay on your machine, and only numeric avatar motion values reach the stream view.

The flow is straightforward. You open the project in the editor, choose Live, start the camera, face forward with relaxed eyes and a closed mouth, and choose Calibrate. Mirroring, sensitivity and smoothing are adjustable, and microphone lip sync can be enabled. Face detection runs through the mediapipe tasks-vision package, which the root package.json pins at 0.10.21.

For output you choose a background and copy the OBS URL, or open the stream view in a new tab to check it first. You keep the Live page open and add the URL as an OBS Browser Source, for example at 1080 by 1080. The transparent background works directly in OBS, and for other capture software you choose green and apply a chroma key. The stream view shows idle motion when the Live page stops sending updates, so the broadcast does not go static.

Optional Lighting adds shading that follows a light you drag over the avatar. It is off by default, and the OBS URL carries the lighting settings, so the stream view and the broadcast agree.

Both pages run on the local development server. The hosted Player on the project site is the alternative for anyone who wants to drive an avatar with their own face and voice without installing anything, opening it in Chrome or Edge.

Editorial conclusion

Adopt Mesh Avatar Studio if you already have a front-facing, head-and-shoulders illustration with a transparent background, and you want a VTuber style avatar with blinking, lip sync and head movement without rigging it by hand. Do not adopt it if you need drawn expressions from Claude Code, since the README states that Claude Code cannot generate images and only prepares masks and prompts, or if your avatars must be shared without your source illustration, since an export without the source image cannot be edited or rebuilt. Before you start, run npm run doctor to see which of Node.js, uv with Python and Playwright Chromium you are missing, and expect to rebuild the layers after changing any outline.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. shinshin86/mesh-avatar-studio on GitHub