Dex SuperMimic

This repository reproduces SuperMimic on a dexterous hand, adapting its world-model-based training approach to in-hand cube reorientation with Wuji Hand 2. It is built on mjlab and MuJoCo Warp.

The bundled assets cover Wuji Hand 1 and Hand 2 tasks, so installation does not require a Git submodule checkout.

Wuji Hand 1 · Cube Reorientation	Wuji Hand 2 · Cube Reorientation	Wuji Hand 2 · Pen Spin

• Overview
• Requirements
• Installation
• Tasks
• Training
• Visualization
• Pretrained Checkpoint
• Acknowledgments

The project retains SuperMimic's three-phase idea:

1. collect short real-simulator rollouts into a replay buffer;
2. train a recurrent-style, multi-step world model on mixed normal and failure transitions;
3. optimize the policy and critic along imagined rollouts, periodically refreshing the buffer from the real simulator.

The implementation is task-aware: cube reorientation uses command/goal observations, an absolute EMA controller, contact and cage rewards, and a translucent world-model ghost in Viser. Pen spin tracks a packaged motion reference, uses a reference-plus-residual controller, and exposes the standard viewer without the cube-specific ghost overlay.

• Linux x86_64 with an NVIDIA GPU is required for training and playback. CUDA 12.8 is tested; Blackwell/RTX 50-series GPUs are supported by MuJoCo Warp.
• macOS arm64 can install and import the package, but training intentionally rejects non-CUDA devices.
• Python 3.10–3.13 is selected automatically by uv.
• At least one CUDA-capable GPU with enough memory for the requested parallel environment count. --num-envs 1024 is the default starting point.
• Disk space for the virtual environment, Wuji meshes, pen-spin motion catalog, checkpoints, and TensorBoard events.

Install uv if it is not already available:

curl -LsSf https://astral.sh/uv/install.sh | sh
source "$HOME/.local/bin/env"

Clone this repository and install the dependencies:

git clone https://github.com/CumulusAlpha/Dex-Supermimic.git
cd Dex-Supermimic
uv sync

Run from the repository root. The first launch may spend extra time compiling Warp and imagination kernels.

# task: hand1-reorient | hand2-reorient | hand2-pen-spin
uv run dex-supermimic-train --task hand1-reorient

Before training hand2-pen-spin, download its upstream motion catalog:

uv run python -m dex_supermimic.tasks.pen_spin.tooling.download

Viser playback uses one environment, opens a URL in the terminal, and runs until interrupted:

uv run dex-supermimic-play --checkpoint <checkpoint.pt>

Inspect TensorBoard curves with:

uv run tensorboard --logdir logs/dex_supermimic

Pretrained checkpoints are distributed separately as GitHub Release attachments. The _8000 suffix indicates that these checkpoints were saved after 8,000 training iterations:

mkdir -p logs/dex_supermimic/pretrained

curl -fL --retry 3 -o logs/dex_supermimic/pretrained/model_hand1_reorient_8000.pt \
  https://github.com/CumulusAlpha/Dex-Supermimic/releases/download/pretrained-wuji-v2/model_hand1_reorient_8000.pt

curl -fL --retry 3 -o logs/dex_supermimic/pretrained/model_hand2_reorient_8000.pt \
  https://github.com/CumulusAlpha/Dex-Supermimic/releases/download/pretrained-wuji-v2/model_hand2_reorient_8000.pt

curl -fL --retry 3 -o logs/dex_supermimic/pretrained/model_hand2_pen_spin_8000.pt \
  https://github.com/CumulusAlpha/Dex-Supermimic/releases/download/pretrained-wuji-v2/model_hand2_pen_spin_8000.pt

uv run dex-supermimic-play \
  --checkpoint logs/dex_supermimic/pretrained/model_hand1_reorient_8000.pt

The logs/ directory is Git-ignored, so the checkpoints remain separate from the source checkout. model_hand2_reorient_8000.pt is the previously released Hand 2 cube-reorientation checkpoint, renamed to identify its task and 8,000-iteration training point.

We thank the SuperMimic authors for the original method.

We thank the authors and contributors of the following repositories:

1. InstinctMJ — the foundation of this repository and its mjlab-based simulation framework.
2. Wuji MJLab — the Wuji hand cube-reorientation and pen-spin task implementations.
3. supermimic_vibed — the SuperMimic reproduction.