posecode

Why Posecode?

Ask an LLM to explain physical movement and it usually returns unstructured prose or a static diagram.

For example:

Bend your knees, move your hips backward, and keep your chest upright.

A human may understand that instruction, but a renderer cannot reliably determine:

• which joints should move,
• by how many degrees,
• in which coordinate frame,
• over what duration,
• in what sequence,
• or within which physical limits.

Large language models can often reason about the components of human movement, but they lack a standardized syntax for expressing that reasoning in a renderable and testable form.

Posecode provides that missing representation.

See Posecode in 28 seconds

From an LLM prompt to editable Posecode, validated 3D rendering, MCP tools, and a one-script web embed.

Movement examples

Why Not Diffusion Text-to-Motion?

Neural text-to-motion systems can generate impressive movement, but they introduce problems for lightweight, programmable applications.

Resource intensive

Many systems require large models and GPU-backed inference, making real-time consumer deployment expensive.

Difficult to control

They usually produce coordinate trajectories rather than editable semantic instructions.

It is difficult to request a precise change such as:

Reduce knee flexion by 10 degrees during the second phase.

Hard to validate

Black-box trajectories do not naturally expose readable joint rules, phase definitions, or range-of-motion limits.

Hard to debug

When a movement looks wrong, developers may not know which semantic instruction caused the problem.

The Posecode Approach

Posecode uses a lightweight, text-driven pipeline.

• Readable: movements are stored as small .posecode documents.
• Structured: joints, actions, angles, timings, and constraints are explicit.
• Editable: developers and models can modify individual movement properties.
• Fast: parsing and rendering happen client-side.
• Deterministic: the same Posecode input produces the same validated representation.
• Inspectable: parser warnings and fidelity checks explain problems.
• Agent-friendly: the MCP server exposes generation, validation, critique, and sharing tools.
• Safety-aware: authored and IK-generated angles are constrained by configured range-of-motion limits.

The Idea in 30 Seconds

A .posecode file describes movement as timed phases with targeted joint actions.

Architecture

┌─────────────────────────┐
│ Natural-language prompt │
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│ GPT-5.6 authoring layer │
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│     .posecode source    │
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│ Parser and ROM checking │
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│ Kinematics and IK layer │
└────────────┬────────────┘
             │
             ├─────────────────────┐
             ▼                     ▼
┌─────────────────────────┐  ┌──────────────────────┐
│ Three.js/WebGL renderer │  │ Fidelity measurements│
└─────────────────────────┘  └──────────┬───────────┘
                                        │
                                        ▼
                             ┌──────────────────────┐
                             │ GPT-5.6 Physics     │
                             │ Critic and revision │
                             └──────────────────────┘

Installation and Usage

Live Playground

Preview, edit, and share movements without installing anything:

https://posecode.org/play

Local Development

Requirements:

• Node.js 20 or newer
• npm

Clone the repository:

git clone https://github.com/posecode-dev/posecode.git
cd posecode

Install dependencies:

npm install

Start the playground:

npm run dev

Run tests:

npm test

Run type checking:

npm run typecheck

Run fidelity evaluations:

npm run eval

Build the playground:

npm run build

MCP Server

Posecode includes a Model Context Protocol server for AI agents.

Run it with:

npx -y posecode-mcp@latest

Example MCP client configuration:

{
  "mcpServers": {
    "posecode": {
      "command": "npx",
      "args": ["-y", "posecode-mcp@latest"]
    }
  }
}

The MCP server exposes:

• validate_posecode
• render_posecode

See packages/posecode-mcp for the complete configuration and tool documentation.

Web Component Embed

Embed a Posecode player on a page:

<script src="https://unpkg.com/posecode-embed/dist/posecode-embed.js"></script>

<posecode-player src="/movements/squat.posecode"></posecode-player>

The player can be used in:

• documentation,
• educational content,
• exercise guides,
• blog posts,
• and movement libraries.

Core Libraries

Install the parser:

npm install posecode-parser

Install the renderer:

npm install posecode-render

Example:

import { parse } from "posecode-parser";
import { createViewer } from "posecode-render";

const source = `
posecode exercise "Lateral raise"
  rig humanoid
  pose start = standing

  step "Raise" 1.4s settle:
    shoulders: abduct 90
`;

const { ir, errors, warnings } = parse(source);

if (!ir || errors.length > 0) {
  console.error(errors);
} else {
  console.warn(warnings);
  const viewer = createViewer(document.querySelector("#viewer"));
  viewer.load(ir);
  viewer.play();
}

The #viewer element is an HTML <canvas>.

How Posecode Stays Honest

Posecode uses multiple layers of checking.

1. Range-of-motion clamping

Joint angles are constrained before rendering.

For example:

knees: flex 200

is clamped to the configured knee-flexion limit and produces a warning instead of rendering an impossible angle.

2. Kinematic evaluation

The engine measures the actual resulting skeleton after:

• parsing,
• forward kinematics,
• inverse kinematics,
• and ground-lock corrections.

3. Geometric fidelity invariants

Movement examples can define expected properties.

For example, a deadlift may r