SeekerCraft (Craft-Agent)
An LLM-driven Minecraft bot that beats the Ender Dragon. Rust + Azalea protocol client, no mods, no screenshots — a real protocol-level player that observes, plans, and executes through typed tools.
| Core question | Can an LLM autonomously survive, craft, and defeat the Ender Dragon from nothing? |
| Runtime | Pure Rust client via Azalea (MC 26.2), no server mods |
| Brain | Any OpenAI-compatible LLM (DeepSeek cache-optimized); DSH (DeepSeek Harness) bridge mode as of 2026-08-14 |
| Scale | 5 crates, 49 LLM Tools, 23 structured tasks, 10 reactive modes, spatial memory |
| Dev loop | Autonomous: gap analysis → fix → probe verify → commit (workflow notes kept locally, not shipped) |
Project nature. This project is produced through AI-assisted development ("vibe coding") as a personal experiment — deliberately adopting a Rust-only toolchain the author had never used. Implementation draws on Mindcraft (JS + mineflayer, reference for tasks/profiles/modes) and Azalea.
Highlights
- Real protocol client — joins as a vanilla player via the Azalea Rust client (MC 26.2), built-in pathfinding; no mods, no screenshots.
- 49 typed LLM tools — perceive, goto, mine, craft (2x2/3x3/smelt/enchant/brew), place, build, containers, trading, combat, meta-tools.
- 10 reactive modes — self-defense, hunting, auto-pickup, torch-placing, unstuck, elbow-room, etc., running tick-level without LLM latency (bot-side; LLM posture switched via
set_mode). - Structured task system — 23 tiered tasks (wood → stone → iron → diamond → netherite → ender dragon) with machine-checkable completion conditions.
- Spatial WorldMemory — chunk-indexed memories (resources, structures, containers, hazards, portals) with TTL forgetting and named anchors.
- DSH bridge mode — since 2026-08-14 the in-bot LLM loop is removed; DSH (DeepSeek Harness) is the sole brain driving the bot through the viewer bridge (
/api/connect+/api/bot_tool+/api/game-state+/api/goal). - Probe mode — a no-LLM tool-layer test harness that verifies tool behavior in seconds (not minutes of LLM runtime).
- Ops console (
craft-agent-ctl) — process lifecycle, goal injection, session inspection. - Autopilot — ops supervisor (10s polling): brings up viewer + connects bot, stall steering, crash recovery, anomaly detection (no code-editing logic).
Screenshots
The bot runs live in Minecraft, driven by DSH (DeepSeek Harness) as its brain; the craft-agent-viewer dashboard shows the real-time state.
| Bot running (DSH brain + live dashboard) | Dashboard (full view) | Dashboard button in DSH |
|---|---|---|
 |
 |
 |
