Cubehand
A survival Minecraft player run by Claude, which builds detailed houses from chat requests.
Players ask in chat, Claude picks the next action, and the bot's own code does the walking, digging and placing under survival rules.



- Built with
- JavaScript, Node 20, Mineflayer, mineflayer-pathfinder, Anthropic SDK, node:test
- Features
- Chat requests, House and structure building, Build previews, Mining and digging, Crafting and smelting, Chest storage, Farming and animals, Fighting, Standing jobs, Memory across restarts, Lessons and skills
Overview
Cubehand is a Node.js bot that joins a private Minecraft Java server as its own survival player. Players talk to it in chat, and it builds houses, mines, crafts, farms, stores things and fights, all under survival rules: it only builds with blocks it carries, gets hungry, can die and only sees the chunks around it.
I designed and built it, and tested it with friends on our server. Claude, through the Anthropic API, decides what to do, and the bot's code decides how: walking, digging, placing blocks in order, crafting. It's plain JavaScript on Mineflayer with a manual tool loop, 53 tools and 977 tests, and no build step.
Constraints
- Survival rules. She only builds with blocks she carries, gets hungry, can die and only sees the chunks around her, so every plan has to start from her inventory.
- The server runs Minecraft 26.3 and Mineflayer only speaks 26.1. She connects as 26.1 through ViaProxy, and has to send the tick_end packet real clients send, or the server kicks her a second after spawning.
- Every model call costs money and a round trip. Each call rereads the whole conversation, so the work is shaped to need as few calls as possible.
- The server is in offline mode. A name proves nothing, so an optional whispered passphrase decides who she takes orders from.
- Anyone can write text she reads. Chat, signs and name tags from players off the allowlist reach the model as information, never as instructions.
Under the interface
Decisions
- Claude decides what, code decides how. The model never works out block-by-block geometry. build_house and the shapes do that, so builds are exact and cheap.
- A manual tool loop, not the SDK's tool runner. I need control between steps for step limits, time limits, stop and mid-job changes.
- The right model for each job. A quick model takes simple jobs and hands the rest up: chores to a mid-size model, building and planning to the main one.
- A fresh conversation per job, with memory in files. Cost per job stays bounded, and the tools and system prompt sit in a one-hour cache so a job doesn't pay to cache them again.
- One call for a whole job. obtain plans and runs the chain to get an item, and dig_area takes a whole box, where each used to be a model round trip per step.
- Look before building. A build of 8 or more parts is turned back until its plan has been rendered, so she sees the picture before placing a block.
- Hold a job, don't restart it. Low health or a dropped connection stops only the running tool, so the model keeps what it has done and hears what happened.
- Safety in code, not only in the prompt. Protected blocks, the allowlist, the chat guard and the stop command all work without a model call.
"Come here" went from three model calls to one. The sorting became the quick model's own first step, and the last action and the reply now come in one response.
Challenges
- Connecting at all: the server kicked the bot a second after spawning until it sent the tick_end packet that real clients send every tick.
- The pathfinder's blind spots: it treats doors as walls, walks across the tops of ladder shafts and sees powder snow as air, and each one needed its own fix in the movement layer.
- Standing frozen: tools now report progress, a watchdog stops one that has stalled, and a status line goes to chat after a minute of quiet.
- Building blind: planning 3D coordinates in text gave flat boxes, floating roofs and backwards stairs, until she could render a plan to a picture first.
- Instructions arriving in pieces: players change a build mid-job, so changes are delivered between steps and tools about to act on the old plan are skipped.
- Enchanted tools: every dig threw before it started because the library expected enchantments as a list, so the bot now works out dig time itself.
Logs from one evening showed the model thinking for about 14 minutes, and 12 silent gaps of over a minute, 37 minutes in total, mostly inside long tools.
Outcomes
3 to 1
Model calls for "come here". The sorting is the quick model's own first step, and the last action and the reply come in one response.
From the changelog entry for 15 Nov 2026.
35 to 78 of 136
Hand-ups that skip the quick model, after build fixes, tunnel work and obvious work orders started on a bigger model.
Counted over the logged jobs in jobs.jsonl, 17 Nov 2026.
29 to 6
Walks needed to place a test ring of 40 wall blocks, once build_structure started placing the block closest to where she stands.
Test ring, 15 Nov 2026.
6.75 s to 0.85 s
Breaking deepslate diamond ore with a diamond pickaxe. The 26.1 data gave ores a tool-tier tag as their material, so they broke at bare-hand speed.
Measured on the server, 15 Nov 2026.
977
Automated tests on Node's own test runner: about 20,200 lines of tests against 26,700 lines of source.
Counted for the project notes, November 2026.
Takeaways
- Put rules in code, not only in the prompt. Stop words, protected blocks and the chat guard work without a model call.
- Fewer, bigger tools. Every call is a round trip that rereads the conversation, so one obtain call beat a chain of chop, craft and mine.
- A model can't check what it can't see. Rendering the plan first caught floating roofs and backwards stairs before a block was placed.
- Log first, then fix. The silent gaps, the refusals and the lost corrections all showed up in the job log.

