‹ Projects

minecraft-sidecar

A standalone Node.js sidecar that wraps a Minecraft Java server client in a clean WebSocket JSON protocol — events out, actions in. Any controller (LLM, scripted automation, dashboard) can drive it without touching Mineflayer directly.

Released Node.js · MIT Game-server automation Protocol layer

Origin

Built as the control-plane layer for an internal experiment in driving Minecraft clients from external AI agents. The interesting question was not “can an LLM play Minecraft” — it was “what is the clean separation between the agent that decides and the bot that does”.

The sidecar is the answer: a process whose only job is to be a controllable Minecraft client. The controller speaks JSON over WebSocket and never has to learn Mineflayer's API. Extracted from the larger experiment because the protocol layer is the genuinely reusable piece.

What it does

Mineflayer bot

Connects to a Minecraft Java server (1.8 through 1.20.x, offline or Microsoft auth) and keeps the connection alive with exponential-backoff reconnect, capped at five minutes.

WebSocket bridge

Listens on a configurable port. Events stream out continuously as JSON envelopes; controllers send action requests and receive results keyed by request id. One bridge can serve multiple connected controllers.

Action vocabulary

Movement, mining, crafting, chat, inventory management, and higher-level routines — vein-mine (BFS over connected ore blocks), auto-eat (best-food selection), find-and-mine (search, pathfind, dig), smart-flee, kill-aura. Each action returns a structured result.

Pathfinding

mineflayer-pathfinder integrated as the default movement layer, with goal timeout and cleanup baked in so a stuck pathfind cannot deadlock the bot.

The protocol

Three message shapes. Action requests carry a controller-supplied id; the matching result envelope quotes it back. Events stream out as they happen.

// Controller -> sidecar
{ "type": "action", "id": "abc",
  "action": "mine_ore", "args": { "ore": "iron" } }

// Sidecar -> controller (when the action completes)
{ "type": "action_result", "id": "abc",
  "result": { "mined": 8, "block_type": "iron_ore" } }

// Sidecar -> controller (events stream)
{ "type": "event", "event": "chat",
  "data": { "username": "Player", "message": "follow me" },
  "timestamp": "2026-05-31T19:14:23Z" }

Why it is public

The interface, not the AI brain, is the reusable artefact. The same sidecar pairs with a Claude-driven controller, a hand-rolled state machine, a remote dashboard, or anything else — and the bot itself does not change.

Releasing the sidecar separately keeps the controller pluggable. The next person wanting to drive a Minecraft world from outside does not need to fork a larger experiment to do it.

minecraft-sidecar on GitHub

Source, the documented WebSocket protocol, and a runnable example.

View repository All projects