HumanoidClimb-RL: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Environment setup

conda create -n climb python=3.10
conda activate climb
conda install numpy pybullet gymnasium stable-baselines3 wandb --channel conda-forge
pip install stable-baselines3[extra]

Training uses CUDA when available (torch.cuda.is_available()), otherwise CPU. wandb is used for run tracking — wandb login must be configured before running train.py / autotrain.py.

Common commands

Train PPO from scratch with N parallel workers (uses SubprocVecEnv with start_method="spawn" — must run under if __name__ == '__main__':, which train.py already does):

python train.py HumanoidClimb-v0 PPO -w 4 -t

Continue training from an existing checkpoint:

python train.py HumanoidClimb-v0 PPO -w 4 -t -f path/to/model.zip

Test a trained single-stance model in the GUI (uses STANCE_14_1 hardcoded in train.py):

python train.py HumanoidClimb-v0 PPO -s path/to/model.zip

Run the full multi-stance climb demo (chains STANCE_1..STANCE_4 policies sequentially with GUI controls r/space/q):

python main.py        # single PPO model loaded from humanoid_climb/models/
python humanoid_climb/climb.py   # chains 4 PPO policies, one per stance

Generate end-of-stance state files (.npz saved under humanoid_climb/states/) by rolling out a trained model:

python collect_states.py   # edit STANCE / MODEL_FILE constants at top first

Inspect joint/part names from humanoid_symmetric.xml (PyBullet GUI):

python joint_test.py

There are no tests, linters, or build steps in this repo.

Architecture

This is a hierarchical climbing-RL setup: one PPO policy is trained per stance transition (a "stance" = which target hold each of the 4 effectors is gripping), then policies are chained at evaluation time.

Data flow

1. config.json is the single source of truth for the simulation: assets (URDF/MJCF paths), climber joint forces and collision groups, holds (3D positions on the wall), and a stance_path (sequence of desired_holds / force_attach / ignore_holds). ClimbingConfig (humanoid_climb/climbing_config.py) loads it and resolves asset references.
2. HumanoidClimbEnv (humanoid_climb/env/humanoid_climb_env.py, registered as HumanoidClimb-v0 in humanoid_climb/__init__.py) consumes the config, builds the PyBullet scene (plane, wall, holds, humanoid), and exposes a 21-dim action / 306-dim observation gym env. The motion path is read from the config's stance_path; each step advances desired_stance_index when current_stance == desired_stance.
3. Humanoid (humanoid_climb/assets/humanoid.py) wraps the MJCF robot. The 21-dim action is split: first 17 are joint torques (scaled by power * joint_forces[name]), last 4 are grasp signals (one per effector — left/right hand/foot). Grasp > 0 triggers attach(), which creates a PyBullet JOINT_POINT2POINT constraint to the nearest hold within penetration distance (uses getClosestPoints with 0.0 threshold). force_attach constraints can be overridden per-stance via action_override/force_attach, and excluded holds via exclude_targets/ignore_holds.
4. Asset (humanoid_climb/assets/asset.py) is a thin wrapper for static URDF/MJCF objects (wall, holds, plane). robot_util.addToScene (PyBullet's standard helper) populates parts/joints/ordered_joints.