haksnbot-agent

The haksnbot-agent is a sophisticated autonomous bot designed for Minecraft, utilizing the powerful Claude Agent SDK. This bot seamlessly connects to any Minecraft server and is capable of engaging with players through chat, while autonomously navigating the game environment—surviving, building structures, crafting tools, and assisting players with their adventures.

Key Features

• Autonomous Gameplay: Capable of survival, resource gathering, crafting, and creating shelters without manual input.
• Player Interaction: Engages with players by responding to chat and providing assistance as needed.
• Reliable Connection: Features an auto-reconnect function to maintain a continuous connection to the server.
• Event-driven Architecture: Reacts dynamically to in-game events such as player activity and system messages.
• Customizable Personality: Personalizes responses through a configurable system prompt, adaptable to various server environments.
• Extensive Toolset: Integrates with over 50 Minecraft Control Protocol (MCP) tools and optional server administration tools for enhanced functionality.

Architecture Overview

The architecture of haksnbot-agent is designed to function efficiently within the Minecraft ecosystem, illustrated as follows:

┌─────────────────────────────────────────────────────────────┐
│                     haksnbot-agent                           │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐  │
│  │ Claude Agent SDK│  │ chat-poll.sh    │  │ Event Loop  │  │
│  │ (persistent)    │  │ (log watcher)   │  │ (asyncio)   │  │
│  └────────┬────────┘  └────────┬────────┘  └─────────────┘  │
└───────────┼────────────────────┼────────────────────────────┘
            │                    │
            │ stdio              │ reads server logs
            ▼                    ▼
┌─────────────────────────────────────────────────────────────┐
│                      MCP Servers                             │
│  ┌─────────────────────┐  ┌──────────────────────────────┐  │
│  │   haksnbot-tools    │  │   haksnbot-admin (optional)  │  │
│  │   (40+ tools)       │  │   (14 tools)                 │  │
│  │   - movement, chat  │  │   - files, git               │  │
│  │   - inventory, build│  │   - server management        │  │
│  └──────────┬──────────┘  └──────────────────────────────┘  │
└─────────────┼───────────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────┐
│   Minecraft Server      │
│   (via Mineflayer)      │
└─────────────────────────┘

Configuration and Customization

The agent requires basic configuration to start. Key settings such as Minecraft server address, player authentication, and behavior customization can be defined in the configuration file. Example prompts can be modified to reflect server-specific guidelines and personality traits, enhancing the player experience.

Example configuration can be set as follows:

minecraft:
  host: mc.example.com        # Your server address
  port: 25565
  username: bot@outlook.com   # Microsoft email for online-mode
  auth: microsoft             # Omit for offline-mode servers
  version: "1.20.4"           # Minecraft version

claude:
  model: claude-sonnet-4-20250514
  max_tokens: 1024

behavior:
  respond_to_mentions: true   # Only respond when bot name is mentioned
  greet_on_join: false        # Greet players who join
  message_batch_delay_ms: 3000

Integrations and Plugin Support

The haksnbot agent also offers ready-made integrations with popular Minecraft server plugins such as GriefPrevention and QuickShop-Hikari, allowing for advanced functionalities like respecting player land claims and shop management.

Getting Started

To initiate the agent, users need to follow the outlined steps for environment setup, configuration, and execution as detailed in the README. The haksnbot-agent is essential for those looking to enhance gameplay experiences in Minecraft through automation and interactivity.