Show HN: Herobrine – Minecraft buddies using jev

A developer released Herobrine, an open-source Minecraft agent system that spawns real players via Mineflayer in vanilla worlds and drives every action through TypeSafe's JEV choice model, with a separate planner model (Claude Opus 5.5 or GPT-6 Astra) handling natural-language instructions. Herobrine runs either as an MCP server inside Claude Code or Codex or as a CLI (`herobrine up --world play`, `herobrine spawn --persona "my bodyguard"`), and each agent carries editable persona, long_term_goal and task fields with completion verified by game state rather than model declaration. It requires Node 20+ and reuses the user's existing Claude Code or Codex subscription, so no extra API key is needed.

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: | Field | Examples | |---|---| | persona : who to be and how to behave | "my bodyguard", "a chill builder who plays alongside me", "a grumpy dwarf miner who never leaves the caves" | | long term goal : an objective it works toward over time | "get us full iron gear", "build a base by the river" | | task : what to do right now | "collect 10 logs", "make a stone pickaxe", "come here", "bring me 5 cobblestone" | 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-acp driving your installed claude with Opus 5.5 - Codex → codex mcp-server codex / codex-reply threads 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. - 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/keyfile herobrine 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 daemon herobrine 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 world TYPESAFE 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-server instead . - 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 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. | Tool | Purpose | |---|---| | start server / stop server / list servers / server logs / server command | Run local vanilla servers needs accept eula: true after the user agrees to the Minecraft EULA | | spawn agent | Join a managed server, or any offline-mode server or LAN world by host / port , with persona/goal/task | | instruct agent | text in the user's words planner interprets, replies in chat and/or structured persona , long term goal , task TaskSpec , owner for one agent or all | | planner status | Active planner backend/model, call stats, and the TaskSpec schema | | agent status , agent events , read chat | See what agents are doing and what players said | | pause agent / resume agent / stop agent | Control | | agent say | Say something in game chat through an agent | | list actions / run action | See the current action menu, or run one step directly without JEV | | open dashboard | Get the dashboard URL | | Env | Default | | |---|---|---| | TYPESAFE API KEY / TYPESAFE KEY FILE | — | Your JEV key required | | TYPESAFE MODEL | jev-latest | | | PLANNER | auto | claude , codex , api or none . Auto: Claude when launched by Claude Code, else Codex if logged in, else Claude if installed, else API key | | PLANNER MODEL | claude-opus-5-5 / gpt-6-astra | Planner model for the chosen backend | | CLAUDE CODE EXECUTABLE | claude on PATH | Claude binary the ACP adapter drives | | MCP MINECRAFT HOME | ~/.minecraft-jev-mcp | Server jars, worlds, name registry, agent logs | | DASHBOARD PORT | 3600 | | | VIEWER BASE PORT | 3601 | One 3D-viewer port per agent | | VIEWER=0 | on | Turns off the 3D views | | MINECRAFT JAVA | auto | Java binary for managed servers | ~/.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 https://github.com/xatuke/herobrine/blob/main/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.