# blendi-remade/agentcraft architecture

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

- Interactive diagram: https://gitdiagram.com/blendi-remade/agentcraft
- Repository: https://github.com/blendi-remade/agentcraft

## Overview

AgentCraft pairs a Minecraft studio client with the Foreman service. A user submits a goal through the in-game console; Foreman coordinates planning and agent work in isolated Git worktrees, streams state back to the client, and the user answers questions and reviews proposed diffs before approving a merge. The graph retains the documented safety, memory, simulation, and studio-world capabilities. Several subsystem links are documented in the README; unsampled implementation details are not inferred.

Main entry points: [`mod/src/client/java/dev/agentcraft/client/foreman/ForemanState.java`](https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/foreman/ForemanState.java) (Client state), [`foreman/src/foreman.ts`](https://github.com/blendi-remade/agentcraft/blob/main/foreman/src/foreman.ts) (Foreman core), [`mod/src/client/java/dev/agentcraft/client/foreman/Foreman.java`](https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/foreman/Foreman.java) (Foreman link), [`foreman/src/server.ts`](https://github.com/blendi-remade/agentcraft/blob/main/foreman/src/server.ts) (WebSocket server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Minecraft client"]
  node_console["Goal console"]
  node_clientlink["Foreman link<br/>[Foreman.java]"]
  node_clientstate["Client state<br/>[ForemanState.java]"]
  node_taskwall["Task wall<br/>[TaskScreen.java]"]
  node_monitor["Agent monitors<br/>[MonitorScreen.java]"]
  node_decisions["Decision podium"]
  node_review["Diff review<br/>[ReviewKit.java]"]
  node_library["Shared library<br/>[MemoryIndex.java]"]
end

subgraph group_foreman["Foreman service"]
  node_protocol["Wire protocol<br/>[protocol.ts]"]
  node_server["WebSocket server<br/>[server.ts]"]
  node_core["Foreman core<br/>[foreman.ts]"]
  node_config["Runtime config<br/>[config.ts]"]
end

subgraph group_work["Agent work"]
  node_claude["Claude agents<br/>[stream.ts]"]
  node_sim["Simulation backend<br/>[director.ts]"]
  node_scenario["Sim scenarios<br/>[scenario.ts]"]
  node_repo[("Git worktrees<br/>[repos.ts]")]
end

subgraph group_studio["Studio world"]
  node_agents["Agent movement<br/>[AgentLife.java]"]
  node_agentmanager["Agent manager<br/>[AgentManager.java]"]
  node_hq["HQ features<br/>[HqFeature.java]"]
  node_anchors["Studio anchors<br/>[Anchors.java]"]
  node_entry["Mod initialization<br/>[AgentCraft.java]"]
end

node_user(("User"))
node_externalrepo[("User repository")]

node_user -->|"enters goal"| node_console
node_console -->|"submits goal"| node_clientlink
node_clientlink -.->|"sends messages"| node_server
node_server -->|"parses messages"| node_protocol
node_server -->|"routes intents"| node_core
node_core -->|"emits state"| node_protocol
node_protocol -->|"defines updates"| node_clientstate
node_clientlink -->|"applies updates"| node_clientstate
node_core -->|"uses settings"| node_config
node_core -.->|"drives agents"| node_claude
node_core -.->|"selects backend"| node_sim
node_sim -->|"runs scenarios"| node_scenario
node_core -->|"manages worktrees"| node_repo
node_repo -->|"isolates changes"| node_externalrepo
node_clientstate -->|"shows tasks"| node_taskwall
node_clientstate -->|"shows live logs"| node_monitor
node_clientstate -->|"shows questions"| node_decisions
node_decisions -->|"sends answers"| node_clientlink
node_clientstate -->|"shows diffs"| node_review
node_review -->|"requests diff"| node_clientlink
node_clientstate -->|"shows memory"| node_library
node_clientstate -->|"updates agents"| node_agentmanager
node_agentmanager -->|"updates motion"| node_agents
node_entry -->|"initializes HQ"| node_hq
node_entry -->|"initializes anchors"| node_anchors
node_agentmanager -->|"uses layout"| node_anchors
node_hq -->|"reads layout"| node_anchors

click node_console "https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/console/ConsoleActions.java"
click node_clientlink "https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/foreman/Foreman.java"
click node_clientstate "https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/foreman/ForemanState.java"
click node_protocol "https://github.com/blendi-remade/agentcraft/blob/main/foreman/src/protocol.ts"
click node_server "https://github.com/blendi-remade/agentcraft/blob/main/foreman/src/server.ts"
click node_core "https://github.com/blendi-remade/agentcraft/blob/main/foreman/src/foreman.ts"
click node_config "https://github.com/blendi-remade/agentcraft/blob/main/foreman/src/config.ts"
click node_claude "https://github.com/blendi-remade/agentcraft/blob/main/foreman/src/agents/claude/stream.ts"
click node_sim "https://github.com/blendi-remade/agentcraft/blob/main/foreman/src/agents/sim/director.ts"
click node_scenario "https://github.com/blendi-remade/agentcraft/blob/main/foreman/src/agents/sim/scenario.ts"
click node_repo "https://github.com/blendi-remade/agentcraft/blob/main/foreman/src/repos.ts"
click node_taskwall "https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/taskwall/TaskScreen.java"
click node_monitor "https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/monitor/MonitorScreen.java"
click node_decisions "https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/decisions/DecisionScreen.java"
click node_review "https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/diff/ReviewKit.java"
click node_library "https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/library/MemoryIndex.java"
click node_agents "https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/agents/AgentLife.java"
click node_agentmanager "https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/agents/AgentManager.java"
click node_hq "https://github.com/blendi-remade/agentcraft/blob/main/mod/src/main/java/dev/agentcraft/hq/HqFeature.java"
click node_anchors "https://github.com/blendi-remade/agentcraft/blob/main/mod/src/main/java/dev/agentcraft/layout/Anchors.java"
click node_entry "https://github.com/blendi-remade/agentcraft/blob/main/mod/src/main/java/dev/agentcraft/AgentCraft.java"

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_console,node_clientlink,node_clientstate,node_taskwall,node_monitor,node_decisions,node_review,node_library,node_user toneBlue
class node_protocol,node_server,node_core,node_config,node_externalrepo toneAmber
class node_claude,node_sim,node_scenario,node_repo toneMint
class node_agents,node_agentmanager,node_hq,node_anchors,node_entry toneRose
```

## Components

### Minecraft client

- [Goal console](https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/console/ConsoleActions.java): `mod/src/client/java/dev/agentcraft/client/console/ConsoleActions.java`
- [Foreman link](https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/foreman/Foreman.java): `mod/src/client/java/dev/agentcraft/client/foreman/Foreman.java`
- [Client state](https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/foreman/ForemanState.java): `mod/src/client/java/dev/agentcraft/client/foreman/ForemanState.java`
- [Task wall](https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/taskwall/TaskScreen.java): `mod/src/client/java/dev/agentcraft/client/taskwall/TaskScreen.java`
- [Agent monitors](https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/monitor/MonitorScreen.java): `mod/src/client/java/dev/agentcraft/client/monitor/MonitorScreen.java`
- [Decision podium](https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/decisions/DecisionScreen.java): `mod/src/client/java/dev/agentcraft/client/decisions/DecisionScreen.java`
- [Diff review](https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/diff/ReviewKit.java): `mod/src/client/java/dev/agentcraft/client/diff/ReviewKit.java`
- [Shared library](https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/library/MemoryIndex.java): `mod/src/client/java/dev/agentcraft/client/library/MemoryIndex.java`

### Foreman service

- [Wire protocol](https://github.com/blendi-remade/agentcraft/blob/main/foreman/src/protocol.ts): `foreman/src/protocol.ts`
- [WebSocket server](https://github.com/blendi-remade/agentcraft/blob/main/foreman/src/server.ts): `foreman/src/server.ts`
- [Foreman core](https://github.com/blendi-remade/agentcraft/blob/main/foreman/src/foreman.ts): `foreman/src/foreman.ts`
- [Runtime config](https://github.com/blendi-remade/agentcraft/blob/main/foreman/src/config.ts): `foreman/src/config.ts`

### Agent work

- [Claude agents](https://github.com/blendi-remade/agentcraft/blob/main/foreman/src/agents/claude/stream.ts): `foreman/src/agents/claude/stream.ts`
- [Simulation backend](https://github.com/blendi-remade/agentcraft/blob/main/foreman/src/agents/sim/director.ts): `foreman/src/agents/sim/director.ts`
- [Sim scenarios](https://github.com/blendi-remade/agentcraft/blob/main/foreman/src/agents/sim/scenario.ts): `foreman/src/agents/sim/scenario.ts`
- [Git worktrees](https://github.com/blendi-remade/agentcraft/blob/main/foreman/src/repos.ts): `foreman/src/repos.ts`

### Studio world

- [Agent movement](https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/agents/AgentLife.java): `mod/src/client/java/dev/agentcraft/client/agents/AgentLife.java`
- [Agent manager](https://github.com/blendi-remade/agentcraft/blob/main/mod/src/client/java/dev/agentcraft/client/agents/AgentManager.java): `mod/src/client/java/dev/agentcraft/client/agents/AgentManager.java`
- [HQ features](https://github.com/blendi-remade/agentcraft/blob/main/mod/src/main/java/dev/agentcraft/hq/HqFeature.java): `mod/src/main/java/dev/agentcraft/hq/HqFeature.java`
- [Studio anchors](https://github.com/blendi-remade/agentcraft/blob/main/mod/src/main/java/dev/agentcraft/layout/Anchors.java): `mod/src/main/java/dev/agentcraft/layout/Anchors.java`
- [Mod initialization](https://github.com/blendi-remade/agentcraft/blob/main/mod/src/main/java/dev/agentcraft/AgentCraft.java): `mod/src/main/java/dev/agentcraft/AgentCraft.java`

### Other components

- **User**
- **User repository**

## Connections

- User → Goal console: enters goal (evidence: `README.md`)
- Goal console → Foreman link: submits goal (evidence: `mod/src/client/java/dev/agentcraft/client/foreman/Foreman.java`)
- Foreman link → WebSocket server: sends messages
- WebSocket server → Wire protocol: parses messages (evidence: `foreman/src/server.ts`)
- WebSocket server → Foreman core: routes intents (evidence: `foreman/src/server.ts`)
- Foreman core → Wire protocol: emits state (evidence: `foreman/src/foreman.ts`)
- Wire protocol → Client state: defines updates (evidence: `foreman/src/protocol.ts`)
- Foreman link → Client state: applies updates (evidence: `mod/src/client/java/dev/agentcraft/client/foreman/Foreman.java`)
- Foreman core → Runtime config: uses settings (evidence: `foreman/src/foreman.ts`)
- Foreman core → Claude agents: drives agents
- Foreman core → Simulation backend: selects backend
- Simulation backend → Sim scenarios: runs scenarios (evidence: `foreman/src/agents/sim/index.ts`)
- Foreman core → Git worktrees: manages worktrees (evidence: `README.md`)
- Git worktrees → User repository: isolates changes (evidence: `README.md`)
- Client state → Task wall: shows tasks (evidence: `mod/src/client/java/dev/agentcraft/client/taskwall/TaskScreen.java`)
- Client state → Agent monitors: shows live logs (evidence: `README.md`)
- Client state → Decision podium: shows questions (evidence: `README.md`)
- Decision podium → Foreman link: sends answers (evidence: `mod/src/client/java/dev/agentcraft/client/foreman/Foreman.java`)
- Client state → Diff review: shows diffs (evidence: `README.md`)
- Diff review → Foreman link: requests diff (evidence: `mod/src/client/java/dev/agentcraft/client/foreman/Foreman.java`)
- Client state → Shared library: shows memory (evidence: `README.md`)
- Client state → Agent manager: updates agents (evidence: `mod/src/client/java/dev/agentcraft/client/agents/AgentManager.java`)
- Agent manager → Agent movement: updates motion (evidence: `mod/src/client/java/dev/agentcraft/client/agents/AgentManager.java`)
- Mod initialization → HQ features: initializes HQ (evidence: `mod/src/main/java/dev/agentcraft/AgentCraft.java`)
- Mod initialization → Studio anchors: initializes anchors (evidence: `mod/src/main/java/dev/agentcraft/AgentCraft.java`)
- Agent manager → Studio anchors: uses layout (evidence: `mod/src/client/java/dev/agentcraft/client/agents/AgentManager.java`)
- HQ features → Studio anchors: reads layout (evidence: `mod/src/client/java/dev/agentcraft/client/hq/HqClientFeature.java`)
