# yc-software/minecraft-agent-harness architecture

> Architecture diagram of the GitHub repository yc-software/minecraft-agent-harness, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yc-software/minecraft-agent-harness
- Repository: https://github.com/yc-software/minecraft-agent-harness

## Overview

This is a Mineflayer-based LLM agent harness: an operator configures an objective, the agent joins a Minecraft server, and a model session chooses tools that observe and change the world. The graph also preserves the documented model-provider, persistent-session, team messaging/shared-machine, per-agent shell, and experimental vision capabilities. Edges reflect excerpts or README statements; unsampled modules are represented by exact existing paths, and uncertain implementation links are omitted.

Main entry points: [`src/agent.js`](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/agent.js) (Agent orchestration), [`src/model/session.js`](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/model/session.js) (Model session), [`src/tools/game-tools.js`](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/tools/game-tools.js) (Game tool registry), [`src/skills/skills.js`](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/skills/skills.js) (Game skills)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Setup and orchestration"]
  node_config["Configuration<br/>[config.js]"]
  node_startup["Startup<br/>[startup.js]"]
  node_agent["Agent orchestration<br/>[agent.js]"]
end

subgraph group_brain["Model and agent loop"]
  node_session["Model session<br/>[session.js]"]
  node_prompt["System prompt<br/>[prompt.js]"]
  node_provider["Model providers<br/>[extra-models.js]"]
  node_history["Session history<br/>[session-history.js]"]
  node_imageguard["Image safeguards<br/>[image-guard.js]"]
end

subgraph group_minecraft["Minecraft capabilities"]
  node_bot["Minecraft bot<br/>[bot.js]"]
  node_skills["Game skills<br/>[skills.js]"]
  node_survival["Survival skills<br/>[survival.js]"]
  node_world["World skills<br/>[world.js]"]
  node_perception["Perception<br/>[perception.js]"]
  node_gametools["Game tool registry<br/>[game-tools.js]"]
  node_gameruntime["Action runtime<br/>[runtime.js]"]
  node_movement["Movement tools<br/>[movement.js]"]
  node_placement["Placement tools<br/>[placement.js]"]
  node_gameactions["Other game actions"]
end

subgraph group_team["Teams and vision"]
  node_mailbox[("Team mailbox<br/>[mailbox-store.js]")]
  node_plan["Shared plans<br/>[plan.js]"]
  node_sharedmachine["Shared machine service<br/>[server.js]"]
  node_vision["Vision capture<br/>[camera.js]"]
end

subgraph group_shell["Agent shell"]
  node_shelltools["Shell tools<br/>[shell-tools.js]"]
  node_sandbox["Sandbox implementations<br/>[shell-sandbox.js]"]
  node_docker["Docker sandbox<br/>[docker.js]"]
  node_e2b["E2B machine<br/>[e2b.js]"]
  node_localmachine["Local machine<br/>[local.js]"]
end

node_operator(("Operator"))
node_mcserver(("Minecraft server"))
node_providerapi(("Model API"))

node_operator -->|"configures"| node_config
node_config -->|"configures"| node_startup
node_startup -->|"creates"| node_session
node_startup -->|"loads"| node_provider
node_session -.->|"requests completions"| node_providerapi
node_session -->|"uses history"| node_history
node_session -->|"uses safeguards"| node_imageguard
node_operator -->|"starts"| node_agent
node_agent -->|"creates"| node_session
node_agent -.->|"starts bot"| node_bot
node_bot -.->|"connects"| node_mcserver
node_session -->|"uses prompt"| node_prompt
node_session -->|"registers tools"| node_gametools
node_gametools -->|"creates runner"| node_gameruntime
node_gametools -->|"registers"| node_movement
node_gametools -->|"registers"| node_placement
node_gametools -->|"registers"| node_gameactions
node_gameruntime -->|"guards actions"| node_bot
node_movement -->|"invokes skills"| node_skills
node_skills -->|"acts through"| node_bot
node_skills -->|"uses"| node_world
node_skills -->|"uses"| node_perception
node_agent -->|"uses messaging"| node_mailbox
node_agent -->|"reads and appends"| node_plan
node_agent -->|"captures frames"| node_vision
node_agent -.->|"provides tools"| node_shelltools
node_shelltools -.->|"executes commands"| node_sandbox
node_sandbox -->|"shared base helpers"| node_docker
node_agent -.->|"team execution"| node_sharedmachine
node_sharedmachine -.->|"served by"| node_e2b
node_sharedmachine -.->|"served by"| node_localmachine