Architecture
seeker-craft/
├── Cargo.toml # workspace root (nightly-2026-07-21)
├── crates/
│ ├── craft-agent/ # pure logic lib: types/GameTool/ToolRegistry/WorldMemory/session/task/profile/skill
│ ├── craft-agent-minecraft/ # Azalea adapter: bot + 49 tools (craft/smelt/enchant/brew/combat/farm)
│ ├── craft-agent-viewer/ # web dashboard (Axum + SSE) + DSH bridge (connect/bot_tool/game-state/goal)
│ ├── craft-agent-autopilot/ # ops supervisor (10s polling: viewer+connect, stall steering, crash recovery)
│ └── craft-agent-ctl/ # ops console
├── data/
│ ├── config/agent.example.toml # legacy LLM template (in-bot era; not used in DSH mode)
│ ├── tasks/ # 23 task JSONs (tier 1-6)
│ ├── profiles/ # 3-layer prompt templates
│ ├── blueprints/ # build blueprints
│ ├── actions/ # LLM-defined rhai scripts
│ └── dsh/craft-bot-preset/ # DSH craft-bot preset template (setup.ps1 generates into ~/.dsh)
├── scripts/
│ ├── setup.ps1 # one-shot install & configure (build + DSH bridge + preset + verify)
│ ├── start.ps1 # one-shot start viewer + connect bot
│ ├── stop.ps1 # one-shot stop
│ └── probe/*.json # tool-layer live-test scripts (no LLM)
├── tools/dsh-bridge/ # DSH bridge plugin (game_state/bot_tool/set_goal + dashboard)
└── vendor/azalea/ # local mirror of the maintained azalea fork (submodule)
azalea dependency: the manifest declares the maintained fork
XJungit/azalea(craft-agentbranch) as an https source with a pinned rev — upstream main lacks the archery/equipping APIs.vendor/azaleais the local offline mirror (submodule); during development a gitignored.cargo/config.toml[patch]redirects to it. Fresh clones compile without that patch. Fork-update workflow: see ARCHITECTURE.md.
DSH bridge runtime (since 2026-08-14)
DSH (DeepSeek Harness) brain ──HTTP──► craft-agent-viewer bridge
│ /api/connect → azalea client joins MC (account CraftAgent)
│ /api/bot_tool → dispatch one of 49 tools (GameTool::execute)
│ /api/game-state → real-time BotState snapshot (perceive format)
│ /api/goal → update ops goal
▼
craft-agent-minecraft (49 tools + WorldMemory per-20-tick scan + handler.rs reactive modes)
▼
azalea (vendor) ──► MC server (TCP)
The in-bot 13-step agent loop was removed (2026-08-14, phase-3 cleanup):
run_one_turn, auto-perceive, SelfPrompter, execute_batch, and per-turn dynamic-context injection no longer exist in Rust. The brain (DSH) now owns decision/planning/context-injection/system-prompt stability; Rust only exposes real-time bot capabilities through the viewer bridge. See ARCHITECTURE.md for details.
The 6-stage path to beating the dragon
| Tier | Stage | Tasks |
|---|---|---|
| 1 | Wood & tools | gather wood, crafting table, wooden pickaxe, stone pickaxe |
| 2 | Iron age | furnace, iron pickaxe |
| 3 | Survival gear | bread, iron armor, iron sword, shield |
| 4 | Diamond age | diamond pickaxe/sword/armor, mine to bedrock |
| 5 | Nether & magic | enchanting table, enchant sword, brewing stand, nether portal |
| 6 | Finale | netherite ingot/pickaxe, shulker box, elytra, ender dragon |
All 23 tasks (6 tiers) ship as machine-checkable JSON in data/tasks/.
Current Progress (2026-08-16 · v1.3.0)
Verified end-to-end (live server, no mods):
| Stage | Status | Evidence |
|---|---|---|
| Tier 1–2: wood → stone → iron pickaxe chain | ✅ live | bot autonomously gathered wood, crafted planks/sticks/pickaxes, and crafted an iron pickaxe via a nearby crafting table |
| Tier 3: survival gear | ✅ live | full iron armor equipped + diamond sword + shield; HP/hunger fully recovered |
| Tier 4: diamond age | ✅ live | bot followed the Y-layer hint (mine_below to Y≤16), descended to the diamond layer (Y=-59), located and mined diamond_ore with search_for_block; full diamond armor equipped |
| Tier 5: nether & magic | 🔄 in progress | nether portal built (obsidian frame + flint_and_steel ignition, visible in world memory as nether_portal); enchanting / brewing being worked |
| Tier 6: finale | ⬜ pending | netherite / shulker / elytra / ender dragon |
Milestones recently shipped (v1.0.0 release baseline):
- v1.0.0 (2026-08-15) — 1.0 release: DSH bridge mode is the only supported usage (one-shot setup/start/stop scripts +
craft-bot preset); azalea dependency moved to a maintained fork (
XJungit/azalea) with a pinned rev — fresh clones compile with no local patch;craft-agent-ctlpaths are derived at runtime (no machine-specific paths); repo URL corrected. - P154 — equip falls back to vanilla right-click equipping (use_item_air) when left_click fails
- P152/P151/P150 — mine approach-branch intermediate results, look_at before mining, approach before mining far targets (fixes dropped loot)
- P149/P148/P147 — pickup supports vertical drops; goto underground nav fix; auto-pickup after mining
- P135/P136 — recipe & Y-layer knowledge-base fixes (below)
Verification discipline: every tool-layer behavior is probe-verified against the live server (see scripts/probe/*.json) before push; Y-hint correctness was probe-verified for diamond (out-of-range hint), emerald (biome hint), and iron/coal (no false positives in-range). Full milestone table: docs/benchmarks.md.
49 LLM Tools
| Category | Tools |
|---|---|
| Perception | perceive, memory, remember, search_wiki, search_for_block |
| Movement | goto, goto_player, move_away, mine_below, mine_above, pickup, follow, stop_follow |
| Modes | set_mode |
| Mining | mine, make_obsidian |
| Interaction | interact_block, interact_entity, attack, defend, use_item, shoot, sleep |
| Craft | craft, craft_3x3, smelt, auto_craft, enchant |
| Gathering | gather, till_and_sow, harvest |
| Placement | place, build, build_blueprint, list_blueprints |
| Containers | open, chest_view, chest_withdraw, chest_deposit |
| Inventory | equip, discard, consume |
| NPC/Social | trade, give |
| Meta | chat, set_goal, run_plan, run_script, new_action, list_actions, pause_goal, resume_goal, task_complete, task_retry |
Quick Start (v1.0 · DSH bridge mode)
In v1.0 the usage is DSH bridge mode:
craft-agent-vieweronly provides the HTTP bridge (/api/connect+/api/bot_tool+/api/game-state+/api/goal), and the brain is DeepSeek Harness (DSH) — you drive the bot from DSH using three tools (game_state/bot_tool/set_goal). The steps below are verified on Windows PowerShell.
1. Prerequisites
| Dependency | Notes |
|---|---|
| Rust nightly | Pinned nightly-2026-07-21 in rust-toolchain.toml (azalea needs nightly; stable fails) |
| Git | For cloning the repo and submodules |
| Node.js ≥ 20 + pnpm | For the DSH bridge plugin |
| Minecraft Java 26.2 server | Bring your own vanilla server (LAN is fine); bot connects to localhost:4444 by default |
| DeepSeek Harness (DSH) | Bring your own install (https://github.com/deepseek-ai/deepseek-harness); this repo only generates the craft-bot preset |
Why DSH is not bundled: DSH is the external "brain" (the same harness you code with); bundling it would duplicate the whole toolchain and pin a version. You install DSH once;
setup.ps1then registers the craft-bot preset into your existing~/.dsh.
2. Clone (with azalea submodule)
git clone --recurse-submodules https://github.com/XJungit/seeker-craft.git
cd seeker-craft
The azalea dependency is a maintained fork (
XJungit/azalea,craft-agentbranch) — upstream lacks the APIs the bot needs for archery/equipping. The manifest declares the fork's https source with a pinned rev, so a fresh clone compiles with no local patch. See ARCHITECTURE.md → "azalea fork maintenance".
3. One-shot install & configure (setup.ps1)
.\scripts\setup.ps1
Idempotent and repeatable. It:
- Checks prerequisites (cargo / git / node / pnpm; prompts installs if missing)
- Runs
cargo build --workspace - Configures the DSH bridge plugin (registers into
~/.dsh+ links deps +pnpm install) - Generates the craft-bot preset (
~/.dsh/.agent-presets/craft-bot), substituting local path placeholders - Copies
.env.example→.envif absent - Runs the DSH plugin verification script
Only want to build, not touch DSH?
.\scripts\setup.ps1 -SkipDsh(skips steps 3/4). Skip the build?-SkipBuild.
4. Start MC server + viewer + connect bot
# First start your MC 26.2 server (listening on localhost:4444)
# One shot: build viewer → start viewer → connect bot (polls until ready)
.\scripts\start.ps1
start.ps1 parameters (all have defaults):
| Parameter | Default | Notes |
|---|---|---|
-Goal |
explore the world… | Operational goal shown in the viewer |
-Steps |
0 (infinite) |
Number of steps |
-Port |
8080 |
Viewer HTTP port |
-Mc |
localhost:4444 |
MC server address |
-Username |
CraftAgent |
Bot name |
Or step-by-step with craft-agent-ctl:
cargo run -p craft-agent-ctl -- viewer "explore the world" 0 # viewer only
cargo run -p craft-agent-ctl -- start # connect bot
cargo run -p craft-agent-ctl -- status # verify running=true
5. Drive the bot from DSH (core usage)
- Open DeepSeek Harness, create/enter a craft-bot preset session
- A Craft Bot dashboard embeds on the right side (live bot state)
- Call the three tools in conversation:
game_state() # perceive: position/health/hunger/inventory/nearby/memory
bot_tool(name:"mine", args:{x:.., y:.., z:..}) # execute one of the 49 tools
set_goal("Collect 24 iron ore and smelt into ingots") # set the ops goal
Tool names are a stable contract (
tools_azalea.rs::ALL_TOOL_NAMES, 49 total). Auto-corrections (mine-on-air → nearest solid; interaction → auto-approach ≤2.5m) are built in — pass the intended target directly.
6. Stop
.\scripts\stop.ps1 # stops viewer/autopilot (does not affect MC server or DSH)
Build & test (for development)
cargo build --workspace
cargo test -p craft-agent --lib
cargo test -p craft-agent-minecraft --features azalea-bot --lib
Probe mode (test the tool layer WITHOUT the LLM, seconds not minutes)
# Single command
cargo run -p craft-agent-minecraft --example azalea_probe --features azalea-bot -- 4444 --cmd "equip iron_helmet helmet"
# Script (see scripts/probe/*.json)
cargo run -p craft-agent-minecraft --example azalea_probe --features azalea-bot -- 4444 --script scripts\probe\smoke.json
The LLM is provided by DSH (the brain) — there is no separate LLM backend configuration file in this repo.
data/config/agent.example.tomlis a legacy template from the in-bot era (kept for reference only; not used in DSH mode).
Documentation
| Doc | What it covers |
|---|---|
| ARCHITECTURE.md | Layered architecture, DSH bridge runtime, module layout |
| docs/mindcraft-gap.md | Mindcraft parity audit + prioritized backlog |
| docs/benchmarks.md | Test baselines, probe coverage, cache hit rates, Ender-Dragon progress |
| docs/adr.md | Architecture decision records |
| docs/README.md | Full documentation index (tutorials, design archive) |
| CHANGELOG.md | Versioned change log |
| SECURITY.md | Security policy & vulnerability reporting |
| CONTRIBUTING.md | How to develop, test & submit a fix |
Docs are also published to GitHub Pages (rustdoc + docs) — see the docs workflow.
Related Projects
- Mindcraft — JS + mineflayer LLM bot; reference for tasks/profiles/modes
- Azalea — Rust Minecraft client protocol library
- XJungit/azalea — maintained fork used by this project (adds
stop_use_item/use_item_air/force_missfor archery & equipping;craft-agentbranch)
License
MIT — see AUTHORS for maintainers. Cite via CITATION.cff.
No comments yet. Be the first to write one.