Dwinovo/minecraft-numen

Numen is an embodied agent that runs inside Minecraft. It lives in the game as a mod, continually explores the Minecraft world, makes its own decisions, and takes action to get tasks done.

What it is

Numen (Chinese: 言出法随) is a Minecraft mod that embeds an embodied AI agent directly inside the game. The agent runs as a player‑character, perceives the world, and can be driven by a large language model (LLM) through a Lua‑based API. In practice you install the mod, configure an LLM service (OpenAI, Anthropic, or any compatible API), summon a bot, and then talk to it in natural language – it will decide what to do and issue Minecraft actions (move, mine, build, interact, etc.).

Why it matters

Embodied intelligence: Unlike chat‑only bots, the agent actually manipulates the Minecraft world, giving a concrete test‑bed for research on LLM‑driven robotics and planning.
Open‑source & extensible: The mod is LGPL‑3.0 and provides a plugin system so developers can expose new Lua actions (e.g., from other mods) to the LLM.
Hybrid deployment: You can run the LLM locally via API keys, or connect the mod to an external “MCP” brain (Claude Code, Cursor, etc.) that does the inference elsewhere, saving token costs.

Who might use it

User type	What they get
Minecraft players who want a self‑driving companion that can help with building, exploring, or automating tasks.
AI researchers / hobbyists looking for a sandbox to experiment with embodied LLM agents, prompt engineering, or multi‑modal interaction (voice, text, skin customization).
Mod developers who want to let their own mods be controlled by LLMs – they can write a plugin that registers new Lua functions for the agent to call.
Educators demonstrating concepts like perception‑action loops, planning, or prompt‑driven robotics in a familiar game environment.

How to get started

Install the mod from CurseForge (search “Numen”) for the Minecraft version you use (e.g., 1.20.1‑Fabric).
Enter the game and press G (or N on newer versions) to open the control panel.
Configure a model – choose OpenAI or Anthropic, paste your API key, and optionally set a custom “personality” or skin.
Summon a bot, give it a name, and start chatting. You can type with Y, speak with V, or switch between multiple bots with R + mouse wheel.
Extend – drop a plugin into the plugins folder to expose new Lua actions (e.g., control the Touhou Little Maid mod). See the repo’s plugins directory and the website docs for templates.

Technical highlights

Three‑layer architecture:
1. Minecraft core – the agent controls a real player entity.
2. Lua API – a set of atomic actions (perception, movement, mining, building, interaction) that the LLM can call. A small Java API exists for loading skills.
3. LLM sandbox – a Lua script runs inside a sandbox, orchestrating many atomic actions in a single call.
Model‑agnostic: Supports any service that follows the OpenAI or Anthropic HTTP protocol; you just enter the endpoint URL.
MCP server mode: The mod can act as a Minecraft‑Chat‑Protocol server, letting an external AI client drive the agent, keeping inference off‑device.
Voice I/O: Optional voice input/output via the panel settings.
Multi‑agent chat: Drag avatars together to create group chats; @‑mentions direct replies.

Community & support

QQ group: 1121662678
Discord: https://discord.gg/FpDCV327vX
Official website: https://numen.dwinovo.cn (docs, architecture diagram, plugin guide)
Issue tracker: Use GitHub Issues for bugs or feature requests.

All information above is taken directly from the repository’s README.