click node_config "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/config.js"
click node_startup "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/startup.js"
click node_agent "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/agent.js"
click node_session "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/model/session.js"
click node_prompt "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/prompt.js"
click node_provider "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/model/extra-models.js"
click node_history "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/model/session-history.js"
click node_imageguard "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/model/image-guard.js"
click node_bot "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/body/bot.js"
click node_skills "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/skills/skills.js"
click node_survival "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/skills/survival.js"
click node_world "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/skills/world.js"
click node_perception "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/skills/perception.js"
click node_gametools "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/tools/game-tools.js"
click node_gameruntime "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/tools/game/runtime.js"
click node_movement "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/tools/game/movement.js"
click node_placement "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/tools/game/placement.js"
click node_gameactions "https://github.com/yc-software/minecraft-agent-harness/tree/main/src/tools/game"
click node_mailbox "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/comms/mailbox-store.js"
click node_plan "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/comms/plan.js"
click node_sharedmachine "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/shared-machine/server.js"
click node_vision "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/vision/camera.js"
click node_shelltools "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/tools/shell-tools.js"
click node_sandbox "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/sandbox/shell-sandbox.js"
click node_docker "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/sandbox/docker.js"
click node_e2b "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/shared-machine/e2b.js"
click node_localmachine "https://github.com/yc-software/minecraft-agent-harness/blob/main/src/shared-machine/local.js"

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_config,node_startup,node_agent toneBlue
class node_session,node_prompt,node_provider,node_history,node_imageguard toneAmber
class node_bot,node_skills,node_survival,node_world,node_perception,node_gametools,node_gameruntime,node_movement,node_placement,node_gameactions,node_mcserver,node_providerapi toneMint
class node_mailbox,node_plan,node_sharedmachine,node_vision toneRose
class node_shelltools,node_sandbox,node_docker,node_e2b,node_localmachine,node_operator toneIndigo
```

## Components

### Setup and orchestration

- [Configuration](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/config.js): `src/config.js`
- [Startup](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/startup.js): `src/startup.js`
- [Agent orchestration](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/agent.js): `src/agent.js`

### Model and agent loop

- [Model session](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/model/session.js): `src/model/session.js`
- [System prompt](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/prompt.js): `src/prompt.js`
- [Model providers](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/model/extra-models.js): `src/model/extra-models.js`
- [Session history](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/model/session-history.js): `src/model/session-history.js`
- [Image safeguards](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/model/image-guard.js): `src/model/image-guard.js`

### Minecraft capabilities

- [Minecraft bot](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/body/bot.js): `src/body/bot.js`
- [Game skills](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/skills/skills.js): `src/skills/skills.js`
- [Survival skills](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/skills/survival.js): `src/skills/survival.js`
- [World skills](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/skills/world.js): `src/skills/world.js`
- [Perception](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/skills/perception.js): `src/skills/perception.js`
- [Game tool registry](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/tools/game-tools.js): `src/tools/game-tools.js`
- [Action runtime](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/tools/game/runtime.js): `src/tools/game/runtime.js`
- [Movement tools](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/tools/game/movement.js): `src/tools/game/movement.js`
- [Placement tools](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/tools/game/placement.js): `src/tools/game/placement.js`
- [Other game actions](https://github.com/yc-software/minecraft-agent-harness/tree/main/src/tools/game): `src/tools/game`

### Teams and vision

- [Team mailbox](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/comms/mailbox-store.js): `src/comms/mailbox-store.js`
- [Shared plans](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/comms/plan.js): `src/comms/plan.js`
- [Shared machine service](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/shared-machine/server.js): `src/shared-machine/server.js`
- [Vision capture](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/vision/camera.js): `src/vision/camera.js`

### Agent shell

- [Shell tools](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/tools/shell-tools.js): `src/tools/shell-tools.js`
- [Sandbox implementations](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/sandbox/shell-sandbox.js): `src/sandbox/shell-sandbox.js`
- [Docker sandbox](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/sandbox/docker.js): `src/sandbox/docker.js`
- [E2B machine](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/shared-machine/e2b.js): `src/shared-machine/e2b.js`
- [Local machine](https://github.com/yc-software/minecraft-agent-harness/blob/main/src/shared-machine/local.js): `src/shared-machine/local.js`

### Other components

- **Operator**
- **Minecraft server**
- **Model API**

## Connections

- Operator → Configuration: configures (evidence: `README.md`)
- Configuration → Startup: configures (evidence: `src/config.js`)
- Startup → Model session: creates (evidence: `src/startup.js`)
- Startup → Model providers: loads (evidence: `src/startup.js`)
- Model session → Model API: requests completions
- Model session → Session history: uses history (evidence: `src/model/session.js`)
- Model session → Image safeguards: uses safeguards (evidence: `src/model/session.js`)
- Operator → Agent orchestration: starts (evidence: `README.md`)
- Agent orchestration → Model session: creates (evidence: `src/agent.js`)
- Agent orchestration → Minecraft bot: starts bot (evidence: `src/agent.js`)
- Minecraft bot → Minecraft server: connects
- Model session → System prompt: uses prompt (evidence: `src/index.js`)
- Model session → Game tool registry: registers tools (evidence: `src/index.js`)
- Game tool registry → Action runtime: creates runner (evidence: `src/tools/game-tools.js`)
- Game tool registry → Movement tools: registers (evidence: `src/tools/game-tools.js`)
- Game tool registry → Placement tools: registers (evidence: `src/tools/game-tools.js`)
- Game tool registry → Other game actions: registers (evidence: `src/tools/game-tools.js`)
- Action runtime → Minecraft bot: guards actions (evidence: `src/tools/game/runtime.js`)
- Movement tools → Game skills: invokes skills (evidence: `src/tools/game/movement.js`)
- Game skills → Minecraft bot: acts through (evidence: `src/skills/skills.js`)
- Game skills → World skills: uses (evidence: `src/skills/skills.js`)
- Game skills → Perception: uses (evidence: `src/skills/skills.js`)
- Agent orchestration → Team mailbox: uses messaging (evidence: `src/agent.js`)
- Agent orchestration → Shared plans: reads and appends (evidence: `src/agent.js`)
- Agent orchestration → Vision capture: captures frames (evidence: `src/agent.js`)
- Agent orchestration → Shell tools: provides tools (evidence: `src/agent.js`)
- Shell tools → Sandbox implementations: executes commands
- Sandbox implementations → Docker sandbox: shared base helpers (evidence: `src/sandbox/docker.js`)
- Agent orchestration → Shared machine service: team execution
- Shared machine service → E2B machine: served by (evidence: `src/shared-machine/e2b.js`)
- Shared machine service → Local machine: served by (evidence: `src/shared-machine/local.js`)