▸ TRY IT YOURSELF

Run a self-building
AI org on your machine.

Watch the demo, then clone the repo, drop in a free Gemini key, run one command, and walk into Omo in Minecraft. Takes about 10 minutes.

▶ Watch the demo ⛏ Install & run
⛏ macOS ◆ Free Gemini key ◆ ~10 min ◆ Open source

SEE IT IN ACTION

Say one sentence. Watch the world build itself.

One continuous take: drop the HQ, speak a goal, a new wing rises block by block, an agent walks in, the wall lights up with live data.

DEMO VIDEO → coming soon. Drop videos/demo.mp4 here (or a YouTube embed) — the one-take money shot: ask → world rises → walk in → /revise → approve.

BEFORE YOU START

What you'll need

Built and tested on macOS (Apple Silicon). On a Mac, install the toolchain with one Homebrew line — the rest is automatic.

brew install openjdk@21 maven node python jq

◆ Java 21 + Maven

Runs the Paper server & builds the plugin.

◆ Node 20+

The runtime / orchestrator (tsx).

◆ Python 3.10+

The ADK + Gemini agent service.

◆ Minecraft: Java 1.21.4

The real game client — you play in it. (minecraft.net)

◆ Gemini API key — free

The brain of every agent. Get one free ↗

◆ Omo client-mod (optional)

Fabric mod for fullscreen in-world screens + voice. In the repo.

RUN IT LOCALLY

Six steps to your own Omo

Copy each block. The launcher does the heavy lifting — Paper download, plugin build, npm install, token wiring.

★ View the repo on GitHub ↗
1

Clone the repo

Grab the code and step into it.

git clone https://github.com/harrythentrepreneur/omo-minecraft.git
cd omo-minecraft
2

First-time setup

Fetches Paper, builds the plugin, installs runtime deps, and writes runtime/.env (with a synced bridge token).

./agentcraft setup
3

Add your free Gemini key

The key powers the agents and the world-architect, so it goes in two places. Paste your key in place of YOUR_KEY.

# 1) the runtime (Gemini world-architect)
echo 'GOOGLE_API_KEY=YOUR_KEY' >> runtime/.env

# 2) the ADK crew (Chief of Staff + specialists)
mkdir -p omo-agent/omo
cat > omo-agent/omo/.env <<'ENV'
GOOGLE_API_KEY=YOUR_KEY
GOOGLE_GENAI_USE_VERTEXAI=FALSE
OMO_GEMINI_MODEL=gemini-flash-latest
ENV
cp omo-agent/omo/.env omo-agent/specialist/.env
4

Install the ADK (Gemini) crew

A one-time Python venv for the adk api_server.

python3 -m venv omo-agent/.venv
omo-agent/.venv/bin/pip install google-adk
5

Start everything

Boots the ADK crew, the runtime, and the Paper server — and tails the logs. One command for the whole stack.

./agentcraft

Stop with ./agentcraft stop · re-tail with ./agentcraft logs · full restart with ./agentcraft restart.

6

Walk in & build your org

Open Minecraft Java 1.21.4 → Multiplayer → Direct Connect → localhost. Then in chat, drop the HQ and talk to the Chief of Staff:

/omo hq

Walk up to the Chief of Staff and say it out loud:

Check whether our ad spend is still paying off — and keep watch.

A new wing rises on the path, a Gemini specialist walks in, and the wall lights up with live data. Ask for a school and it builds a classroom too.

THE LAZY WAY

Or just let an AI set it up

Clone the repo, open it in Claude Code / Cursor / any terminal AI, and paste this. It walks you through every step and fixes errors as they come.

I want to run Omo Mission Control locally on macOS.
Repo: https://github.com/harrythentrepreneur/omo-minecraft
I've cloned it and I'm in the project root. Walk me through setup
ONE step at a time, waiting for me to confirm after each:

1. Check I have the prereqs (java 21, maven, node 20+, python 3.10+,
   jq, curl). For anything missing, give me the exact `brew install`.
2. Help me get a FREE Google AI Studio (Gemini) API key, then put it in
   BOTH places: append GOOGLE_API_KEY to runtime/.env (the world-architect),
   and create omo-agent/omo/.env with GOOGLE_API_KEY, GOOGLE_GENAI_USE_VERTEXAI=FALSE,
   OMO_GEMINI_MODEL=gemini-flash-latest (copy it to omo-agent/specialist/.env too).
3. Create the ADK venv: python3 -m venv omo-agent/.venv &&
   omo-agent/.venv/bin/pip install google-adk
4. Run `./agentcraft setup`, then `./agentcraft`. Watch logs/ and fix any errors.
5. Tell me how to connect my Minecraft Java 1.21.4 client to localhost,
   then what to type in-game: `/omo hq`, then talk to the Chief of Staff.

If a command fails, read the error (and `./agentcraft logs`) and fix it
before moving on. Keep replies short and tell me exactly what to run next.

IF SOMETHING'S OFF

Quick fixes

◆ Agents say “offline”

The ADK crew didn't start — check logs/adk.log and that your Gemini key is in omo-agent/omo/.env.

◆ Buildings don't appear

The world-architect needs GOOGLE_API_KEY in runtime/.env. A fallback pod still builds without it.

◆ Can't connect in-game

Wait for paper ready on :25565 in the logs, then Direct Connect to localhost.

◆ See what's running

./agentcraft status shows every service; ./agentcraft logs tails them all.

◆ No fullscreen screens

That's the optional Fabric client-mod — build it from client-mod/ and add it to your mods folder.

◆ Start fresh

./agentcraft restart does a clean full restart of the whole stack.

Full README on GitHub ↗ Back to top