GuiaIA

What if Minecraft felt like a world you could share with an AI?

An open-source project to build a real AI companion for Minecraft —
and the tools for AI agents to observe, understand and improve the worlds we play in.

🇪🇸 Leer en español  ·  Roadmap  ·  Join the conversation  ·  Contribute

[!IMPORTANT] This is an early developer preview, not a playable AI companion yet. The public main branch provides a working read-only MCP gateway, local Minecraft status queries, deterministic mission proposals and safety checks. The in-game companion, world vision and autonomous development workflows are in development. We would rather show what's real than fake an impressive demo.

✨ The vision

One world. Two players. One of them is AI.

Imagine telling your companion:

“GuiaIA, come explore this cave with me.”

“Help me collect the materials for our base.”

“Why is this area lagging? Investigate it and test a fix safely.”

Not a chatbot pretending it can see Minecraft. Not an agent blindly sending server commands. The goal is a companion that can act inside the game, grounded in real observations, while a separate development agent can test and improve your world without risking your saves.

These examples describe where we're going, not gameplay already shipped.

🚦 What actually works today?

The current Python preview has no paid AI dependency, runs without a GPU and does not install mods or touch a world save. The Fabric prototype lives separately in feature/world-observer-p0; it is not part of the current alpha release.

⚡ Try it in 60 seconds

No Minecraft server, API key, game account or AI subscription needed. Just Python 3.11+ and Git.

git clone https://github.com/iagorobo24-hub/GuiaIA.git
cd GuiaIA

# Run a real diagnostic against the included synthetic example
PYTHONPATH=src python3 - <<'PY'
import json
from guiaia.observer import SnapshotObserver
from guiaia.tools import ToolRegistry

tools = ToolRegistry(SnapshotObserver("examples/synthetic_world.json"))
print(json.dumps(tools.invoke("guia_diagnose", {}), indent=2))
PY

You'll get a structured diagnosis, including the observed tick-time warning, low reported TPS, high entity count, and suggested checks — with "production_changes": 0. The sample is synthetic, not a claim about a real server.

Want to connect it to your AI client? Start the MCP stdio server:

PYTHONPATH=src python3 -m guiaia.mcp --snapshot examples/synthetic_world.json

This command waits for an MCP client on stdin/stdout; it does not launch a graphical app or a Minecraft bot. See the MCP client setup and smoke test.

PYTHONPATH=src python3 -m guiaia.mcp \
  --rcon-password-file /absolute/private/path/rcon.secret \
  --rcon-port 25575

🏗️ Designed to observe before it acts

flowchart LR
    A["You + your local MCP client"] --> B["GuiaIA MCP gateway"]
    B --> C["Read-only world data"]
    B --> D["Bounded mission proposals"]
    C --> E["Sanitized metrics snapshot"]
    C --> F["Local RCON: fixed queries"]
    D --> G["No world execution in v0.1"]
    H["Experimental Fabric observer"] -. "future integration" .-> C

Our long-term rule is straightforward:

Observe → plan → check permissions → test in an isolated world → verify → request approval before production changes.

Model output is never permission to run arbitrary RCON commands, execute shell code or modify someone's world. Read the architecture · Security model.

🗺️ Roadmap: from tools to a teammate

The first target for the Fabric side is Minecraft Java 1.21.1. Compatibility with other versions and modpacks must be verified, not assumed. Find the full development plan, Fabric prototype, and research into related projects.

🤝 Help us make this real

We're building in public — and early contributors can genuinely shape what GuiaIA becomes.

PYTHONPATH=src python3 -m unittest discover -s tests -v
python3 -m compileall -q src tests