Minecraft agents that do whatever you ask. Each agent is a real player (Mineflayer) in a vanilla world; TypeSafe's JEV model picks every action it takes, and a planner model (Claude Opus 5.5 or GPT-6 Astra, on the subscription you already have) understands what you say and speaks for it.
Use it two ways:
- As an MCP server inside Claude Code or Codex — "start a world and spawn a bodyguard for me".
- As a CLI — herobrine up --world play,herobrine spawn --persona "my bodyguard",herobrine tell Cedar "bring me 5 logs".
Both drive the same core; the CLI also works against the MCP instance while Claude Code has it open.
Agents have no fixed roles. Each one has three free-text fields, and the user can change any of them at any time:
With no task, the agent picks its own next short-term task based on its persona and long-term goal. Tasks end as done or stuck.
Each agent gets a short single-word Minecraft-style name (e.g. Flake, Basalt, Cedar) when it spawns. Names are never reused in the same world.
Two models with clearly separated jobs:
- System Two — the planner (src/planner.mjs): a full language model that turns what people say into a typed task, reviews progress, picks the next task from the persona and long-term goal, and writes every chat reply. It runs through the host you already use, so no extra key is needed:- Claude Code → an ACP session (claude-code-acpdriving your installedclaude) with Opus 5.5
- Codex → codex mcp-server(codex/codex-replythreads) with GPT-6 Astra
- or an API key (ANTHROPIC_API_KEY,OPENROUTER_API_KEY,OPENAI_API_KEY) One persistent session per agent, so it remembers the conversation.
- Claude Code → an ACP session (
- System One — JEV (src/jev.mjs): TypeSafe's choice model. Once a second it picks one concrete action from a menu built from what the agent can see. It never sees free text.
player chat / dashboard / MCP text ──▶ planner ──▶ TaskSpec {kind, items, recipient, location, entity, until} + reply
│
world memory ◀── observe ──▶ action menu ──▶ JEV picks one ──▶ Mineflayer executes (bounded)
│
predicates verify completion (inventory / delivered / arrived / killed / built)
planner reviews "judged"/"ongoing" tasks, budgets and repeated failures
- Typed tasks (src/tasks.mjs): completion is verified by the game state, not declared by a model.items(inventory),delivered(hand-over events),arrived(distance),killed,built,ongoing(follow/guard),judged(planner reviews it). Item matches are exact ids, globs (*_log) or categories (food,tool,building…) resolved from the game's own registry.
- Prerequisites (src/actions.mjs): for "make a stone pickaxe" the missing chain (logs → planks → table → sticks → wooden pickaxe → cobblestone) is worked out from Minecraft's recipe data and shown to JEV as the next step.
- World memory (src/memory.mjs): last-seen player positions, known tables/furnaces/chests/beds/ores, visited areas, home. Every action can target something out of view ("walk to where satuke was last seen", "go back to the furnace").
- Chat: Cedar <anything>,all <anything>, or a whisper. The planner decides whether it is a task, a goal, a persona change, a stop/resume, or just a question, and answers in character and honestly.
Requirements: Node 20+, a TypeSafe (JEV) key, and a planner: Claude Code (logged in) or Codex (logged in) on the same machine, or an API key. To run worlds locally you also need Java: 21+ for Minecraft 1.20.5 and later, 17 for 1.17–1.20.4.
git clone git@github.com:xatuke/herobrine.git && cd herobrine
npm install
npm link # puts `herobrine` on your PATH (optional)
herobrine config set key <TYPESAFE_KEY> # or: config set key-file /path/to/keyfileherobrine up --world play --difficulty peaceful # daemon + world (asks you to accept the Minecraft EULA)
herobrine spawn --world play --persona "a friendly survival companion" --goal "get us iron gear" --owner YourName
herobrine tell Cedar "bring me 5 logs" # planner interprets it, agent replies
herobrine chat Cedar # interactive conversation
herobrine status # everything at a glance
herobrine logs Cedar -f # follow task / chat / planner events
herobrine actions Cedar # the menu JEV is choosing from right now
herobrine cmd play "time set day" # server console
herobrine down # stop agents, worlds and the daemonherobrine is a thin client of the local HTTP API (http://127.0.0.1:3600, also the dashboard). herobrine up starts a daemon that runs the same core as the MCP server; if Claude Code already has the MCP open, the CLI talks to that instead.
claude mcp add herobrine -e TYPESAFE_API_KEY=your_key -- node /absolute/path/to/herobrine/src/server.mjs[mcp_servers.herobrine]
command = "node"
args = ["/absolute/path/to/herobrine/src/server.mjs"]
env = { TYPESAFE_API_KEY = "your_key" }
tool_timeout_sec = 300 # first start_server downloads the jar and generates a worldTYPESAFE_KEY_FILE=/path/to/keyfile or herobrine config set key ... work instead of putting the key in the config. The key stays in the server process and is never logged.
- Toward Claude Code / Codex it is an MCP server (that's what you add, and what exposes the tools).
- Inside, it is an ACP client: it spawns Claude Code as an ACP agent to use Opus 5.5 as the planner (with Codex it uses codex mcp-serverinstead).
- The CLI talks plain HTTP to the same process.
Just talk to Claude or Codex:
Start a peaceful survival world and spawn two agents. One should be my bodyguard; the other should get us iron tools.
Tell Cedar to bring me 10 logs.
Make Flake act like a lazy farmer who complains a lot.
Watching: herobrine status, herobrine logs <agent> -f, or open the dashboard at http://127.0.0.1:3600 (or ask for open_dashboard). It shows each agent's live 3D view, persona, goals, current task and action, next prerequisite, inventory and recent results, plus a box to send it instructions. You can also join the world with Minecraft Java at the same version: Multiplayer → Direct Connect → localhost:25565. Managed servers run in offline mode.
~/.minecraft-jev-mcp/config.json (written by herobrine config set …) can hold typesafeApiKey / typesafeKeyFile, planner and plannerModel; environment variables override it. Agent logs (every JEV decision and result) are written to ~/.minecraft-jev-mcp/logs/<name>.jsonl. Performance and cost numbers: BENCHMARKS.md.
- Offline-mode servers only. Agents join as offline players. Online-mode (Microsoft-authenticated) servers aren't supported.
- Menu-based control. JEV chooses from concrete actions and Mineflayer does the pathfinding. Agents don't see screenshots and don't press individual keys.
- Free-form building is basic. Agents can place blocks around themselves and pillar up, but there's no blueprint builder yet.
- Planner latency. Interpreting an instruction takes ~4–15 s (Opus/Astra); the agent keeps acting on its current task meanwhile. JEV decisions stay sub-second.