Humanoid-GPT: A GPT-Style Motion Tracker for the Unitree G1
Official implementation of AstraBrain-WBC 0.5
At a glance
- What is it?
- Humanoid-GPT is the reference implementation of AstraBrain-WBC 0.5, a causal Transformer policy that tracks unseen motion without fine-tuning. It ships inference and deployment code for the Unitree G1, but no training code and no training data.
- Who is it for?
- Adopt Humanoid-GPT if you already have a Unitree G1 or a CUDA 12.x machine and want to run a released ONNX tracking policy against your own retargeted mocap, since the .onnx checkpoint and a sample trajectory under storage/test are enough to start. Do not adopt it if you need to reproduce the 2B-frame pre-training: the TODO list still marks training code and training data as unshipped, so the billion-scale claim cannot be checked from this repository.
- 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 29 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
The gap Humanoid-GPT is aimed at
Most humanoid motion trackers are shallow MLP policies trained per motion or per motion family. The README frames the field as constrained by scarce data and by an agility versus generalization trade-off, and positions Humanoid-GPT as the answer: a GPT-style Transformer pre-trained on a 2B-frame retargeted corpus that unifies major mocap datasets with in-house recordings. The stated goal is zero-shot tracking, meaning arbitrary unseen motions without fine-tuning.
The intended user is a robotics engineer with a Unitree G1 (29 DOF whole-body) who wants to run a released tracking policy rather than train one. That framing matters, because the repository is an inference and deployment release, not a training release. If your interest is the pre-training recipe, this is the wrong artifact.
What the causal Transformer actually consumes
The architecture is a causal Transformer with Rotary Position Embeddings, which the README says supports variable-length motion sequences. Causal attention plus RoPE is the same family of choices that lets language models consume sequences of differing length without a fixed positional table, and here it is applied to motion frames instead of tokens.
The data flow visible in the repository runs from retargeted mocap to keypoints to policy. The policy consumes a keypoint representation, and the repository ships converters for it: tracking/convert_qpos2kpt.py turns a single mocap .npz into that representation, and tracking/convert_parallel.py does the same across a directory with a worker count. On the policy side, tracking/policy.py is described as the ONNX policy wrapper, and storage/ holds assets, configs, a sample trajectory and the released checkpoints. Simulation and rendering live under utils/, built on MuJoCo and MuJoCo-MJX, with Brax listed among the acknowledgments.
The expected motion file is a .npz containing either qpos directly, or root_pos, root_rot and dof_pos arrays. That is a narrow contract, and it is the first thing to check against your own data.
Installing Humanoid-GPT and running a first track
The README targets an NVIDIA GPU with CUDA 12.x and Conda or Miniconda. macOS is supported for testing if you skip jax[cuda12] and use mjpython for the MuJoCo viewer. The package requires Python >=3.11,<3.13.
The install is a clone plus an editable pip install, with the extra selected by platform. On Linux with an NVIDIA GPU, the cuda extra pulls jax-cuda12-plugin and onnxruntime-gpu; on macOS the cpu extra is the substitute.
git clone https://github.com/GalaxyGeneralRobotics/Humanoid-GPT.git
cd Humanoid-GPT
conda create -n h-gpt python=3.12 -y
conda activate h-gpt
pip install -e ".[cuda]" # or ".[cpu]" on MacOS, or "." for real robot deploy-onlyWith the environment active, the README says a pre-trained .onnx tracking policy and a sample trajectory under storage/test/ are all you need. The single-motion command points at storage/ckpts/pns_wo_priv264.onnx and the sample directory; you should see the policy roll out against that trajectory.
python -m scripts.inference --onnx_track storage/ckpts/pns_wo_priv264.onnx --track_dir storage/testThere is also an interactive Gradio demo, a parallel evaluator that takes --workers and --privileged, and a trajectory visualizer.
python -m scripts.app
python -m scripts.eval_parallel --onnx_track storage/ckpts/pns_wo_priv264.onnx \
--track_dir storage/test --workers 32 --privileged
python -m scripts.vis --path storage/testTo bring your own retargeted mocap in, convert it first. The single-file path has a --debug flag for visualization; the parallel path takes --src_dir, --save_dir and --num_workers.
python tracking/convert_qpos2kpt.py --mocap_npz <mocap_path.npz> --debug
python tracking/convert_parallel.py --src_dir <in_dir> --save_dir <out_dir> --num_workers 32On macOS, the README says to run the viewer through mjpython rather than python, for example mjpython -m scripts.app. Hardware variants are selected with the G1_VERSION environment variable, defaulting to 5010, which picks storage/assets/unitree_g1_${G1_VERSION}/ automatically.
Deployment on the G1 is a separate chain
Getting a policy to track in simulation and getting it onto a robot are different problems here, and the repository keeps them apart. Deployment is split into sub-modules under deploy/, and the README points to deploy/DEPLOY.md for install and SDK setup before anything else.
The simulation entry point is python -m deploy.play_track --track-dir storage/test, and the real-robot path adds --real and a network interface name. Three variants sit alongside: onboard_deploy/ for Jetson Orin on-board deployment with its own DEPLOY_ONBOARD.md, onboard_deploy_wo_GMR/ for an on-board build that streams retargeting from a host, and brainco/ for a BrainCo dexterous-hand tracking variant.
That split is a reasonable design. It also means the real-robot path depends on documentation the README does not inline, and on a network interface you supply. Nothing in the README describes a rollback procedure or a safety envelope for the --real path.
The training half is not in this repository
The TODO list is the most important section for anyone evaluating the paper's claims. Inference and deployment code are checked off. Pre-trained model checkpoints under storage/ckpts/ are checked off. Training code is not. Training data is not.
So the 2B-frame corpus and the scaling result are described but not reproducible from what ships. You can run the policy, convert motions into the representation it consumes, and evaluate tracking metrics, but you cannot retrain it or inspect the data pipeline that produced it. For a CVPR 2026 paper release this is a common split, and it is worth stating plainly rather than treating the repository as a full artifact.
The practical consequence is a hard boundary: you can use Humanoid-GPT as a policy, and you can fine-tune nothing, because there is no training loop to fine-tune with. The README's zero-shot claim is the only mode available.
Where it fits against other motion-tracking work
The related searches around this project name SONIC, HoloMotion, MotionMillion and HoloMotion-1, which suggests the natural comparison set is other large-scale humanoid motion systems. The README does not describe those projects, so the honest comparison is structural rather than benchmarked.
What can be said is what Humanoid-GPT commits to. It is a causal Transformer with RoPE rather than a shallow MLP tracker, it is tied to one platform (the Unitree G1, 29 DOF), and it ships an ONNX policy plus MuJoCo-MJX simulation rather than a training framework. A project that ships training code and data would let you reproduce its scaling curve; this one lets you deploy its output. If your evaluation criterion is reproducibility of the pre-training result, that difference decides the choice before any performance number is considered.
The projects/ directory hints at optional side modules: hme/ for a Harmonic Motion Encoder described as a periodic autoencoder, gqs/ for General Quality Selection with physics and diversity scoring, and transformer/ for a Transformer tracking policy with inference and deploy. Those are described in the structure listing but not documented in the README.
Licence, dependencies and upgrade cost
Humanoid-GPT is Apache-2.0, both in the repository LICENSE file and in the pyproject.toml license field. Apache-2.0 is permissive and includes an explicit patent grant, which matters for a robotics stack that may end up in a product. It also means redistributing a modified version requires carrying the licence and notices. This is a description of the licence text, not legal advice; check the terms against your own distribution model.
The dependency pins are the real upgrade cost. pyproject.toml pins numpy==2.3.4, mujoco==3.3.7, mujoco-mjx==3.3.7, jax==0.8.0, flax==0.12.0, torch==2.8.0, warp_lang==1.9.0, opencv-python==4.11.0.86, mink==1.1.0, and onnxruntime<1.24. The cuda extra pins jax-cuda12-plugin==0.8.0, onnxruntime-gpu<1.24 and gradio==6.11.0. JAX and MuJoCo move quickly, and these exact pins are what the release was built against, so an unpinned environment is the likely source of a first-run failure.
The last push to the default branch was on 2026-08-20, and the repository is not archived. No releases were retrieved, so there is no versioned upgrade path to follow; you track main. The package version in pyproject.toml is 0.1.0, while the README describes the implementation as AstraBrain-WBC 0.5, so the version string and the project naming do not line up and should not be treated as interchangeable.
Editorial conclusion
Adopt Humanoid-GPT if you already have a Unitree G1 or a CUDA 12.x machine and want to run a released ONNX tracking policy against your own retargeted mocap, since the .onnx checkpoint and a sample trajectory under storage/test are enough to start. Do not adopt it if you need to reproduce the 2B-frame pre-training: the TODO list still marks training code and training data as unshipped, so the billion-scale claim cannot be checked from this repository. Before anything else, confirm that your motion is already in the expected .npz form with qpos or root_pos, root_rot and dof_pos arrays, and that your G1 hardware version matches the storage/assets/unitree_g1_${G1_VERSION}/ folder you intend to load.
Frequently asked questions
What is Humanoid-GPT?
It is the official implementation of AstraBrain-WBC 0.5, described in the README as a GPT-style humanoid motion Transformer trained with causal attention for whole-body control. The repository ships inference and deployment code plus pre-trained ONNX checkpoints, and targets the Unitree G1 with 29 DOF.
How do I install Humanoid-GPT?
The README requires an NVIDIA GPU with CUDA 12.x and Conda or Miniconda, then a clone followed by an editable pip install with the cuda extra on Linux or the cpu extra on macOS. macOS is supported for testing if you skip jax[cuda12] and use mjpython for the MuJoCo viewer.
Does Humanoid-GPT include training code and training data?
No. The TODO list marks inference and deployment code and pre-trained checkpoints as done, while training code and training data remain unchecked, so the 2B-frame pre-training cannot be reproduced from this repository.
Which robot does Humanoid-GPT support?
The README states it is optimized for the Unitree G1 humanoid robot with 29 DOF whole-body control. Multiple G1 hardware versions are selected through the G1_VERSION environment variable, which defaults to 5010 and picks storage/assets/unitree_g1_${G1_VERSION}/.
Community notes