Posecode

Kinematic motion as text.
Mermaid gave LLMs a way to draw diagrams.
Posecode gives them a way to show movement.

A human-readable spatial DSL for describing, validating, and rendering
exercises, physiotherapy movements, posture, dance, and human motion.

Live Playground · Movement Library · Language Specification · Examples · MCP Server

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

_{One .posecode document — shoulders: abduct 160, hips: abduct 30, repeat 12 — rendered live in the browser.}

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.

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

▶ Watch the 28-second builder demo
_{Plain text in. Smooth, programmable 3D motion out.}

pelvis: hinge — deadlift

knees: flex 95 — squat

shoulders: abduct 90 — lateral raise

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

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

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.

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

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

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.

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

1. Write .posecode	2. Render the movement
posecode exercise "Body-weight squat" rig humanoid pose start = standing step "Descend" 1.6s settle:   hips: flex 80   knees: flex 95   ankles: dorsiflex 14   ground-lock: feet   cue "Sit the hips back" step "Drive up" 1.2s drive:   hips: flex 0   knees: flex 0   ankles: dorsiflex 0   ground-lock: feet repeat 8

┌─────────────────────────┐
│ 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 │
                             └──────────────────────┘

Preview, edit, and share movements without installing anything:

https://posecode.org/play

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

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.

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.

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>.

Posecode uses multiple layers of checking.

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.

The engine measures the actual resulting skeleton after:

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

Movement examples can define expected properties.

For example, a deadlift may require:

• sufficient torso pitch,
• limited forward knee travel,
• stable foot contact,
• and symmetrical hip movement.

The Build Week critic interprets the movement and deterministic measurements together.

It explains biomechanical problems in natural language and proposes specific revisions.

Posecode is built with:

• TypeScript
• JavaScript
• Node.js
• Three.js
• WebGL
• Vite
• CodeMirror
• Model Context Protocol
• Zod
• Vitest
• Playwright
• esbuild
• GPT-5.6
• Codex

Posecode currently focuses on:

• single-person human movement,
• fitness,
• physiotherapy demonstrations,
• posture,
• dance,
• education,
• rehabilitation visualization,
• forward kinematics,
• ground locking,
• ROM-constrained inverse kinematics,
• hip hinging,
• standing, seated, and lying poses,
• basic scene props,
• and browser-based rendering.

The following are outside the current scope:

• two-person or partner motion,
• comprehensive collision detection and rigid-body dynamics,
• detailed object physics,
• advanced equipment simulation,
• multi-joint finger animation,
• FBX or GLB animation export,
• and medical diagnosis.

Posecode is an engineering and visualization project.

Its range-of-motion values and biomechanical checks are based on general reference data and simplified models.

They are not:

• medical advice,
• diagnosis,
• injury-prevention guarantees,
• physiotherapy prescriptions,
• or a substitute for a qualified professional.

Generated movements should be reviewed by a qualified expert before being used for healthcare, rehabilitation, or safety-critical applications.

Posecode could support:

• game and character animation,
• fitness instruction,
• exercise visualization,
• anatomy education,
• physiotherapy demonstrations,
• posture training,
• dance and choreography prototyping,
• sports technique analysis,
• robotics research,
• synthetic motion-data generation,
• and embodied AI systems.

• Complete GPT-5.6 Physics Critic
• Complete biomechanical fidelity scorecard
• Add generate → critique → revise agent loop
• Add critique tools to the MCP server
• Add playground prompt interface
• Expand adversarial movement evaluations
• Improve temporal interpolation
• Add more skeletal models
• Support visual Posecode editing
• Add standard animation export
• Explore multi-person movement

See ROADMAP.md for the longer-term plan.

posecode/
├── packages/
│   ├── posecode-language/
│   ├── posecode-parser/
│   ├── posecode-render/
│   ├── posecode-share/
│   ├── posecode-mcp/
│   └── posecode-eval/
├── playground/
├── editors/
├── spec/
├── docs/
├── scripts/
└── README.md

Run all unit tests:

npm test

Run coverage:

npm run coverage

Run type checking:

npm run typecheck

Run biomechanical evaluations:

npm run eval

The CI workflow verifies that the project:

• builds successfully,
• passes type checking,
• passes unit tests,
• and satisfies configured movement invariants.

Posecode follows the design study:

Kinematic Motion Definition Protocols for Large Language Models

The project explores whether semantic, text-based movement programs can provide a controllable and inspectable alternative to black-box motion generation.

The specification covers:

• DSL design,
• biomechanical constraints,
• client-side rendering,
• agent integration,
• and possible product applications.

See:

• spec/SPEC.md
• spec/llm-authoring.md
• docs/market-research.md

The hosted playground currently uses an Adobe Mixamo character and one showcase animation under the applicable Adobe terms. These binary assets are not covered by Posecode's software licenses. See third-party notices.

The renderer also includes a zero-asset procedural figure and accepts compatible humanoid GLB characters through characterUrl.

Posecode is open source with a clear standard and product boundary:

Organizations that need to use an AGPL component in a closed-source product may contact hello@posecode.org about a separate commercial agreement.

Earlier grants are unchanged. MIT revisions remain MIT, and the 0.2.2 npm packages remain Apache-2.0. See LICENSING.md, COMMERCIAL-LICENSE.md, and TRADEMARK.md.

Feedback and contributions are welcome.

• Email: hello@posecode.org
• Issues: GitHub Issues

OpenAI Build Week 2026: Posecode existed before the hackathon. During Build Week, the project is being meaningfully extended with a GPT-5.6-powered biomechanical Physics Critic and an end-to-end Codex-built agent workflow. The sections below clearly distinguish previous work from new hackathon work.

Before OpenAI Build Week, Posecode already included:

