Nexa AI Chat

Nexa AI (Minecraft Mod + Paper Plugin)

[!NOTE] This page includes detailed information about the mod/plugin. If it feels too much, you can skip straight to using it. Just install the mod/plugin and run the command /nexa <message> to get started right away.

Nexa AI adds an AI agent into Minecraft.

• Works as a Fabric / Forge / NeoForge mod (clients + servers)
• Also available as a Paper plugin at here: Plugin Nexa AI

Players can talk to Nexa in chat and (with the right permissions) let it run server tools like teleporting, locating structures, changing weather/time, and more.

Features

• Chat with Nexa directly: /nexa <message>
• Agent Modes:
  • Ask-before-act (default): Privileged actions are previewed and require confirmation before execution.
  • Autonomous: Nexa can execute allowed steps automatically (guardrails still apply).
• Server Guardrails: Per-player request limits + global tool cooldown.
• Customization: Custom assistant name + personality prompt.
• Client GUI: Open the configuration and chat interface by pressing N or using the command /nexa-gui / /nex-gui (Fabric/Forge/NeoForge clients).
• Built-in Tools ("Function Calling"): Server-aware actions, environment lookups, and screenshot analysis.
• Auto Messages: Optional greeting on join + occasional idle-time messages (server-wide, can be disabled).
• Update Notifications & Feedback: Updates checked and feedback sent securely via proxy.

Supported Targets

• Fabric: Minecraft 26.2
• Forge: Minecraft 26.2
• NeoForge: Minecraft 26.2
• Paper: Minecraft 26.1.2 - 26.2+

All targets share a common core compiled with Java 25 compatibility.

Commands

Chat

• /nexa <message> — Chat with Nexa.
• /nexa confirm — Approve queued actions (ask-before-act mode).
• /nexa cancel — Cancel queued actions.

Client GUI

• /nexa-gui (or /nex-gui) — Opens the configuration GUI screen (Fabric, Forge, and NeoForge clients only).

Configuration (/nex-config)

• /nex-config clearchat — Clear your conversation history.
• /nex-config feedback <message> — Send feedback (rate-limited to once per 24 hours).
• /nex-config mode show — Show your current agent mode.
• /nex-config mode <ask|autonomous> — Set your personal agent mode override.
• /nex-config limits status — Show limits and cooldown.
• /nex-config limits maxrequests <1..15> — Set max requests per prompt (requires admin/op privileges).
• /nex-config limits cooldown <seconds> — Set global tool cooldown (requires admin/op privileges).
• /nex-config custom name <name> — Change assistant name (requires admin/op privileges, max 30 chars / 3 words).
• /nex-config custom prompt <prompt> — Set personality prompt (requires admin/op privileges, max 1000 chars).
• /nex-config custom reset — Reset name/prompt to defaults (requires admin/op privileges).
• /nex-config custom show — View your current custom settings.
• /nex-config automessages enable|disable|status — Toggle join/idle auto messages (server-wide).

BYOK (Bring Your Own Key)

BYOK is per-player and bypasses the default proxy for chat calls.

• /nex-byok status — Show BYOK status.
• /nex-byok toggle enable|disable — Enable/disable BYOK.
• /nex-byok provider <google|openai|ollama|lmstudio|custom> — Choose provider.
• /nex-byok apikey <key> — Set API key (required for cloud providers).
• /nex-byok endpoint <url|default> — Set endpoint URL (for local/custom providers, or default to reset).
• /nex-byok model <name> — Set model name.
• /nex-byok tools enable|disable — Enable/disable tool calling (mainly useful for local endpoints).
• /nex-byok test — Test current BYOK config and check connection.

Modes

Ask-before-act

Nexa proposes an action preview and waits for confirmation before running any privileged tool. Approve via the clickable buttons in chat ([Yes] / [No]), or with /nexa confirm (deny with /nexa cancel). Queue timeout is 30 seconds.

Autonomous

Nexa can execute allowed tools without an explicit prompt. Guardrails still apply (cooldowns, request limits, and required privileges).

AI Providers & BYOK Configuration

Default AI Service

By default, Nexa uses default services. It is free but you could experience rate limiting, overload, etc. It is recommended to use BYOK for optimal performance.

BYOK Mode

BYOK (Bring Your Own Key) lets each player use their own provider + key:

