ANIMA Zero

🤖 If you are an AI agent, read AGENTS.md first — the machine-facing entry point: the layering rule, where each fact lives, and the commands.

Overview

ANIMA Zero is the brain of an embodied robot. It thinks but never moves: it decides what to do, and the body decides how to move.

Tell it "go to the living room". It has no map, no coordinates and no list of rooms — only the camera on the robot's head. From that it works out where it is, picks a direction, and keeps walking until it sees the room you asked for. The robot walks with a learned gait, so the legs really step; nothing teleports.

_{One brain, two bodies: a G1 humanoid above, a Go2 quadruped below. In each clip the left half is the only input ANIMA gets; the right half is what actually happens, which it never sees.}

Why "Zero"?

It is a series name, not a version number. Zero means this line stays open source — the brain is ANIMA Zero, the body is Open Chess Robot, and any future commercial edition will carry a different name rather than closing this one. The whole project is MIT.

On PyPI it is pip install anima-zero and the import is import anima — anima alone was already registered by someone else.

Key features

• One brain, different bodies: the same brain code drives a Unitree Go2 quadruped and a Unitree G1 humanoid without a line changing — only the eye height differs, 0.38 m against 1.25 m.
• One interface for any world: a world is a separate process speaking AWI over MCP. Swapping worlds means swapping a URL — and a world is untrusted until you have reviewed and approved it.
• From a sentence to joint torques: an instruction crosses five layers before it becomes leg motion, and those layers run three and a half orders of magnitude apart in frequency.
• It remembers what it is doing: two state registers ride along in the system prompt, so a sixty-step turn does not forget the goal or what it has already ruled out.
• Auditable and interruptible: every frame, thought and tool call is recorded, and a running turn can be stopped mid-flight.

_{The same living room through the quadruped's eyes (left) and the humanoid's (right). What a robot can see decides what it can conclude, which is why the scene is built realistically rather than tailored to one machine.}

Architecture

A world is a program of its own — a simulator today, real hardware later. ANIMA never reaches inside it. Everything the brain knows arrives through four channels, and everything it does leaves through the same four. A human can also bypass the brain entirely and poke the world in its own UI, which is the clearest proof that the two are genuinely separate.

The three endpoints along the bottom — ground truth, video and liveness — never travel over MCP and never reach the brain. That separation is deliberate: the moment ground truth enters perception, the ability this world is meant to test is given away for free.

Inside a single instruction the layering becomes concrete. The brain reasons once per step; the gait policy runs at 50 Hz; physics at 500 Hz. That gap is what System 2 and System 1 actually mean here, and it is why the brain can only ever issue intent, never joint angles.

The world reports back truthfully rather than conveniently. A learned gait does not track a velocity command exactly — a turn drifts, a walk falls short — so the world measures what actually happened and says so, and the brain corrects its own sense of position from that rather than from what it asked for.

src/core/      orchestrator, AWI contract, trust store, safety gate
src/clients/   MCP client layer and the world registry
src/session/   sessions, context window, unified log
src/llm/       model adapters      src/presentation/  HTTP backend
world/         the worlds, each its own process
services/      board-game engine   frontend/  web app   eval/  scoring

Installation

uv tool install anima-zero     # or: pipx install anima-zero, or plain pip
anima demo

That is the whole first five minutes. The demo starts a tiny bundled world — a dot on an eight-cell corridor, ANIMA's talker/listener — picks a brain, and runs one real turn: if you have an API key it uses it, otherwise it walks you to a free local brain that runs on your CPU (Qwen3-4B-Instruct via Ollama — qwen3:4b-instruct, ~2.5 GB, offered as a one-line pull). Every frame, thought and tool call lands in a session log you can read afterwards. Nothing you see is staged, and anima doctor will tell you where on your disk all of it landed.

A real world is a separate program and none ships in the wheel, so the next step is to get one: clone this repository for the worlds in world/, or write your own against the AWI spec — src/examples/minimal_world.py, the corridor from the demo, is the template to copy.

The fastest way to find your way around is to hand the repository to a coding agent — Claude Code, Codex, or whichever you use — and let it read AGENTS.md, which is written for exactly that. It will start a world with you, or write you a new one.

anima demo                    prove the loop works: a bundled world, one brain, one real turn
anima chat --world W          a conversation in the terminal
anima run --say "..."         one turn, scripted
anima serve                   the backend API, for the web app
anima world add NAME URL      register a world — and review it before approving
anima doctor                  what is configured and what is reachable

Stuck? The FAQ covers the six things new users actually trip over.

The full setup

Three processes: a world, the backend, and the web app. Scenes and robots come from alice-house, looked up next to this repository; set HOUSENAV_ASSETS_ROOT if it is elsewhere.

cd world/sim-house-nav && pip install -e . && uvicorn server:app --port 8112
pip install -e . && cp .env.example .env      # add an API key, or point at a local Ollama
anima serve
cd frontend && npm install && npm run dev

Connecting a world is a trust decision

A world is a remote process, and its own description of itself lands in the brain's system prompt — so its tools and guidance do not reach the brain until you have looked and said yes. anima world add NAME URL prints what it declares, then asks. Approval binds to the content, not the name: if the world comes back different you are asked again, with a note on what changed. While developing your own world, set ANIMA_TRUST_ALL=1. SECURITY.md says what this does and does not protect against.

Seeing it run

Open the web app, create a session against sim-house-nav, and type "go to the living room". The middle column shows what the robot sees and, separately, a chase camera that only you can see. The right column shows every step: frame, reasoning, tool call, and the world's answer.

To check whether a claim is true rather than plausible, ask the world directly — curl -s localhost:8112/status, an endpoint for human verification that never enters perception. Swapping things costs one line each: the body has a dropdown on the AWI dashboard (or set HOUSENAV_ROBOT=g1 before starting the world), the brain has one in the web app, and the world is chosen when you create a session.

These worlds ship with the repository:

How well it actually works

Five target rooms, one run each, every final frame checked by hand against what the model claimed:

The interesting result is the negative one. The suspected cause used to be that a kitchen and a bathroom look alike from 0.38 m, which is part of why the humanoid was added. But the humanoid, at 1.25 m, sees the hob and the range hood clearly and still calls it a bathroom. So this is not a perception problem: facing the same doorway, the model composes whatever story matches the room it is hunting for. The next release aims at the acceptance criterion instead.

Runs that did work, with per-frame verification, are written up in world/sim-house-nav/实测记录.md.

Add your own world

Implement a standard MCP server with the four channels above, add its address to ANIMA_WORLDS, and the brain will drive it unchanged. The smallest complete example ships inside the package: src/examples/minimal_world.py — the corridor from anima demo, annotated line by line against the spec, and runnable on its own with python -m anima.examples.minimal_world. Copy from camera if your world is only something to look at, sim-chess if it takes actions, or sim-house-nav for the complete one, and read world/README.md first. The contract is written down in docs/awi-spec-v1.md, and anima conformance <url> checks a world against it.

Acknowledgements

Scenes, robot models and locomotion policies come from alice-house. The humanoid's turning policy was trained in unitree-g1-locomotion. Physics is MuJoCo; the robot models originate from MuJoCo Menagerie.