minecraft-agent-swarm

How the swarm is organized

Minecraft Agent Swarm is a self-improving swarm of autonomous AI agents that play Minecraft together, powered by local LLMs through Ollama with a hybrid skill system. The README says each of five bots specializes in a different area: exploring, farming, mining, building, or combat, and they coordinate through shared context and a central resource stash. The bots earn everything in-game, with no item handouts, no teleport rescues, and no scripted shortcuts that act on their behalf, so progress comes from making the agents more capable rather than cheating for them. The project was formerly called mineflayer-chatgpt and was renamed to reflect a multi-agent swarm running on local models. The bot team table lists Atlas as scout and explorer with a five hundred block leash, Flora as farmer and crafter with one hundred blocks, Forge as miner and smelter with two hundred fifty, Mason as builder with one hundred fifty, and Blade as combat and guard with three hundred. Each bot has its own personality, allowed actions, allowed skills, memory file, and leash radius, and they share a central stash of chests plus a team bulletin that shows each bot's action, position, and thought injected into every LLM prompt. The design is meant for live streaming with a Mission Control dashboard, per-bot 3D viewers, OBS overlays, text to speech, and Twitch integration.

Decision making and skills

The brain is event-driven rather than a polling loop. The README describes strategic decisions on idle every ten seconds or on goal completion, reactive decisions on hostiles or damage with a tiny prompt, a critic after every action that verifies the result, and a chat handler for messages. Each decision executes a gated action restricted to the bot's allowed skills, records success or failure, and updates memory, the team bulletin, the scoreboard, and the trajectory log. Stuck detection forces a different approach after two failed attempts at the same action, and leash enforcement warns at eighty percent of the radius and force-navigates home at one hundred fifty percent. The skill system combines hand-crafted TypeScript skills such as build_house, build_farm, build_bridge, craft_gear, strip_mine, smelt_ores, light_area, go_fishing, setup_stash, and neural_combat, with fifty-seven Voyager-style JavaScript skills run in a vm sandbox covering crafting, mining, smelting, combat, and gathering, plus dynamic skill generation at runtime that saves new skills for reuse. Freeze protection comes from watchdogs: a skill watchdog at two hundred forty seconds, an action watchdog at one hundred fifty seconds, bounded primitives for pathfinder and dig and craft, aggregate loop budgets, and fail-fast reachability for the stash. Persistent memory files record structures, deaths, ore discoveries, and skill success rates.

Setup and self-improvement

Requirements are Node.js 20 or newer, Ollama with the gpt-oss:20b model pulled, a Minecraft Java Edition server version 1.21.4 with five or more player slots, and Python 3.10 or newer for the neural combat server. Installation clones the repository, runs npm install, and installs the Python requirements. Configuration uses a dotenv file with the Minecraft host, port, usernames, version, auth mode, LLM provider, model, bot identity, multi-bot mode, and autonomy flags. The default LLM provider is local Ollama, but an OpenAI-compatible API can be used by setting the provider and supplying a base URL and an API token, with the note that the model must support JSON mode. The run starts the Minecraft server first, then npm run dev, which connects the bots, starts the neural combat server, starts the unified 3D viewer on port 3000, and starts the Mission Control dashboard on port 3010. The self-improvement loop measures and improves across sessions using a scoreboard of success rates and deaths and stash throughput, team-wide skill curation that retires broken skills, a tech-tree curriculum from real inventory, Voyager-style skill refinement, and a fine-tuning pipeline that logs trajectories and LoRA-tunes Qwen3-8B. The README also records a model history and a July 2026 three-way trial where gpt-oss:20b won on food economy, action success, and decision throughput.

Editorial conclusion

Minecraft Agent Swarm is distributed under the MIT license, and the repository's most recent commit was on 2026-08-26. The project is hosted at github.com/JesseRWeigel/minecraft-agent-swarm.