Repolode
Submit
yc-software

yc-software/minecraft-agent-harness

Runs LLM agents as Minecraft players through Mineflayer, with persistent sessions, per-agent shell sandboxes and multi-agent teams.

View on GitHub
Stars
158
Forks
16
Open issues
1
Last commit
9 days ago

What is it?

minecraft-agent-harness connects a language model to a Minecraft server so it can play like a regular player. Actions such as walking, mining, crafting, building, fighting and chatting go through Mineflayer, and the model session is handled by pi. Supported model providers include Claude, GPT, Gemini, OpenRouter, and any endpoint that speaks the OpenAI Responses API.

An agent's state is saved under a per-name folder, so restarting an agent with the same name resumes its session. Each agent gets a shell backed by E2B, Docker or a local folder, where it can keep notes and write scripts that call its game tools. Teams of agents are defined in a single JSON file, can send direct messages to each other, and can optionally share a machine.

The project includes a dev Paper 1.21.6 server, a Docker Compose setup, and a Bed Wars example with rules and a referee. Vision support is available as an experimental option.

Key features

  • 01Connects Claude, GPT, Gemini, OpenRouter or any OpenAI Responses-compatible endpoint.
  • 02Resumes an agent's session after restart when it uses the same name.
  • 03Gives each agent a shell via E2B, Docker or a local folder.
  • 04Defines multi-agent teams in one JSON file with direct messages between agents.
  • 05Includes a Docker Compose setup with a Paper server.

Use cases

  • Experimenting with LLM agents that act inside a Minecraft world.
  • Running a team of AI players that coordinate through chat.
  • Testing agent behavior in a game such as Bed Wars with a referee.
  • Studying how agents use shell sandboxes to write scripts for game tools.

Quick start

  1. 1

    Install dependencies

    npm ci
  2. 2

    Copy the env file and add your model provider API key

    cp .env.example .env
  3. 3

    Start the dev Minecraft server (needs Java 21)

    npm run server
  4. 4

    In a second terminal, start an agent with an objective

    npm start -- --objective "Gather wood and build a small shelter near spawn"

Things to know

  • Requires Node 22.19+, an API key from a model provider, and a Minecraft server.
  • By default the agent's shell is a local folder where commands run as your user unless Docker or E2B is available or you pass --sandbox none.
  • Vision support is experimental.
  • The project is young with 100 stars, so expect rough edges.

In collections

Open-source AI agent frameworks & apps

Topics

#ai-agents#llm#minecraft#mineflayer#multi-agent#sandbox#agent-harness

FAQ

What is minecraft-agent-harness?
Runs LLM agents as Minecraft players through Mineflayer, with persistent sessions, per-agent shell sandboxes and multi-agent teams. minecraft-agent-harness connects a language model to a Minecraft server so it can play like a regular player. Actions such as walking, mining, crafting, building, fighting and chatting go through Mineflayer, and the model session is handled by pi. Supported model providers include Claude, GPT, Gemini, OpenRouter, and any endpoint that speaks the OpenAI Responses API.
Is minecraft-agent-harness free to use? What license does it have?
minecraft-agent-harness is open source under the MIT license. Check the license terms before using it in commercial products.
Is minecraft-agent-harness still maintained?
Actively maintained. The last commit to minecraft-agent-harness was on Oct 29, 2026.
What can I use minecraft-agent-harness for?
Experimenting with LLM agents that act inside a Minecraft world. Running a team of AI players that coordinate through chat. Testing agent behavior in a game such as Bed Wars with a referee. Studying how agents use shell sandboxes to write scripts for game tools.
How do I install minecraft-agent-harness?
Install dependencies: npm ci Copy the env file and add your model provider API key: cp .env.example .env Start the dev Minecraft server (needs Java 21): npm run server In a second terminal, start an agent with an objective: npm start -- --objective "Gather wood and build a small shelter near spawn"
Where can I get minecraft-agent-harness?
The source code and installation instructions are on GitHub: https://github.com/yc-software/minecraft-agent-harness

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects