How hexafuture/hexashell works
HexaShell is a task-agnostic harness for coding agents controlling simulated and real robots. The principal workflow is an episode: a model receives a task card and observations, runs Python tool calls in a sandbox, and gets motion/perception results while a benchmark or robot session supplies observations and reports the verdict. The graph preserves the documented simulation, real-robot, perception, and motion branches. Some adapter internals and prompt/skill assets are unsampled or absent from the supplied tree; those links are not inferred beyond explicit documentation or indexed imports.
Main entry points: episode.py Episode loop · host.py Robot API host · scene.py Scene perception · armserver.py Benchmark server
Components 28
Agent episode
- Episode loop
hexashell/runtime/episode.py - Conversation
hexashell/runtime/conversation.py - Model client
hexashell/runtime/llm.py - Task card
hexashell/runtime/card.py - Episode records
hexashell/runtime/records.py - Session contract
hexashell/runtime/session.py - Cell host
hexashell/kernel/host.py - Sandbox worker
hexashell/kernel/worker.py - Python sandbox
hexashell/kernel/sandbox.py
Robot tools
- Robot API host
hexashell/robot/host.py - Motion planner
hexashell/motion/driver.py - Inverse kinematics
hexashell/motion/ik.py - Arm kinematics
hexashell/motion/chain.py - Observation state
hexashell/state.py
Perception
- Scene perception
hexashell/vision/scene.py - RGB-D geometry
hexashell/vision/rgbd.py - Camera models
hexashell/vision/cameras.py
Execution adapters
- Simulator session
hexashell/benches/session.py - Benchmark server
hexashell/benches/armserver.py - LIBERO adapter
hexashell/benches/libero/server.py - RoboCasa adapter
hexashell/benches/robocasa/server.py - RoboTwin adapter
hexashell/benches/robotwin/server.py - RoboDojo bridge
hexashell/xpl/session.py - Real robot session
hexashell/real/urai/session.py
External systems
- SAM 3 service
services/sam3_server.py
Other components
- Coding agent
- Benchmark simulator
- PiPER-X robots
Connections 26
- Coding agent → Episode loop: starts episode
README.md - Episode loop → Conversation: runs conversation
hexashell/runtime/episode.py - Episode loop → Model client: queries model
hexashell/runtime/episode.py - Episode loop → Task card: builds task card
hexashell/runtime/episode.py - Episode loop → Episode records: writes records
hexashell/runtime/episode.py - Episode loop → Session contract: uses session
hexashell/runtime/episode.py - Episode loop → Cell host: runs cell
hexashell/runtime/episode.py - Cell host → Sandbox worker: dispatches cell
hexashell/kernel/host.py - Sandbox worker → Python sandbox: executes code
hexashell/kernel/worker.py - Robot API host → Motion planner: delegates motion
hexashell/robot/host.py - Motion planner → Inverse kinematics: plans paths
hexashell/motion/driver.py - Motion planner → Arm kinematics: uses arm chain
hexashell/motion/driver.py - Robot API host → Scene perception: serves perception
hexashell/robot/host.py - Scene perception → RGB-D geometry: uses RGB-D geometry
hexashell/vision/scene.py - Scene perception → Camera models: uses camera models
hexashell/vision/scene.py - Scene perception → SAM 3 service: requests segmentation
README.md - RoboDojo bridge → Robot API host: creates robot host
hexashell/xpl/session.py - RoboDojo bridge → Scene perception: configures perception
hexashell/xpl/session.py - Simulator session → Benchmark server: starts server
hexashell/benches/session.py - LIBERO adapter → Benchmark server: uses server base
hexashell/benches/libero/server.py - RoboCasa adapter → Benchmark server: uses server base
hexashell/benches/robocasa/server.py - RoboTwin adapter → Benchmark server: uses server base
hexashell/benches/robotwin/server.py - Benchmark simulator → Benchmark server: runs benchmark
- Real robot session → Robot API host: provides robot host
- PiPER-X robots → Real robot session: receives control
- Robot API host → Observation state: reads observations
hexashell/robot/host.py