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 python@3.12`
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)

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

2. Convex Database (required for schematic storage)

Install Convex: npm install convex
Set up a new project: npx convex dev in the frontend/ directory
This creates the schematic storage tables and functions
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.

Go to developer.spotify.com/dashboard → Create App
Add this exact Redirect URI in the app's settings:
```
http://127.0.0.1:8765/spotify/auth/callback
```

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

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.

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

Add to .env:

GMAIL_ADDRESS=you@gmail.com
GMAIL_APP_PASSWORD=xxxx xxxx xxxx xxxx

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

Name		Name	Last commit message	Last commit date
Latest commit History 131 Commits
bin		bin
fabric-mod		fabric-mod
frontend		frontend
lib		lib
sidecar		sidecar
.env.example		.env.example
.gitignore		.gitignore
.impeccable.md		.impeccable.md
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
Taskfile.yml		Taskfile.yml
package.json		package.json
run.sh		run.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

minecraft-code

Quick Start

How It Works

Architecture

Commands

Terminal Commands

Agent Villagers

Code Editor (VS Code in Minecraft)

Dashboard

Schematics

Spotify Jukebox

Mailbox

Agent Villagers

Schematics Pipeline

Prerequisites

Setup Guide

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

2. Convex Database (required for schematic storage)

3. Environment Variables

4. Convex Configuration

5. Spotify (optional, for `/spotify`)

6. Mail (optional, for `/mail`)

CLI

Development

Tech Stack

Supported Mob Types

License

About

Uh oh!

Releases 1

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

minecraft-code

Quick Start

How It Works

Architecture

Commands

Terminal Commands

Agent Villagers

Code Editor (VS Code in Minecraft)

Dashboard

Schematics

Spotify Jukebox

Mailbox

Agent Villagers

Schematics Pipeline

Prerequisites

Setup Guide

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

2. Convex Database (required for schematic storage)

3. Environment Variables

4. Convex Configuration

5. Spotify (optional, for /spotify)

6. Mail (optional, for /mail)

CLI

Development

Tech Stack

Supported Mob Types

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

5. Spotify (optional, for `/spotify`)

6. Mail (optional, for `/mail`)

Packages