aicc-capsule — Reference Testbed

Reference implementation of the AICC Protocol in a 3D environment: an AI-controlled capsule in a room. This is the "hello world" of the protocol — a working end-to-end vertical that proves the spec is implementable and gives other projects a template to copy.

Goal

A 3D room with a capsule that an LLM agent controls through AICC sensor/actuator tools. The agent perceives the world via tools (vision, proprioception, hear), reasons, and acts (move, turn, look_at, interact). No pixel-clicking, no engine-specific hooks — pure protocol.

Status

Working. The testbed is built: headless 3D room with a capsule, a protocol-conformant bridge (9/9 conformance scenarios), and a demo in which an agent (LLM or scripted) navigates to the beacon and activates it. See testbed/README.md for run instructions; scripts/BUILDLOG.md for the build log.

Layout

aicc-capsule/
  AGENTS.md           # instructions for AI coding agents (opencode, claude, etc.)
  README.md           # this file
  docs/
    aicc-core.md      # AICC Protocol spec, v0.1 (copy from AICC-Protocol repo)
    aicc.schema.json  # JSON Schema for all AICC messages
    testbed-design.md # design notes for the testbed itself (see below)
  scripts/            # build/run/dev scripts
  testbed/            # the testbed source (empty until built)

Reading order for an agent

1. AGENTS.md — what to build, constraints, definition of done
2. docs/aicc-core.md — the protocol contract (sections 1–5 are essential)
3. docs/testbed-design.md — how the testbed maps onto the protocol
4. ~/Desktop/aicc-py — the SDK to build on (Bridge, AICCClient, transports)

Related repositories

• Spec: https://github.com/emil28092005/AICC-Protocol
• Python SDK: https://github.com/emil28092005/aicc-py (local checkout: ~/Desktop/aicc-py)