• Google Gemini: Default endpoint https://generativelanguage.googleapis.com/v1beta, default model gemini-2.5-flash-lite (supports tool calling).
• OpenAI: Default endpoint https://api.openai.com/v1, default model gpt-5-chat-latest (supports tool calling).
• Ollama (Local): Default endpoint http://localhost:11434/v1 (no API key needed, custom models, tool calling toggle).
• LM Studio (Local): Default endpoint http://localhost:1234/v1 (no API key needed, custom models, supports tool calling).
• Custom: Full OpenAI-compatible custom endpoint, custom models (supports tool calling).

Note: BYOK settings (including API keys) are stored securely on the server in the world data file.

Nexa Tools (Function Calling)

Nexa can call built-in tools depending on player permissions:

Unprivileged Tools (Available to all players)

• getPlayerState: Get current player details (position, health, gamemode, dimension, difficulty, last death location).
• getInventorySummary: Inspect the contents of your inventory, main/off-hand items, and armor.
• getEnvironmentInfo: Retrieve current environment conditions (time, weather, biome, facing direction, difficulty, dimension).
• getGameRules: Read the value of server game rules (e.g., keepInventory, doDaylightCycle).
• getNearbyEntities: Scan for entities (mobs, players) within a 48-block radius.
• saveLocation: Save your current coordinates as a custom named location.
• removeLocation: Remove a saved location or clear all saved locations.
• listSavedLocations: View all your saved locations and their coordinates.
• getAgentContext: Review Nexa's current operational mode, server defaults, guardrails, and permission privileges.
• analyzeScreenshot: Capture a screenshot of the client's screen to visually analyze the game state (available when mod is installed client-side).

Privileged Tools (Require nexa.admin / OP status)

• locate (executes immediately even in ask-before-act): Find coordinates of structures (e.g., village) or biomes.
• teleport (queued in ask-before-act): Teleport to specific coordinates.
• timeSet (queued in ask-before-act): Set the server time (preset like day/noon/night/midnight or a numeric tick value).
• weather (queued in ask-before-act): Change the server weather (clear, rain, thunder) and specify duration.
• giveEffect (queued in ask-before-act): Apply status effects with customizable duration, amplifier, and particles.
• spawnEntity (queued in ask-before-act): Spawn a specific entity (pig, zombie, etc.) at your location or specified coordinates (max 20 entities).

Permissions & Privileges

Nexa integrates with LuckPerms for granular permission control across Fabric, Forge, NeoForge, and Paper.

Permission Nodes

• nexa.use — Access to /nexa, /nex-config, /nex-byok, and /nexa-gui (Default: allowed for all players).
• nexa.admin — Administrative actions (limits/cooldown modification, custom prompts, privileged tools, server-wide changes).

Vanilla Fallback (Without LuckPerms)

• nexa.use is allowed for everyone.
• nexa.admin falls back to OP / Gamemaster privileges on dedicated servers, and Creative Mode in singleplayer.

Requirements & Installation

Java

• Minecraft 26.2: Typically runs on Java 25.

Installation

• Fabric: Install Fabric Loader + Fabric API, then drop the nexa-fabric*.jar into .minecraft/mods/
• Forge: Drop the nexa-forge*.jar into .minecraft/mods/
• NeoForge: Drop the nexa-neoforge*.jar into .minecraft/mods/
• Paper: Drop the nexa-paper*.jar into plugins/ and restart the server.

Tip: Server-side features work with only the server jar installed. Install the client mod to enable the GUI (keybinding N) and screenshot analysis.

Guardrails (Server)

• Agent mode: ASK_BEFORE_ACT or AUTONOMOUS
• Per-prompt request budget (maxrequests) and a global cooldown (cooldown)
• Privileged actions are previewed (and can be denied) in ask-before-act mode.

Fair Use, Safety, and Privacy

• Community Built: Please don’t abuse default services (rate limits/guardrails exist for a reason).
• AI Provider Terms: Default service prompts/responses are processed by Google Gemini. When using BYOK, your chosen provider's terms apply.
• Data & Security: Settings and BYOK API keys are saved per-world in chatmc_locations.json. Only grant server file access to trusted individuals.
• Feedback: Feedback messages submitted via /nex-config feedback are sent to the proxy with identifying metadata.

Support & Contributions

If you encounter issues, have feedback, or wish to contribute, please join our Discord server.

Discord: https://discord.gg/Wvst4znsgk