minWM: an open-source framework that turns a T2V model into a real-time world model
A Minimal and Elegant Framework & Tutorial for Real-Time Interactive World Models
At a glance
- What is it?
- The shengshu-ai team open-sourced the whole path from a bidirectional text-to-video backbone to a 4-step action-conditioned world model, with runnable scripts, checkpoints, and Claude skills for the parts that usually eat months.
- Who is it for?
- minWM is worth attention less for any single model and more for what it open-sources around the model: a complete data-to-inference path, staged distillation with inspectable checkpoints, two backbone integrations that demonstrate how to add a third, and Claude skills that turn one team’s debugging scars into onboarding notes.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 10 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What minWM actually is
minWM, published by shengshu-ai under the Apache-2.0 license, describes itself as the first full-stack open-source world model framework. The wording matters: it is a framework and tutorial rather than a single pretrained model. You start from a bidirectional text-to-video foundation model and end with an action-conditioned video world model that runs in 4 steps per frame. Everything between those two points is open: the data construction recipes, the training scripts, the distillation stages, and the inference stack.
The project shipped in May 2026, released its technical report on arXiv (2605.30263) at the end of that month, and pushed a reworked version with optimized infrastructure on 2026-09-05. The old layout survives at the v0.1-legacy tag with a migration guide, so earlier experiments do not break.
The full pipeline from data to inference
Most public world-model work releases checkpoints and leaves the plumbing undocumented. minWM goes the other way: the data, training, and inference stages are all open, and every stage exposes input and output checkpoints so you can stop, swap, or fork anywhere along the line.
On the data side, the framework walks through constructing training-ready datasets paired with camera poses, then processing them into latents. Training covers FSDP with sequence parallelism, single-node and multi-node setups, and the full distillation pipeline. Inference covers 4-step DMD for HY Action2V, HY TI2V, and Wan Action2V, multi-GPU sequence parallelism, and camera-trajectory control driven either by pose strings such as "a*4,w*8,s*7" or by JSON files. That last detail is what makes it a world model rather than a video generator: the camera path is an input you control.
The distillation ladder
The most technically interesting part is the staged path from a slow bidirectional diffusion model to a fast autoregressive student. Phase 1 is plain bidirectional SFT. Phase 2 then climbs a four-step ladder: teacher forcing AR diffusion first, then Causal ODE as proposed in the Causal Forcing paper (arXiv 2602.02214), then Causal CD from Causal Forcing++ (arXiv 2605.15141), and finally asymmetric DMD with self rollout.
The output of that last stage is the headline number: a 4-step real-time model. Each rung has a defined input and output checkpoint, so if your student model collapses at stage 2b you can inspect exactly what the teacher forcing stage produced instead of guessing across an opaque end-to-end run. The onboarding skill (more on that below) treats these stages as its core teaching content.
Two backbones, one abstraction
minWM currently supports two backbone lines, and the README lists them side by side. Wan 2.1 uses cross-attention plus a DiT architecture with 1.3 billion parameters. HunyuanVideo 1.5 uses MMDiT with 8 billion parameters. Both run all four training stages and both infer with 4-step DMD.
The structural claim is the useful one: both lines share the same trainer, loss, and dataset abstractions, so adding a third backbone is mostly a wrapper-and-config exercise rather than a rewrite. For a researcher evaluating which base model to build on, that means the framework cost of switching backbones is low, and the reference integrations for HunyuanVideo and Wan double as documentation for future ones.
Claude skills that carry the experience
The team packaged its project experience as three Claude skills, which is an unusual and practical choice. debug-world-model collects failure modes from the training pipeline: loss NaN, frame-to-frame jitter, camera drift, memory attenuation, distillation collapse. Instead of a model guessing at your symptoms, the skill diagnoses likely root causes from a curated catalog of what actually went wrong during the project.
integrate-new-backbone is a step-by-step recipe for plugging a new video DiT into minWM, grounded in the HunyuanVideo and Wan reference integrations. onboarding-world-model targets researchers entering the field, with two parts: foundations covering teacher forcing for AR diffusion training and the Causal Forcing pair for distillation, and pitfalls listing the non-obvious mistakes the team hit while building minWM. Stated audience: graduate students, independent researchers, and junior labs that would otherwise spend about three months reverse-engineering existing repos.
Installing it
The install path is a standard conda environment plus an editable install, with flash-attn handled separately because of its build requirements:
conda create -n minwm python=3.12 -y
conda activate minwm
pip install -r requirements/base.txt
pip install flash-attn --no-build-isolation
pip install -e . # editable install: makes `import minwm` resolve, no PYTHONPATHAll downloaded weights live under ./ckpts/ after download, and the README includes a checkpoint table mapping each file to its backbone, stage, and use case. The demo checkpoints let you run inference before committing to any training, and an optional step overlays the key indicator on demo videos so you can see what the model is tracking. Full requirements, verification steps, and troubleshooting live in INSTALL.md.
Who should pick it up
If you already run a production world-model pipeline, minWM is probably a reference implementation rather than a dependency. The audience named in the README is narrower and honest: people who want to enter the world-model space without spending three months reverse-engineering someone else's repository.
For that audience the combination is well matched. The pipeline gives you a working baseline end to end, the staged checkpoints make failures localizable, the two backbone integrations show the pattern for adding your own, and the Claude skills encode the debugging knowledge that normally lives only in the heads of people who ran the experiments. The WeChat group and Hugging Face model page give newcomers somewhere to take questions once the skills run out.
Editorial conclusion
minWM is worth attention less for any single model and more for what it open-sources around the model: a complete data-to-inference path, staged distillation with inspectable checkpoints, two backbone integrations that demonstrate how to add a third, and Claude skills that turn one team’s debugging scars into onboarding notes. For labs and independent researchers entering the world-model field, that combination cuts the entry cost from months of repo archaeology to a conda install and a weekend of reading.
Frequently asked questions
Is minWM a pretrained world model I can download and run?
It is a framework plus demo checkpoints. You can download the demo weights and run 4-step DMD inference immediately, but the point of the project is the full pipeline that takes a bidirectional T2V foundation model and turns it into your own action-conditioned world model.
Which base models does minWM support?
Two backbone lines are supported today: Wan 2.1 (cross-attention plus DiT, 1.3B parameters) and HunyuanVideo 1.5 (MMDiT, 8B parameters). Both run all four training stages and share the same trainer, loss, and dataset abstractions, so a third backbone is mostly a wrapper-and-config job.
What does the 4-step distillation pipeline involve?
Phase 1 is bidirectional SFT. Phase 2 runs teacher forcing AR diffusion, then Causal ODE (from the Causal Forcing paper), then Causal CD (from Causal Forcing++), and finally asymmetric DMD with self rollout, which produces the 4-step real-time student model. Each stage exposes its own checkpoints.
Community notes