minecraft-code

Turn Minecraft into a coding workstation. Spawn Claude Code as a villager, open VS Code in-game, find schematics on the web, and build them in your world — all from chat.

/agent alex              → spawn Claude villager
/agent rex wolf          → spawn wolf agent
/claude hello            → talk to Claude Code
/browser-use get-schematics castle → download builds
/build 27283             → place schematic via Litematica
/agent-tell alex shawn "review this" → agents talk to each other

Quick Start

# Install
npm install -g @reaganhsu/minecraft-code

# Check prerequisites
minecraft-code doctor

# Set up everything (venv, mod build, dependencies)
minecraft-code init

# Launch (tmux + sidecar + Claude Code + Minecraft)
minecraft-code start

How It Works

The mod connects to tmux terminal panes via smux/tmux-bridge. Each command you type in Minecraft sends text to a named tmux pane and reads the output back. The mod doesn't know or care what's running in each pane.

Minecraft Chat  →  TmuxBridge.java  →  tmux-bridge CLI  →  tmux pane
     ↓                                                         ↓
  /claude hello     types "hello" into        Claude Code responds
     ↓              the "claude" pane              ↓
  Shows response    reads output back         "Hello! How can I help?"
  in Minecraft chat

Architecture

tmux session "minecraft-code"
┌──────────────┬──────────────┐
│  sidecar     │  claude      │
│  (FastAPI)   │  (lfg)       │
├──────────────┼──────────────┤
│  minecraft   │  browser     │
│  (gradlew)   │  (repl)      │
├──────────────┤              │
│  shell       │              │
│  (bash)      │              │
└──────────────┴──────────────┘

+ "agents" window (created by /agent command)
┌──────────────┬──────────────┐
│  alex        │  shawn       │
│  (lfg)       │  (lfg)       │
└──────────────┴──────────────┘

Commands

Terminal Commands

Agent Villagers

Code Editor (VS Code in Minecraft)

Dashboard

Schematics

Agent Villagers

Spawn AI agents as Minecraft mobs that follow you around:

/agent alex              → librarian villager named "alex"
/agent rex wolf          → wolf named "rex"
/agent scout creeper     → creeper named "scout"

Each agent:

• Follows you (3-6 block distance, teleports if >16 blocks away)
• Shows output as floating text above its head (with ANSI color rendering)
• Right-click to open a scrollable chat GUI
• Dies -> tmux pane closes + custom death sound
• Custom spawn sounds per name (alex, shawn, magnus, aitor, etc.)

Agents can talk to each other:

/agent-tell alex shawn "tell shawn to review the code"
/agent-chat alex shawn "debate rust vs python"

Schematics Pipeline

Download schematics from the web and place them in Minecraft:

/browser-use get-schematics castle     → Browser Use finds and downloads
                                       → Saves to Convex database
/build list                            → Shows available schematics
/build castle                          → Downloads from Convex
                                       → Load in Litematica (M+C) to place

Supports:

• minecraft-schematics.com (default, skips non-free)
• planetminecraft.com (get-schematics castle --site planet)

Prerequisites

Run minecraft-code doctor to check everything.

Setup Guide

1. Browser Use API Key (required for schematic downloading)

1. Go to cloud.browser-use.com
2. Sign up and create an API key
3. (Optional) Create a browser profile for persistent sessions — save the profile ID

2. Convex Database (required for schematic storage)

1. Install Convex: npm install convex
2. Set up a new project: npx convex dev in the frontend/ directory
3. This creates the schematic storage tables and functions
4. Note your Convex deployment URL (e.g., https://your-project.convex.cloud)

3. Environment Variables

Create a .env file in the project root:

# Required for schematic downloading
BROWSER_USE_API_KEY=bu_your_key_here

# Optional — for voice transcription
OPENAI_API_KEY=sk_your_key_here

4. Convex Configuration

If you're using your own Convex deployment, update the CONVEX_URL in:

• sidecar/browser_repl.py
• fabric-mod/src/main/java/com/minecraftuse/commands/BuildCommand.java
• fabric-mod/src/main/java/com/minecraftuse/catalog/CatalogIndex.java

CLI

minecraft-code doctor    # Check prerequisites
minecraft-code init      # Set up everything
minecraft-code start     # Launch tmux environment + Minecraft
minecraft-code stop      # Kill tmux session

Development

task build          # Build the Fabric mod
task test           # Run all tests (Java + Python)
task test:python    # Python tests only (50 tests)
task lint           # Run ruff linter
task mc:install     # Copy mod JAR to mods folder
task up             # Start tmux dev environment
task down           # Kill tmux session

Tech Stack

• Minecraft Mod: Fabric 1.21.1, Java 21, Fabric API 0.107.0
• Terminal Bridge: smux/tmux-bridge
• Sidecar: Python 3.12, FastAPI, Browser Use Cloud SDK
• Database: Convex (schematic storage)
• Schematic Placement: Litematica
• Frontend: React 19, Vite, Convex

Supported Mob Types

villager, wolf, cat, pig, cow, sheep, chicken, fox, parrot, rabbit, horse, donkey, llama, goat, bee, axolotl, frog, camel, sniffer, allay, iron_golem, snow_golem, zombie, skeleton, creeper, enderman

License

MIT