cletus

Cletus is a Java Edition Minecraft bot built with AI and Mineflayer. The goal is to have Cletus become somewhat autonomous.

Cletus Bot – A Learning Minecraft AI

Cletus is a modular Mineflayer-based Minecraft bot designed to observe, learn, adapt, and evolve through tasks, memory, and AI interaction. It reads signs, listens to players, remembers context, and uses a local AI model to improve over time.

---

Features

• State-driven AI: Uses a dynamic state machine (/states) to handle tasks like Observe, ReadFromSign, Idle, HandleChat, etc.
• Memory system: Persists events, chats, locations, and signs in SQLite via /memory
• Safe zones: Prevents accidental destruction near homes, beds, bases, and more
• AI integration: Uses Ollama with gemma3 or any LLM to chat and rewrite failed scripts
• Self-growing: Failed task scripts are auto-sent to AI for improvement and saved

---

Folder Structure

├── bot.js                # Bot entrypoint
├── config.json           # Centralized bot and AI config
├── core/
│   ├── state-machine.js  # Loads and manages dynamic states
│   └── context.js        # Shared bot context for state/tasks
├── states/               # Modular AI states (Observe, Idle, etc.)
├── bot-tasks/            # AI or manually written task modules
├── memory/               # Memory modules (chat, signs, events, etc.)
├── lib/
│   ├── ai-helper.js      # AI chat integration
│   └── utils.js          # (Optional helper utils)
├── db/
│   └── memory.db         # SQLite database (auto-created)

---

Config (config.json)

{
  "bot": {
    "name": "Cletus",
    "host": "192.168.1.90",
    "port": 25565,
    "auth": "offline",
    "version": "1.20.4"
  },
  "ai": {
    "model": "gemma3",
    "ollamaUrl": "http://localhost:11434/api/generate",
    "persona": "a curious minecraft explorer who learns from the world around them",
    "responseLength": 30
  },
  "safeZone": {
    "xBound": 50,
    "yBound": 30,
    "zBound": 50,
    "keywords": ["home", "bed", "base", "village", "farm"]
  }
}

---

🛠 Prerequisites

• Node.js (v16+)
• Ollama running locally with gemma3 or compatible model
• Minecraft server (1.20.4) with bot permissions

---

Running the Bot

npm install
node bot.js

Then in Minecraft:

Say: Cletus, go find a flower

---

Extending Cletus

• Add new tasks to /bot-tasks/
• Add new states to /states/
• Memory system will auto-track chat, signs, events
• AI auto-rewrites broken tasks using chatWithAI()

---

AI Improvement Loop

1. You run a task
2. If it fails → AI rewrites the file
3. File is overwritten and reused on next run

---

Example Tasks

• find-flower
• observe
• read-from-sign
• idle

Want Cletus to do more? Just ask him in chat.