{"slug": "show-hn-herobrine-minecraft-buddies-using-jev", "title": "Show HN: Herobrine – Minecraft buddies using jev", "summary": "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.", "body_md": "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.\n\nUse it two ways:\n\n- **As an MCP server** inside Claude Code or Codex — \"start a world and spawn a bodyguard for me\".\n- **As a CLI** —`herobrine up --world play` ,`herobrine spawn --persona \"my bodyguard\"` ,`herobrine tell Cedar \"bring me 5 logs\"` .\n\nBoth drive the same core; the CLI also works against the MCP instance while Claude Code has it open.\n\nAgents have no fixed roles. Each one has three free-text fields, and the user can change any of them at any time:\n\n| Field | Examples | \n|---|---|\n| **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\" | \n| **long_term_goal** : an objective it works toward over time | \"get us full iron gear\", \"build a base by the river\" | \n| **task** : what to do right now | \"collect 10 logs\", \"make a stone pickaxe\", \"come here\", \"bring me 5 cobblestone\" | \n\nWith 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**.\n\nEach 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.\n\nTwo models with clearly separated jobs:\n\n- **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:\n  - **Claude Code** → an ACP session (`claude-code-acp` driving your installed`claude` ) with**Opus 5.5**\n  - **Codex** →`codex mcp-server` (`codex` /`codex-reply` threads) with**GPT-6 Astra**\n  - or an API key (`ANTHROPIC_API_KEY` ,`OPENROUTER_API_KEY` ,`OPENAI_API_KEY` )\nOne persistent session per agent, so it remembers the conversation.\n- **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.\n\n```\nplayer chat / dashboard / MCP text ──▶ planner ──▶ TaskSpec {kind, items, recipient, location, entity, until} + reply\n                                                     │\n                 world memory ◀── observe ──▶ action menu ──▶ JEV picks one ──▶ Mineflayer executes (bounded)\n                                                     │\n                                       predicates verify completion (inventory / delivered / arrived / killed / built)\n                                       planner reviews \"judged\"/\"ongoing\" tasks, budgets and repeated failures\n```\n\n- **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.\n- **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.\n- **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\").\n- **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.\n\nRequirements: 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.\n\n```\ngit clone git@github.com:xatuke/herobrine.git && cd herobrine\nnpm install\nnpm link                      # puts `herobrine` on your PATH (optional)\nherobrine config set key <TYPESAFE_KEY>    # or: config set key-file /path/to/keyfile\nherobrine up --world play --difficulty peaceful   # daemon + world (asks you to accept the Minecraft EULA)\nherobrine spawn --world play --persona \"a friendly survival companion\" --goal \"get us iron gear\" --owner YourName\nherobrine tell Cedar \"bring me 5 logs\"            # planner interprets it, agent replies\nherobrine chat Cedar                              # interactive conversation\nherobrine status                                  # everything at a glance\nherobrine logs Cedar -f                           # follow task / chat / planner events\nherobrine actions Cedar                           # the menu JEV is choosing from right now\nherobrine cmd play \"time set day\"                 # server console\nherobrine down                                    # stop agents, worlds and the daemon\n```\n\n`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.\n\n```\nclaude mcp add herobrine -e TYPESAFE_API_KEY=your_key -- node /absolute/path/to/herobrine/src/server.mjs\n[mcp_servers.herobrine]\ncommand = \"node\"\nargs = [\"/absolute/path/to/herobrine/src/server.mjs\"]\nenv = { TYPESAFE_API_KEY = \"your_key\" }\ntool_timeout_sec = 300   # first start_server downloads the jar and generates a world\n```\n\n`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.\n\n- Toward Claude Code / Codex it is an **MCP server** (that's what you add, and what exposes the tools).\n- 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).\n- The CLI talks plain HTTP to the same process.\n\nJust talk to Claude or Codex:\n\nStart a peaceful survival world and spawn two agents. One should be my bodyguard; the other should get us iron tools.\n\nTell Cedar to bring me 10 logs.\n\nMake Flake act like a lazy farmer who complains a lot.\n\n**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.\n\n| Tool | Purpose | \n|---|---|\n| `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) | \n| `spawn_agent` | Join a managed server, or any offline-mode server or LAN world by `host` /`port` , with persona/goal/task | \n| `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` | \n| `planner_status` | Active planner backend/model, call stats, and the TaskSpec schema | \n| `agent_status` ,`agent_events` ,`read_chat` | See what agents are doing and what players said | \n| `pause_agent` /`resume_agent` /`stop_agent` | Control | \n| `agent_say` | Say something in game chat through an agent | \n| `list_actions` /`run_action` | See the current action menu, or run one step directly without JEV | \n| `open_dashboard` | Get the dashboard URL | \n\n| Env | Default |  | \n|---|---|---|\n| `TYPESAFE_API_KEY` /`TYPESAFE_KEY_FILE` | — | Your JEV key (required) | \n| `TYPESAFE_MODEL` | `jev-latest` |  | \n| `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 | \n| `PLANNER_MODEL` | `claude-opus-5-5` /`gpt-6-astra` | Planner model for the chosen backend | \n| `CLAUDE_CODE_EXECUTABLE` | `claude` on PATH | Claude binary the ACP adapter drives | \n| `MCP_MINECRAFT_HOME` | `~/.minecraft-jev-mcp` | Server jars, worlds, name registry, agent logs | \n| `DASHBOARD_PORT` | `3600` |  | \n| `VIEWER_BASE_PORT` | `3601` | One 3D-viewer port per agent | \n| `VIEWER=0` | on | Turns off the 3D views | \n| `MINECRAFT_JAVA` | auto | Java binary for managed servers | \n\n`~/.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).\n\n- **Offline-mode servers only.** Agents join as offline players. Online-mode (Microsoft-authenticated) servers aren't supported.\n- **Menu-based control.** JEV chooses from concrete actions and Mineflayer does the pathfinding. Agents don't see screenshots and don't press individual keys.\n- **Free-form building is basic.** Agents can place blocks around themselves and pillar up, but there's no blueprint builder yet.\n- **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.", "url": "https://wpnews.pro/news/show-hn-herobrine-minecraft-buddies-using-jev", "canonical_source": "https://github.com/xatuke/herobrine", "published_at": "2026-09-25 11:26:15+00:00", "updated_at": "2026-09-25 11:30:01.386392+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "large-language-models", "developer-tools"], "entities": ["Herobrine", "Mineflayer", "TypeSafe", "JEV", "Claude Code", "Codex", "Claude Opus 5.5", "GPT-6 Astra"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-herobrine-minecraft-buddies-using-jev", "markdown": "https://wpnews.pro/news/show-hn-herobrine-minecraft-buddies-using-jev.md", "text": "https://wpnews.pro/news/show-hn-herobrine-minecraft-buddies-using-jev.txt", "jsonld": "https://wpnews.pro/news/show-hn-herobrine-minecraft-buddies-using-jev.jsonld"}}