Iki
息 (breath) · 生き (life) · 粋 (chic)
Iki is a free, MIT-licensed 2D puppet animation engine for the web — an
alternative to Live2D and Inochi2D whose characters an
AI agent can make. Ask for one, and the bundled
Claude Code / Codex plugin has an image model draw its parts, then rigs them
into a character that blinks, looks around, talks, turns and nods, with hair
that sways. What you get is an open .iki file — plain JSON you own — that the
WebGL runtime plays in any browser, and that a host (such as
Charivo) drives from lip-sync, gaze and
expressions.
Status: early, but real. The runtime renders parameter-driven color quads,
atlas-sampled texture parts, warp-mesh and grid deformation, stencil clipping
masks, and spring/chain physics. The editor authors parts, deformers, and
physics rigs; the generator rigs a character from role-named PNG/PSD layers,
including through an MCP server that AI agents can drive.
Make a character with AI
Install the plugin in Claude Code:
/plugin marketplace add zeikar/iki
/plugin install iki@iki
Or in Codex:
codex plugin marketplace add zeikar/iki
codex plugin add iki@iki
Start a new Codex session to load it. The same skills and MCP server work in
both hosts; see the plugin installation guide for a local
checkout and prerequisites.
Then ask for a character — "make me an iki character: short copper bob, green
eyes, school uniform". The plugin:
- Draws each part on its own with an image model — face, eyes, irises,
brows, mouth, nose, front and back hair, torso.
- Composes and checks them on one canvas (
compose_layers_from_parts,
measure_layers), catching the geometry that would break in motion.
- Rigs them (
auto_rig_from_layers): eyelid-fold blink, gaze, lip-sync,
head turn, nod and tilt, brows, breathing and hair physics, written to a
.iki model.
The character at the top of this page was made this way. The plugin needs an
image generator — see its prerequisites. Already have
art? Hand role-named PNG layers to the auto-rigger through the
@ikijs/mcp server, or import a layered PSD in the editor.
Try it
No install — both demos run in the browser:
- Playground — drag the sliders
that a host would drive, on a hand-authored model or one of the three
regression-corpus characters — the hero and two full bodies.
- Editor — author parts, deformers,
and physics rigs, import a layered PSD, and export a validated
.iki.
Why
- Characters an AI agent can build. Part images in, a rigged model that
blinks, talks, turns and nods out — through the Claude Code / Codex plugin or any MCP
client. That is the part Iki is really exploring.
- Free for commercial use. MIT: no publication license, no revenue tiers —
ship whatever you build with it.
- Open format. The
.iki model is a plain, documented JSON schema you own —
which is what makes generating a model tractable in the first place.
- Web-native. WebGL runtime, TypeScript, no native toolchain.
- Host-agnostic. The engine knows nothing about Charivo or any host; it
just plays
.iki models. Charivo consumes it through a thin render-iki
adapter, the same way it consumes the Live2D SDK today.
How Iki compares
Live2D Cubism is the industry standard, and it is far more mature than Iki in
every dimension that matters to an artist — editor, tooling, ecosystem, and the
quality ceiling of what you can rig with it. Inochi2D
is the established open-source project in this space. Iki is not trying to
replace either. It exists because three things it wanted never lined up in one
place: a permissive license, a plain-text format, and a rig an agent can build.
| Live2D Cubism | Inochi2D | Iki |
|---|
| License | Proprietary SDK license; a publication license is required to distribute, with exemptions for individuals and small businesses (terms) | BSD-2-Clause | MIT — free for commercial use |
| Editor | Cubism Editor (paid PRO tier, free tier) | Inochi Creator (open source) | Headless editor core + example app (early) |
| Model format | .moc3, compiled and proprietary | Open | Plain JSON with a documented schema and a validator |
| Runtime | Native SDKs, including a Web SDK | Native (D) | TypeScript + WebGL2, npm install |
| An AI agent can build it | — | — | Yes: a Claude Code / Codex plugin that draws and rigs a character, over an MCP server (compose_layers_from_parts, measure_layers, auto_rig_from_layers, measure_turn_reference, render_poses) |
| Maturity | Industry standard | Established | Early (0.x, schema still settling) |
If you need production-grade 2D rigging today, use Cubism. If you want an open
web format you can script against, that is what this is.
Packages
| Package | What it is |
|---|
@ikijs/format | The .iki model schema, types, loader, and validator |
@ikijs/engine | WebGL2 runtime that plays a .iki model |
@ikijs/editor | Headless editing core (no UI): EditorDocument, edit commands, undo/redo, atlas layout/UV helpers, auto-rigger (depends only on @ikijs/format) |
@ikijs/mcp | stdio MCP server exposing .iki read/validate plus compose_layers_from_parts, measure_layers, auto_rig_from_layers, measure_turn_reference and render_poses to AI agents |
examples/playground (live) | Slider-driven demo of the three regression-corpus characters (the hero and two full bodies) and a hand-authored model |
examples/editor (live) | Private React+Zustand app — load/import art, numeric part + deformer + physics editing, pivot gizmo, live IkiPlayer preview, validated .iki export |
plugin/ | Claude Code / Codex plugin — shared character-generation skills, two agent roles, and the MCP server, wired up in one install |
Install
npm install @ikijs/engine @ikijs/format
@ikijs/editor is for building authoring tools; @ikijs/mcp runs as a
server (npx -y @ikijs/mcp) rather than being imported.
Quick start (this repo)
pnpm install
pnpm build
pnpm playground # open the Vite URL and drag the sliders
The .iki model
A model is a flat list of parts composited back-to-front, plus parameters wired
to those parts through linear bindings:
import { StandardParameter, type IkiModel } from "@ikijs/format";
const model: IkiModel = {
version: 1,
name: "Hello",
canvas: { width: 1000, height: 1000 },
parameters: [{ id: StandardParameter.MouthOpen, min: 0, max: 1, default: 0 }],
parts: [
{
id: "mouth",
color: [0.78, 0.32, 0.36, 1], // solid fill, or tint multiplier when a texture is present
width: 150,
height: 34,
order: 0,
transform: { x: 0, y: -150 },
bindings: [
{
parameter: StandardParameter.MouthOpen,
channel: "scaleY",
from: 0,
to: 3,
},
],
},
],
};
Stick to the StandardParameter ids (ParamMouthOpenY, ParamAngleX, …) so
any host can drive any model without per-model wiring. Left/Right in those
ids name the character's side, so the character's left eye is the part at
positive x (the viewer's right).
A model can also declare expressions and motion clips, each with a description.
A host plays an expression by its id and a clip by its group and index.
Stability: IKI_FORMAT_VERSION identifies the .iki contract, and from
1.0 on, any breaking schema change bumps it. Until then the v1 schema is still
settling: a 0.x release may tighten validation and reject a model an earlier
one accepted (canvas extents must now be > 0, for instance). Such changes
are called out in the changelog. The TypeScript surface can likewise shift
between 0.x minors.
FAQ
Can I use this commercially? Yes — MIT, for everything in this repo. Models
you make are yours.
Can it load Live2D models? No. .moc3 is a proprietary compiled format;
Iki has its own open schema and no importer for it.
Is it production ready? Not yet — the packages are published from 0.1.0 and
the v1 schema is still settling. See Stability above for what that means for
a model you save today.
Do I need the editor to use it? No. @ikijs/engine + @ikijs/format are
enough to play a model. The editor packages are for building authoring tools.
How do I make a model? Ask for one with the
Claude Code / Codex plugin, which draws the parts and rigs
them. With art of your own, feed role-named PNG layers to the auto-rigger in
@ikijs/editor / @ikijs/mcp, which
wires up blink, gaze, lip-sync, head-turn and brows for you. Or hand-write the
JSON — it is small, see above.
Roadmap
ROADMAP.md tracks what has landed and what is deferred.
License
MIT © Zeikar
