MinecraftClaude — Claude Plays Minecraft

Concept

MinecraftClaude is a multi-agent experiment with a simple but ambitious goal: let Claude build the framework needed to play Minecraft from scratch, then play survival autonomously.

No game code is written by hand. A Python orchestrator spawns Claude Code agents that design, implement and test the system — then a game agent takes over and plays survival.

There are no direct Anthropic API calls: everything goes through the claude -p CLI, using the user’s existing Claude Code session.

Multi-agent architecture

The system relies on four distinct agents, coordinated by a Python orchestrator:

PM Agent

Reads project state (roadmap.json, code inventory) and decides the next task to assign to Dev. Also evaluates feature requests during the gameplay phase — rejecting anything resembling cheating (/give, creative mode, god mode, etc.).

Dev Agent

Receives a task specification and implements it using Claude Code tools (Bash, Read, Write, Edit, Glob, Grep). Tests the work before reporting back. Can retry up to 3 times if the implementation fails.

Game Agent

Runs in a continuous loop during gameplay. Each iteration it receives the game state (position, health, inventory, nearby blocks and entities), calls claude -p to decide the next action, and sends the command to the bot. Maintains persistent memory (goals, plan, knowledge, failed attempts) that survives restarts.

Node.js Bot

A Mineflayer bot that receives JSON commands via stdin and sends game state via stdout. Handles movement (A* pathfinding), mining, chat, and exposes a browser-based spectator view via prismarine-viewer.

File-based communication

Agents never communicate directly — all state passes through JSON files in project-state/:

roadmap.json          → milestone progress
code-inventory.json   → implemented features (prevents duplicate work)
pm-decision.json      → current PM decision
tasks/<id>.json       → task specification
current-report.json   → Dev's report
bot-memory.json       → game agent's persistent memory
bot-capabilities.json → available bot commands (updated dynamically)
bot-requests/<id>.json→ feature requests

This makes the system transparent, resumable after failure, and easy to audit.

Phase 1 — Building the framework

The orchestrator drives a PM → Dev loop across 5 milestones:

Milestone	Description
M1	Docker infrastructure, bot connects to server
M2	Mineflayer actions (movement, mining, chat), block scanning
M3	Agent ↔ bot game loop, persistent memory
M4	Browser spectator view, SSE chat relay
M5	Survival behaviours (safety, resources, tools, shelter)

Once all milestones are validated, the build phase stops and gameplay begins.

Phase 2 — Autonomous play and self-improvement

The game agent loops continuously: it receives state, calls Claude, executes the action, repeats. In parallel, if Claude finds it lacks a capability (e.g. placing a block), it submits a feature request. The PM evaluates it, Dev implements it, and the new command is available on the next iteration — no restart needed.

The bot plays legitimate survival: it must gather wood, craft tools, build shelter, and survive the night.

The orchestrator starts the Minecraft server (Docker), runs the build phase if needed, then launches the game loop. The spectator view is accessible at http://localhost:3007.