Skip to content
← Back

Cubehand

A survival Minecraft player run by Claude, which builds detailed houses from chat requests.

3 to 1
Model calls to answer "come here"
29 to 6
Walks to place a 40-block test ring
977
Automated tests

Players ask in chat, Claude picks the next action, and the bot's own code does the walking, digging and placing under survival rules.

1 / 6
Getting spruce logs with one obtain call: the chain is planned in code, and her status line names the step she's on
A build_structure plan going up by the water, 219 of 544 blocks in
Scaffolding she cleans up: a cobblestone pillar goes up beside a tree and comes down again
Strip mining with dig_area, 33 of about 60 blocks into a tunnel
Strip mining with dig_area, 33 of about 60 blocks into a tunnel
Checking the labelled chests for dirt; she remembers what each one held the last time she opened it
Checking the labelled chests for dirt; she remembers what each one held the last time she opened it
Replanting a sapling where a tree she chopped stood
Replanting a sapling where a tree she chopped stood
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.
Where a chat request goes, from the message to the reply Chat message Checks in code allowlist, stop, come here Quick model sorts the request Mid-size model chores, mining, storage Main model building, planning Tool loop step by step Actions walk, dig, place, craft Chat guard no commands, no slurs Reply in chat simple jobs stay on the quick model hands up calls results every line she says
Where a request goes: stops and a plain come, follow or stay are handled in code, builds and obvious work orders skip the quick model, and every line she says goes through the chat guard
How a build works, from the design guide to the checked result design_guide structure and style Plan palette, shapes, kits preview_structure renders, places nothing build_structure places the blocks Check and fix missing or turned wrong under 8 parts and no part over 150 blocks: no preview needed change the plan after seeing the pictures then two rendered views of the result go back to Claude what she gets back: the plan from two opposite corners, and a slice to see inside
How a build works. The pictures are the bot's own renderer drawing its cottage design, and a larger build is turned back until it has been previewed this way

"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.
What happens when a tool stalls, and when a tool is slow but still working A stalled tool nothing changes A slow tool still working progress 45 s with no movement, digging, item change or progress progress reported, nothing said in chat the watchdog stops it and hands Claude a report a status line goes to chat 0 s 15 s 30 s 45 s 60 s 75 s
Two kinds of quiet: a tool where nothing changes for 45 seconds is stopped and the model is told where it got stuck, and a tool that is still working gets a status line in chat after a minute

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.

If I picked it back up. Boat travel. On this protocol version the client has to move the boat itself, so it needs a supervised live test before any code.

Next project:

Urara

An Umamusume guide where every character and song page is pre-rendered, so search engines get real pages from a static host.