# supermimic (HybridRobotics/supermimic)

> SuperMimic is a research codebase that trains a humanoid robot to track whole-body motion. It uses one differentiable world model and is built on mjlab.

- GitHub: https://github.com/HybridRobotics/supermimic
- GitHub.Locker page: https://github.locker/HybridRobotics/supermimic
- Stars: 1.7K
- Language: Python
- License: Apache-2.0
- Last push: 2026-11-16

## Questions and answers

Written by GitHub.Locker from the README and the repository; check the README below for details.

**Is it a library I can import, or something I run?**

You run it. It is a training and playback tool with commands to train a world model and policy and to play back a trained one, not a package to import into your code.

**How do I get it running?**

Install uv, clone SuperMimic and mjlab as sibling directories, then use the train and play commands from the README.

**What do I need before I start?**

uv for environment setup and a local checkout of mjlab next to SuperMimic. The README does not list GPU, Python version or OS requirements.

**What makes the 'one differentiable world model' approach special?**

The README says one differentiable world model trains the whole-body tracker, but it does not explain the method in detail. The paper linked from the README is the place to learn how it works.

**How do the two task IDs differ in practice?**

Both target the G1 humanoid. GenCoord describes the robot with generalized coordinates, while MaxCoord uses maximal coordinates, so the choice depends on which representation you want to compare.

**Can I see a trained model before training my own?**

The README includes a step to play back a trained model, so you can check the results. Where to get a trained checkpoint is not stated in the README text.


---

## README (checked against GitHub 2026-11-18)

Source: https://github.com/HybridRobotics/supermimic/blob/main/README.md

# SuperMimic

[Project page](https://supermimic.github.io) | [Paper](https://arxiv.org/abs/2610.28480)

SuperMimic trains a humanoid whole-body motion tracker with one differentiable world model, built on [mjlab](https://github.com/mujocolab/mjlab).

## Setup

Install [uv](https://docs.astral.sh/uv/):

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Clone both repos as siblings:

```bash
mkdir supermimic_ws && cd supermimic_ws
git clone git@github.com:HybridRobotics/supermimic.git
git clone git@github.com:HybridRobotics/mjlab_research.git
cd supermimic
```

## Usage

Available task IDs:

- `SuperMimic-GenCoord-G1` — generalized coordinates representation
- `SuperMimic-MaxCoord-G1` — maximal coordinates representation

Train a world model and policy:

```bash
CUDA_VISIBLE_DEVICES=<GPU_ID> uv run src/supermimic/scripts/train.py \
  <TASK_ID> --runner.run_name <description>
```

Play back a trained model:

```bash
uv run src/supermimic/scripts/play.py \
  <TASK_ID> --wandb-path <RUN_PATH>
```

## Acknowledgements

SuperMimic contains code inspired by these projects:

- [ControlVAE](https://github.com/heyuanYao-pku/Control-VAE) (BSD-3-Clause)
- [robotic_world_model](https://github.com/leggedrobotics/robotic_world_model) (Apache-2.0)
- [DreamerV3](https://github.com/danijar/dreamerv3) (MIT)

## License

Copyright 2026 The SuperMimic Authors.

Released under the [Apache License 2.0](LICENSE).

