SkillFoxx

Minecraft Agent Harness CLI

A CLI that runs LLM agents in Minecraft via Mineflayer: mining, building, combat, chat, sessions that survive restarts

  • 214 ★ on the repository
  • Last commit
  • MIT
CLI

Extended access

Why this level

  • The agent runs commands in its shell (Docker, E2B or a local folder) and in the game
  • Model provider API keys come from `.env` and token use grows with the number of agents
  • Bots on third-party servers may break rules, so join only with the owner's consent
All reasons and checks

yc-software/minecraft-agent-harnessAuthor:yc-software

Install

Manual install

npm ci

The first quick-start step: then copy `.env.example` to `.env`, `npm run server` and `npm start -- --objective "..."`.

Access and checks

How we review

Extended accessThe tool runs code or makes network calls and only reads external data.

  • The agent runs commands in its shell (Docker, E2B or a local folder) and in the game
  • Model provider API keys come from `.env` and token use grows with the number of agents
  • Bots on third-party servers may break rules, so join only with the owner's consent

This is third-party code. Review the repository files before installing.

What it does

The harness connects a model to a Minecraft server and gives it a task. The agent plays like a regular player through Mineflayer: it walks, mines, crafts, builds, fights and chats. pi manages the model session, so Claude, GPT, Gemini, OpenRouter and any endpoint speaking the OpenAI Responses API work. State lives in `.agent-state/<name>/`, and a stopped agent under the same name carries on where it stopped. Each agent has a shell in Docker, E2B or a plain folder where it keeps notes and writes scripts that call its own game tools. Teams are described in a single JSON file with direct messages between agents and an optional shared machine, and vision is experimental. According to the README it ran Bed Wars matches and a survival server with 50 agents.

Who it is for. Researchers and developers of game agents who test models in the open world of Minecraft and want team interaction without writing their own control loop.

Good fit when

  • You want to test how a model builds a shelter or gathers resources from a one-phrase goal
  • Several agents play as a team, message each other and share a machine
  • An experiment lasts hours and an agent must continue by itself after the process crashes
  • You want to compare Claude, GPT and Gemini on the same in-game task

Not a fit when

  • A code development helper is needed: the project is built for the game and unrelated to repositories
  • You have no Minecraft server of your own and connecting bots to someone else's needs the owner's consent
  • A stable game version other than 1.21.6 is needed: the bundled Paper server is built for that one

Example request

Build a small wooden shelter near spawn and say in chat when you are done.

Limitations

Node.js 22.19 or newer, an API key from some model provider and a Minecraft server are required: for development a bundled Paper 1.21.6 in offline mode is included and needs Java 21. The default model in the README is named `GPT-6.1 Terra`, and other providers are set in `docs/configuration.md`. An agent shell in Docker or E2B needs the matching environment. Vision is marked experimental in the README. Run agents only on servers where bots are allowed. The latest commit in the repository is from October 2026.

How to disable. Stop the agent with Ctrl+C. The state sits in `.agent-state/` and is deleted along with that folder, Docker containers for shells are stopped separately, and the bundled server closes when `npm run server` ends.

FAQ

How do I start an agent?

Run `npm ci`, fill in `.env`, start `npm run server`, then `npm start -- --objective "..."` with the goal in quotes. You can join and watch from Minecraft 1.21.6 at `localhost:25565`.

Which models are supported?

Claude, GPT, Gemini, OpenRouter and any endpoint that speaks the OpenAI Responses API. The list and switching are described in `docs/configuration.md`.

What happens after a restart?

An agent started under the same name continues from the saved state in `.agent-state/<name>/`: notes, session and memory stay.

Can I run a team of agents?

Yes, teams are described in a single JSON file, agents send each other direct messages and a shared machine is optional. The README mentions a server with 50 agents.

Where does an agent keep notes and scripts?

In its own shell: Docker, E2B or a plain local folder. The agent scripts call its game tools.

Discussion

No questions or reviews yet.

CLI tools
Official

The Harness MCP server: one agent starts other Claude Code and Codex sessions on your computer, waits for them, reads their answers and closes them

MCP serverBroad access1.5K

LocalHarness runs agents on your local models through vLLM, llama.cpp, Ollama or LM Studio, with YAML agents and a permission gate

CLIBroad access69

mi is agentic coding in 30 lines: a loop, two tools and a model; works with any OpenAI-compatible API and runs in Docker.

CLIBroad access105

An open coding agent for the terminal, browser and desktop that works with models from OpenAI and Claude to Ollama

CLIBroad access364

multi-agents runs a team of coding agents on a task and measures whether it beat a single agent and what it cost.

CLIExtended access158

Agent Mesh links agents, containers and laptops into a private network where nodes publish tools and models over MCP

CLIExtended access1.2K

README in short

The README explains that the project connects an LLM to a Minecraft server, lists capabilities (models, sessions, shell, teams, vision), gives a three-step quick start and links to configuration, tools and the Bed Wars example.

README badge

Report a problem