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
/spotify                 → open the in-game Spotify jukebox
/mail                    → open the in-game email client

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

| Command | Description | |---------|-------------| | /claude <message> | Send a message to Claude Code | | /browser-use <task> | Run a Browser Use task | | /browser-use get-schematics <query> | Search and download schematics | | /shell <command> | Run a shell command | | /tmux-send <pane> <text> | Send text to any tmux pane | | /tmux-read <pane> | Read from any tmux pane |

Agent Villagers

| Command | Description | |---------|-------------| | /agent <name> | Spawn a villager agent (runs Claude Code) | | /agent <name> <mob> | Spawn as specific mob (wolf, pig, creeper...) | | /agent <name> --attach <pane> | Attach villager to existing tmux pane | | /despawn <name> | Remove agent and close its tmux pane | | /agent-tell <from> <to> <msg> | One agent sends a message to another | | /agent-chat <a1> <a2> <prompt> | Multi-round conversation between agents |

Code Editor (VS Code in Minecraft)

| Command | Description | |---------|-------------| | /code | Open VS Code (vscode.dev) in-game | | /code repo | Open the project repo in github.dev | | /code server | Open code-server at localhost:8080 | | /code login | Sign in to GitHub | | /code <url> | Open any URL in the browser |

Dashboard

| Command | Description | |---------|-------------| | /agents | Open agent dashboard showing all active agents |

Schematics

| Command | Description | |---------|-------------| | /build list | List schematics from Convex database | | /build <name> | Download schematic for Litematica placement |

Spotify Jukebox

| Command | Description | |---------|-------------| | /spotify | Open the in-game Spotify jukebox |

A Minecraft-styled UI that controls your Spotify via the Web API. Music discs replace album art, and the panel matches the vanilla GUI aesthetic.

• Now Playing — track / artist / album / playlist context, progress bar, play/pause/next/previous, volume slider
• SEARCH tab — query the full Spotify catalog (Enter to run)
• PLAYLISTS tab — your private + collaborative playlists; click one to drill into its tracks
• LIKED tab — your Liked Songs
• QUEUE tab — what's coming up next on Spotify
• The search field doubles as a fuzzy filter on every non-search tab (e.g. PLAYLISTS → "tlr swft")
• Clicking a track plays it; sidecar walks neighbouring tracks via Spotify Connect — no focus stolen from Minecraft

Requires Spotify Premium for playback control via the Web API.

Mailbox

| Command | Description | |---------|-------------| | /mail | Open the in-game email client |

A Minecraft-styled email client that reads your Gmail (or any IMAP inbox) and lets you browse, read, reply, and compose without leaving the game. Written books stand in for email icons; a parchment-warm accent replaces Spotify-green.

• Inbox — 25 most recent, with sender / subject / relative date. Auto-refreshes every 30 s.
• Detail view — click a row → full plain-text body (HTML stripped). URLs are underlined and clickable (opens in your browser with MC's standard confirm-prompt).
• Actions — Mark read/unread, Archive (moves to All Mail), Trash, Reply.
• Compose — new message from the inbox toolbar, or prefilled as a quoted reply from the detail view.
• Attachments — listed below the body when present. Click a row to save to ~/Downloads/mailbox/; the chat log shows a clickable path that opens the file in Finder.
• Fuzzy filter — the persistent search bar filters the loaded rows locally (same subsequence matcher as the Spotify tabs).
• In-process — IMAP/SMTP run inside the mod via bundled Jakarta Mail. No Python sidecar needed for /mail.

Auth: app password, not OAuth. See Setup Guide → Step 6 below.

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

| Tool | Version | Install | |------|---------|---------| | Java | 21+ | brew install openjdk@21 | | tmux | 3.x+ | brew install tmux | | Python | 3.12+ | brew install [email protected] | | Node.js | 18+ | brew install node | | smux | latest | auto-installed by minecraft-code init |

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

5. Spotify (optional, for /spotify)

Spotify Premium is required for playback control via the Web API.

1. Go to developer.spotify.com/dashboard → Create App
2. Add this exact Redirect URI in the app's settings:

   http://127.0.0.1:8765/spotify/auth/callback

3. Copy the Client ID and Client Secret into your .env:

   SPOTIFY_CLIENT_ID=...
   SPOTIFY_CLIENT_SECRET=...
   SPOTIFY_REDIRECT_URI=http://127.0.0.1:8765/spotify/auth/callback

4. In Minecraft, run /spotify and click Sign in to Spotify — your browser opens, you approve, the GUI auto-detects when the token is saved (~1s). The token persists in sidecar/.spotify-token.json and refreshes itself.

6. Mail (optional, for /mail)

The mail client uses IMAP + SMTP via an app password, not OAuth. Works with Gmail, Outlook, iCloud, Fastmail, or any IMAP host — defaults assume Gmail.

1. Turn on 2-Step Verification on your Google account if it isn't already: myaccount.google.com/signinoptions/two-step-verification
2. Generate an app password: myaccount.google.com/apppasswords → enter any name (e.g. minecraft-mail) → Create → copy the 16-char password.
3. Add to .env:

   [email protected]
   GMAIL_APP_PASSWORD=xxxx xxxx xxxx xxxx

4. In Minecraft, run /mail. The mod warms the IMAP connection and prefetches the first 25 envelopes at launch, and keeps the connection alive with a periodic NOOP, so the inbox renders near-instantly on every open.

Different provider? Override any of these in .env:

IMAP_HOST=imap.yourhost.com        # default: imap.gmail.com
SMTP_HOST=smtp.yourhost.com        # default: smtp.gmail.com
SMTP_PORT=587                       # default: 587
MAIL_ARCHIVE_FOLDER=[Gmail]/All Mail  # where Archive sends messages
MAIL_TRASH_FOLDER=[Gmail]/Trash       # where Trash sends messages
MAIL_POLL_SECONDS=1                   # inbox refresh cadence while /mail is open (clamped 1–300)

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