• the core .posecode domain-specific language,
• a parser and intermediate motion representation,
• basic range-of-motion validation,
• a Three.js/WebGL renderer,
• forward kinematics,
• basic inverse-kinematics and ground-lock behavior,
• a browser playground,
• example movement files,
• shareable Posecode links,
• and an MCP server foundation.

This original version was developed primarily with Claude as an AI-assisted engineering tool.

That prior work provides the foundation for the project, but it is not presented as the new hackathon contribution.

During the July 13–21 Build Week submission period, Posecode is being meaningfully extended with:

1. GPT-5.6 Physics Critic
2. Biomechanical fidelity scorecard
3. Natural-language-to-motion agent workflow
4. Interactive generation and critique experience
5. Codex-built tests, tooling, and renderer improvements

The new workflow allows a user to describe a movement in ordinary language, generate structured Posecode, validate it deterministically, and receive a detailed GPT-5.6 critique explaining biomechanical or spatial problems.

• GPT-5.6 movement generation
• GPT-5.6 Physics Critic
• Structured fidelity-score response
• Critique panel in the playground
• Generate → validate → critique → revise loop
• MCP tools for critique and revision
• Automated tests for the new workflow
• Demo-ready example movements
• Build Week commit links added below
• Codex session ID added below

A movement can be syntactically valid while still being awkward, unstable, unsafe, or physically implausible.

For example:

step "Twist" 1s:
  hips: rotate 0
  spine: rotate 90
  feet: lock

A parser may understand this program, but the movement may create an unrealistic torso rotation while the hips and feet remain locked.

The new Physics Critic sends the structured movement, parser warnings, joint states, and geometric measurements to GPT-5.6.

GPT-5.6 then returns a structured critique such as:

{
  "score": 42,
  "summary": "The movement is syntactically valid but biomechanically implausible.",
  "issues": [
    {
      "severity": "high",
      "category": "spinal_rotation",
      "message": "Torso rotation is excessive while the pelvis and feet remain fixed.",
      "suggestion": "Reduce spinal rotation or allow the pelvis and feet to rotate."
    }
  ]
}

The critic does not replace deterministic safety checks. It adds a semantic reasoning layer on top of the real Posecode parser and kinematic engine.

The Build Week scorecard combines deterministic measurements with GPT-5.6 analysis.

It can evaluate:

• joint range-of-motion compliance,
• balance and support,
• movement continuity,
• left-right consistency,
• torso and pelvis coordination,
• foot-ground contact,
• reachability,
• abrupt transitions,
• and overall biomechanical plausibility.

Conceptually, the total score is:

$$ F = \sum_{i=1}^{n} w_i s_i $$

where:

• (s_i) is the score for one fidelity dimension,
• (w_i) is that dimension's weight,
• and (\sum_{i=1}^{n} w_i = 1).

The purpose of the score is not to provide medical advice. It gives developers and AI agents a transparent signal for comparing, debugging, and improving generated movement.

GPT-5.6 is used as a spatial and biomechanical reasoning layer.

It supports two Build Week workflows.

A user can enter:

Perform a controlled forward lunge, keep the torso upright, pause at the bottom, and return to standing.

GPT-5.6 translates that request into a structured .posecode program with:

• participating joints,
• semantic joint actions,
• approximate angles,
• movement phases,
• timings,
• cues,
• and grounding constraints.

The output is not sent directly to the renderer.

It must pass through the deterministic Posecode pipeline:

Natural-language request
        ↓
GPT-5.6 generation
        ↓
Posecode parser
        ↓
ROM validation
        ↓
Forward and inverse kinematics
        ↓
Geometric fidelity checks
        ↓
WebGL renderer

After parsing and evaluating the movement, GPT-5.6 receives structured information about:

• the original user request,
• generated Posecode,
• parser warnings,
• clamped joint values,
• movement phases,
• support points,
• kinematic measurements,
• and failed fidelity invariants.

GPT-5.6 uses this information to explain:

• what is wrong,
• why it matters,
• how severe it is,
• and how the movement could be corrected.

This creates an iterative agent loop:

Generate → Parse → Validate → Critique → Revise → Render

Codex is the primary engineering tool used for the new Build Week extension.

During the hackathon period, Codex is used to help:

• inspect and understand the existing monorepo,
• design the Physics Critic architecture,
• implement GPT-5.6 API integration,
• define structured generation and critique schemas,
• build new MCP tools,
• create the fidelity-score pipeline,
• add playground UI components,
• implement movement revision workflows,
• debug coordinate and skeletal transformation issues,
• write unit and integration tests,
• create evaluation fixtures,
• improve error handling,
• and document the new system.

Codex accelerates implementation, but the project remains human-directed.

The following decisions are reviewed and selected manually:

• DSL semantics,
• system architecture,
• prompt design,
• scoring dimensions,
• biomechanical constraints,
• validation policy,
• user experience,
• and acceptance or rejection of generated code.

The Build Week workflow follows this process:

1. Define a specific product or engineering problem.
2. Ask Codex to inspect the relevant implementation.
3. Request one or more possible approaches.
4. Review the trade-offs and choose the architecture.
5. Use Codex to implement the selected approach.
6. Run type checking, tests, and fidelity evaluations.
7. Inspect failures manually.
8. Refine the implementation with additional Codex sessions.
9. Review the final changes before committing.

Codex /feedback session ID: TODO

The repository history will distinguish pre-existing functionality from work completed during the hackathon.

Add the relevant dated commits here:

• TODO — GPT-5.6 integration
• TODO — Physics Critic implementation
• TODO — Fidelity scorecard
• TODO — Playground generation interface
• TODO — MCP agent workflow
• TODO — Tests and documentation

LLMs already have languages for software, data, and interfaces.
Posecode gives them a language for movement.