posecode

Why Posecode?

Animation clips and generated trajectories can show movement, but they often hide the semantic decisions that produced it.

Posecode keeps those decisions in readable source. A human can write the document, an animation tool can emit it, or an LLM can draft it. Parsing, validation, editing, and rendering do not require an AI model.

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.

Humans, tools, and language models all need a shared syntax for expressing movement in a renderable and testable form.

Posecode provides that missing representation.

See Posecode in 28 seconds

From readable movement source to validated 3D rendering, MCP tools, and a one-script web embed.

Movement examples

Related MCP server: pyBittle MCP Server

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.

OpenAI Build Week 2026: Posecode existed before the hackathon. During Build Week, the project was extended using Codex — running on GPT-5.6 — as the primary engineering tool for a real batch of shipped work: motion/grounding quality, language contract diagnostics, licensing restructuring, release automation, and product-facing pages. The sections below distinguish previous work from Build Week work using actual commit history, not a roadmap.

OpenAI Build Week Extension

What existed before Build Week

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

What was added during Build Week

Every item below is a merged, dated pull request built with Codex (GPT-5.6) — see Build Week Evidence for direct links.

1. Motion and grounding overhaul — ROM-constrained reach IK, semantic palm/fist/sole/knee/pelvis contact surfaces, multi-contact refinement, stable support handoffs, and XBot-aware grounding (#76).

2. Language contract and diagnostics — Posecode language/IR v0.3 custom start-pose blocks with ROM-checked overrides, live and clip-wide grounding/self-collision diagnostics, and an accessible metric floor guide (#92).

3. Licensing restructure — split the monorepo into an Apache-2.0 standard layer (spec, parser, share, language, LSP, VS Code) and an AGPL-3.0 product layer (render, embed, MCP, eval, playground), with a commercial-license path (#84).

4. Release automation — Changesets-driven npm publishing via GitHub OIDC, MCP Registry publishing, and CI validation of package versions, entry points, and tarball contents (#66).

5. Third-party integration readiness — Posecode 0.2 timing vocabulary (drive/settle/flow/snap), a parser validation CLI, and embed compatibility metadata (#62).

6. Ground-lock correctness — parser-owned validation for per-side foot/hand/elbow ground locks and back-contact support for supine movements, replacing silent acceptance of invalid contacts (#61, #64).

7. LLM-first landing page and product page — redesigned the landing page around a prompt → Posecode → live 3D story, and added a /for-products page documenting the web component, parser, renderer, and MCP server for integrators (#82, #74).

8. Mobile and search fixes — mobile toolbar/viewer layout, natural hand orientation, and Google Search indexing corrections (#78, #65).

Build Week feature status

• Motion/grounding quality overhaul shipped (#76)

• Language contract + diagnostics shipped (#92)

• Licensing restructure shipped (#84)

• Release automation shipped (#66)

• Ground-lock correctness shipped (#61, #64)

• Landing/product pages shipped (#82, #74)

How GPT-5.6 Is Used

During Build Week, Codex sessions ran on GPT-5.6 (GPT-5.6 Terra), which is the model that powers Codex for this event. GPT-5.6 is the reasoning engine behind every Build Week change listed above: reading the existing monorepo, proposing the ROM-constrained IK and contact-surface design in #76, designing the language/IR v0.3 diagnostics in #92, and drafting the licensing boundary in #84.

A GPT-5.6-powered natural-language-to-Posecode generation feature (describe a movement in plain English, get a validated .posecode document back) is a natural next step given the existing posecode_authoring_guide MCP tool, but it is not yet built — it is not claimed as shipped functionality here.

How Codex Is Used

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

During the hackathon period, Codex was used to:

• inspect and understand the existing monorepo before each change,

• design and implement the ROM-constrained reach IK and contact-surface system (#76),

• design and implement the language/IR v0.3 diagnostics and floor guide (#92),

• restructure package licensing across the monorepo (#84),

• build the Changesets/OIDC npm and MCP Registry release pipeline (#66),

• fix ground-lock validation and silent-acceptance bugs (#61, #64),

• redesign the landing page and add the product integration page (#82, #74),

• write unit, integration, and evaluation-harness tests for each change,

• and fix mobile UI and search-indexing regressions.

Codex accelerates implementation, but the project remains human-directed. The following decisions were reviewed and selected manually: DSL semantics, system architecture, licensing boundaries, biomechanical constraints, validation policy, user experience, and acceptance or rejection of generated code.

Codex development workflow

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 biomechanical evaluations (npm run eval).

7. Inspect failures manually.

8. Refine the implementation with additional Codex sessions.

9. Review the final changes before committing.

Build Week Evidence

All Build Week work is public, dated, and directly linked below — no placeholders.

Build Week pull requests

Build Week comparison

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

Editor support

A VS Code extension provides syntax highlighting, ROM diagnostics, and completion for .posecode files — see editors/vscode. Until it is published, you can get basic highlighting immediately by associating .posecode files with Markdown:

"files.associations": {
  "*.posecode": "markdown"
}

See the editor guide for VS Code, Cursor, Sublime Text, and Neovim instructions.

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

Exporting motion (BVH)

posecode-render can bake a movement into a Biovision Hierarchy (.bvh) file for import into Blender and other animation tools. In the playground, use the Download BVH button; programmatically:

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

const { ir } = parse(source);
const bvh = exportBVH(ir!, { fps: 30 }); // string, ready to write to disk

Options: fps (default 30), scale (default 1 = metres; pass 100 for centimetres), includeFingers (default false), and proportions for a calibrated rig.

• Coordinate system: right-handed, Y-up, figure faces +Z in the rest pose (identical to the renderer and Three.js). Enable Blender's "Y up" BVH import option.

• Units: metres by default.

• Rotation channels: Zrotation Xrotation Yrotation (Euler order ZXY).

• Scope: this exports the authored joint motion plus root travel/turn. It does not yet re-run the renderer's contact/IK solve, so IK-dependent movements (e.g. reach: hand_left floor) export the authored pose rather than the solved one. See issue #63.

Exporting motion (glTF / GLB)

For web animation pipelines, posecode-render can export the rig and a baked animation clip as a glTF/GLB asset. In the playground, use Download glTF; programmatically:

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

const { ir } = parse(source);
const glb = await exportGLTF(ir!);            // GLB ArrayBuffer (default)
const gltf = await exportGLTF(ir!, { binary: false }); // glTF JSON object

The result loads with Three.js GLTFLoader, and the clip plays on the included rig:

const gltf = await new GLTFLoader().loadAsync(url);
const mixer = new THREE.AnimationMixer(gltf.scene);
mixer.clipAction(gltf.animations[0]).play();

• Joint nodes are named by Posecode bone id; the animated root is posecode_root.

• Limitations: exports the procedural mannequin rig, not a humanoid/Mixamo skeleton, so there is no retargeting onto external rigs yet, and (as with BVH) it bakes the authored motion, not the contact/IK-solved motion. See issue #90.

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 require:

• sufficient torso pitch,

• limited forward knee travel,

• stable foot contact,

• and symmetrical hip movement.

4. GPT-5.6 Physics Critic

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

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

Packages

Technology

Posecode is built with:

• TypeScript

• JavaScript

• Node.js

• Three.js

• WebGL

• Vite

• CodeMirror

• Model Context Protocol

• Zod

• Vitest

• Playwright

• esbuild

• GPT-5.6

• Codex

Scope

Version 0.1

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.

Deferred

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.

Limitations and Safety

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.

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

Repository Structure

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

Testing

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.

Background

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

Character assets

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.

Multiple character appearances (avatar avatar1 / avatar2 / avatar3)

All built-in characters use the same rig humanoid skeleton topology. An optional avatar directive selects appearance without redefining that rig (see spec/SPEC.md). Pass characterUrls (selector → GLB URL map) to createViewer instead of a single characterUrl; ir.avatar is used when present and ir.rig supplies the default selector otherwise. Switching documents, or editing the avatar directive, swaps the visible character. A selector with no entry in the map (or any load failure) falls back to the procedural figure. See packages/posecode-render/README.md for the option, and packages/posecode-embed's character attribute docs for the same behavior in the web component (absent by default; set an explicit URL to pin one character regardless of avatar).

Bringing your own character rig

Pass a characterUrl (fixed) or characterUrls (per-selector, see above) pointing to a skinned GLB to replace the bundled Mixamo character. Requirements:

• Format: glTF binary (.glb) containing a THREE.SkinnedMesh.

• Rest pose: T-pose.

• Bone naming: Mixamo convention. Names may carry the mixamorig: / mixamorigN: namespace prefix — it's stripped automatically. These bones must all be present:

  • Torso/head: Hips, Spine, Spine2, Neck, Head

  • Arms: LeftArm, LeftForeArm, LeftHand, RightArm, RightForeArm, RightHand

  • Legs: LeftUpLeg, LeftLeg, LeftFoot, RightUpLeg, RightLeg, RightFoot

  • Fingers (first phalanx only): LeftHandThumb1, LeftHandIndex1, LeftHandMiddle1, LeftHandRing1, LeftHandPinky1, and the RightHand*1 equivalents

If any required bone is missing, loading the character rejects and the viewer silently falls back to the zero-asset procedural figure — a bad rig never breaks the scene.

The simplest way to source a compatible rig is mixamo.com: export a character in T-pose with "skin with skeleton," then convert FBX → GLB (e.g. with Blender's glTF exporter or FBX2glTF). Bone names come out Mixamo-compatible automatically.

The bone map and retarget/calibration logic live in packages/posecode-render/src/character.ts. Supporting a different naming convention (e.g. VRM humanoid bones) means editing the BONE_MAP table and plainName() prefix-stripping there.

Licensing

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, commercial licensing, and trademark policy.

Feedback and Support

Feedback and contributions are welcome.

• Email: hello@posecode.org

• Issues: GitHub Issues