# kolbytn/mindcraft architecture

> Architecture diagram of the GitHub repository kolbytn/mindcraft, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kolbytn/mindcraft
- Repository: https://github.com/kolbytn/mindcraft

## Overview

Mindcraft runs configurable LLM-driven Minecraft agents: a user starts agents from profiles or a task, which act in a Minecraft world and can be evaluated against task goals. The graph preserves the documented model-provider choices, task domains, vision, NPC behavior, and Python interface. The excerpts show task validation and action management, but omit much of the runtime wiring; uncertain links are therefore left out.

Main entry points: [`src/agent/agent.js`](https://github.com/kolbytn/mindcraft/blob/develop/src/agent/agent.js) (Minecraft agent), [`src/agent/conversation.js`](https://github.com/kolbytn/mindcraft/blob/develop/src/agent/conversation.js) (Conversation), [`src/agent/tasks/tasks.js`](https://github.com/kolbytn/mindcraft/blob/develop/src/agent/tasks/tasks.js) (Task orchestration), [`main.js`](https://github.com/kolbytn/mindcraft/blob/develop/main.js) (Startup and profiles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent runtime"]
  node_main["Startup and profiles<br/>[main.js]"]
  node_mindcraft["Runtime coordinator<br/>[mindcraft.js]"]
  node_agentproc["Agent process<br/>[agent_process.js]"]
  node_initagent["Agent initialization<br/>[init_agent.js]"]
  node_agent["Minecraft agent<br/>[agent.js]"]
end

subgraph group_reasoning["Reasoning and actions"]
  node_conversation["Conversation<br/>[conversation.js]"]
  node_history[("History and memory<br/>[history.js]")]
  node_prompter["Prompt construction<br/>[prompter.js]"]
  node_modelmap["Model selection<br/>[_model_map.js]"]
  node_action["Action execution<br/>[action_manager.js]"]
  node_commands["Agent commands<br/>[index.js]"]
end

subgraph group_world["Minecraft interaction"]
  node_skills["Skills library<br/>[skills.js]"]
  node_worldlib["World access<br/>[world.js]"]
  node_vision["Vision interpretation"]
  node_camera["World camera<br/>[camera.js]"]
end

subgraph group_tasks["Tasks and goals"]
  node_tasks["Task orchestration<br/>[tasks.js]"]
  node_construction["Construction validation"]
  node_cooking["Cooking tasks<br/>[cooking_tasks.js]"]
  node_npc["NPC goal controller<br/>[controller.js]"]
end

subgraph group_integrations["External interfaces"]
  node_models["LLM provider adapters"]
  node_minecraft[("Minecraft server")]
  node_mindserver["MindServer interface<br/>[mindserver.js]"]
  node_python["Python interface<br/>[mindcraft.py]"]
end

node_user(("Operator"))

node_user -->|"starts"| node_main
node_main -->|"initializes agents"| node_mindcraft
node_main -->|"loads task"| node_tasks
node_mindcraft -->|"creates process"| node_agentproc
node_agentproc -->|"initializes"| node_initagent
node_initagent -->|"configures"| node_agent
node_agent -->|"runs dialogue"| node_conversation
node_conversation -->|"records turns"| node_history
node_conversation -->|"builds prompts"| node_prompter
node_conversation -->|"selects model"| node_modelmap
node_modelmap -->|"dispatches request"| node_models
node_agent -->|"manages actions"| node_action
node_action -->|"controls execution"| node_agent
node_agent -->|"handles commands"| node_commands
node_commands -->|"calls skills"| node_skills
node_skills -->|"uses world access"| node_worldlib
node_camera -->|"supplies images"| node_vision
node_tasks -->|"validates builds"| node_construction
node_tasks -->|"starts cooking task"| node_cooking
node_tasks -->|"sets goals"| node_commands
node_npc -->|"uses skills"| node_skills
node_npc -->|"queries world"| node_worldlib
node_agent -->|"acts in world"| node_minecraft
node_mindcraft -->|"starts interface"| node_mindserver
node_python -.->|"connects"| node_mindserver
node_models -.-> node_minecraft

click node_main "https://github.com/kolbytn/mindcraft/blob/develop/main.js"
click node_mindcraft "https://github.com/kolbytn/mindcraft/blob/develop/src/mindcraft/mindcraft.js"
click node_agentproc "https://github.com/kolbytn/mindcraft/blob/develop/src/process/agent_process.js"
click node_initagent "https://github.com/kolbytn/mindcraft/blob/develop/src/process/init_agent.js"
click node_agent "https://github.com/kolbytn/mindcraft/blob/develop/src/agent/agent.js"
click node_conversation "https://github.com/kolbytn/mindcraft/blob/develop/src/agent/conversation.js"
click node_history "https://github.com/kolbytn/mindcraft/blob/develop/src/agent/history.js"
click node_prompter "https://github.com/kolbytn/mindcraft/blob/develop/src/models/prompter.js"
click node_modelmap "https://github.com/kolbytn/mindcraft/blob/develop/src/models/_model_map.js"
click node_models "https://github.com/kolbytn/mindcraft/tree/develop/src/models"
click node_action "https://github.com/kolbytn/mindcraft/blob/develop/src/agent/action_manager.js"
click node_commands "https://github.com/kolbytn/mindcraft/blob/develop/src/agent/commands/index.js"
click node_skills "https://github.com/kolbytn/mindcraft/blob/develop/src/agent/library/skills.js"
click node_worldlib "https://github.com/kolbytn/mindcraft/blob/develop/src/agent/library/world.js"
click node_vision "https://github.com/kolbytn/mindcraft/blob/develop/src/agent/vision/vision_interpreter.js"
click node_camera "https://github.com/kolbytn/mindcraft/blob/develop/src/agent/vision/camera.js"
click node_tasks "https://github.com/kolbytn/mindcraft/blob/develop/src/agent/tasks/tasks.js"
click node_construction "https://github.com/kolbytn/mindcraft/blob/develop/src/agent/tasks/construction_tasks.js"
click node_cooking "https://github.com/kolbytn/mindcraft/blob/develop/src/agent/tasks/cooking_tasks.js"
click node_npc "https://github.com/kolbytn/mindcraft/blob/develop/src/agent/npc/controller.js"
click node_mindserver "https://github.com/kolbytn/mindcraft/blob/develop/src/mindcraft/mindserver.js"
click node_python "https://github.com/kolbytn/mindcraft/blob/develop/src/mindcraft-py/mindcraft.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_mindcraft,node_agentproc,node_initagent,node_agent toneBlue
class node_conversation,node_history,node_prompter,node_modelmap,node_action,node_commands toneAmber
class node_skills,node_worldlib,node_vision,node_camera toneMint
class node_tasks,node_construction,node_cooking,node_npc toneRose
class node_models,node_minecraft,node_mindserver,node_python,node_user toneIndigo
```

## Components

### Agent runtime

- [Startup and profiles](https://github.com/kolbytn/mindcraft/blob/develop/main.js): `main.js`
- [Runtime coordinator](https://github.com/kolbytn/mindcraft/blob/develop/src/mindcraft/mindcraft.js): `src/mindcraft/mindcraft.js`
- [Agent process](https://github.com/kolbytn/mindcraft/blob/develop/src/process/agent_process.js): `src/process/agent_process.js`
- [Agent initialization](https://github.com/kolbytn/mindcraft/blob/develop/src/process/init_agent.js): `src/process/init_agent.js`
- [Minecraft agent](https://github.com/kolbytn/mindcraft/blob/develop/src/agent/agent.js): `src/agent/agent.js`

### Reasoning and actions

- [Conversation](https://github.com/kolbytn/mindcraft/blob/develop/src/agent/conversation.js): `src/agent/conversation.js`
- [History and memory](https://github.com/kolbytn/mindcraft/blob/develop/src/agent/history.js): `src/agent/history.js`
- [Prompt construction](https://github.com/kolbytn/mindcraft/blob/develop/src/models/prompter.js): `src/models/prompter.js`
- [Model selection](https://github.com/kolbytn/mindcraft/blob/develop/src/models/_model_map.js): `src/models/_model_map.js`
- [Action execution](https://github.com/kolbytn/mindcraft/blob/develop/src/agent/action_manager.js): `src/agent/action_manager.js`
- [Agent commands](https://github.com/kolbytn/mindcraft/blob/develop/src/agent/commands/index.js): `src/agent/commands/index.js`

### Minecraft interaction

- [Skills library](https://github.com/kolbytn/mindcraft/blob/develop/src/agent/library/skills.js): `src/agent/library/skills.js`
- [World access](https://github.com/kolbytn/mindcraft/blob/develop/src/agent/library/world.js): `src/agent/library/world.js`
- [Vision interpretation](https://github.com/kolbytn/mindcraft/blob/develop/src/agent/vision/vision_interpreter.js): `src/agent/vision/vision_interpreter.js`
- [World camera](https://github.com/kolbytn/mindcraft/blob/develop/src/agent/vision/camera.js): `src/agent/vision/camera.js`

### Tasks and goals

- [Task orchestration](https://github.com/kolbytn/mindcraft/blob/develop/src/agent/tasks/tasks.js): `src/agent/tasks/tasks.js`
- [Construction validation](https://github.com/kolbytn/mindcraft/blob/develop/src/agent/tasks/construction_tasks.js): `src/agent/tasks/construction_tasks.js`
- [Cooking tasks](https://github.com/kolbytn/mindcraft/blob/develop/src/agent/tasks/cooking_tasks.js): `src/agent/tasks/cooking_tasks.js`
- [NPC goal controller](https://github.com/kolbytn/mindcraft/blob/develop/src/agent/npc/controller.js): `src/agent/npc/controller.js`

### External interfaces

- [LLM provider adapters](https://github.com/kolbytn/mindcraft/tree/develop/src/models): `src/models`
- **Minecraft server**
- [MindServer interface](https://github.com/kolbytn/mindcraft/blob/develop/src/mindcraft/mindserver.js): `src/mindcraft/mindserver.js`
- [Python interface](https://github.com/kolbytn/mindcraft/blob/develop/src/mindcraft-py/mindcraft.py): `src/mindcraft-py/mindcraft.py`

### Other components

- **Operator**

## Connections

- Operator → Startup and profiles: starts
- Startup and profiles → Runtime coordinator: initializes agents
- Startup and profiles → Task orchestration: loads task
- Runtime coordinator → Agent process: creates process
- Agent process → Agent initialization: initializes
- Agent initialization → Minecraft agent: configures
- Minecraft agent → Conversation: runs dialogue
- Conversation → History and memory: records turns
- Conversation → Prompt construction: builds prompts
- Conversation → Model selection: selects model
- Model selection → LLM provider adapters: dispatches request
- Minecraft agent → Action execution: manages actions
- Action execution → Minecraft agent: controls execution
- Minecraft agent → Agent commands: handles commands
- Agent commands → Skills library: calls skills
- Skills library → World access: uses world access
- World camera → Vision interpretation: supplies images
- Task orchestration → Construction validation: validates builds
- Task orchestration → Cooking tasks: starts cooking task
- Task orchestration → Agent commands: sets goals
- NPC goal controller → Skills library: uses skills
- NPC goal controller → World access: queries world
- Minecraft agent → Minecraft server: acts in world
- Runtime coordinator → MindServer interface: starts interface
- Python interface → MindServer interface: connects
- LLM provider adapters → Minecraft server