1e3b36a9a1
* fix(mindcraft-skills): hard timeout on every skill call mc_avoid_enemies (and 7 other tools) wrapped only in safeCall without a withTimeout. When mindcraft's underlying pathfinder/pvp goal couldn't be satisfied, the call never resolved — the Pi tick loop blocked forever. Observed live: mc_avoid_enemies pending >10 minutes after one mc_observe. safeCall now takes timeoutMs (default 30s) and wraps withTimeout itself, so every tool gets a hard ceiling. Per-tool overrides: - goToPosition / goToNearestBlock: 120s / 90s (unchanged from before) - defendSelf / avoidEnemies: 45s - stay: secs*1000 + 10s - craft / consume / pickup / place: 30s - equip: 15s collectBlock still uses its bespoke per-iter 75s loop. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(runtime): script-driven reflex daemon + Ink TUI dashboard Pure-Pi runtime had three failure modes in practice: - slow: 20-60s per decision because LLM was in the hot path - expensive: every tick (defend, eat, idle) paid for a reasoning pass - invisible: required tmux capture-pane to know what the bot was doing New runtime/ layer is a long-running Node daemon that owns the MC connection, ticks a priority-ordered reflex chain (defend > eat > sleep > idle) with NO LLM in the hot path, and exposes status + commands over a Unix-socket IPC. tui/ is an Ink dashboard that attaches over IPC and can detach freely — multiple TUI clients can connect at once. Pi/Codex are still available, but as on-demand escalation: TUI hotkey 'a' spawns `pi -p "<prompt>"` as a subprocess and streams stdout into the dashboard. The self-improvement loop (proposals → operator approval → Pi-driven patch → hot reload) is documented in docs/runtime.md but not yet wired. Reflex bodies are stubs today — they log decisions but don't drive Mineflayer actions yet. The priority chain, IPC contract, and TUI are fully working; subsequent commits will fill in defend/eat/sleep bodies and wire automatic escalation. Run with `npm run bot` + `npm run tui`. Pi-only fallback stays at `npm run agent`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Yuriy Mayatnikov <mayatnikov@me.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
197 lines
12 KiB
Markdown
197 lines
12 KiB
Markdown
# pepa-pi-bot
|
|
|
|
> A universal, autonomous, self-extending Minecraft player. Built on [Mineflayer](https://github.com/PrismarineJS/mineflayer) with a hybrid runtime: a fast script-driven reflex loop for the everyday, and headless [Pi](https://pi.dev) escalation for the hard bits. Works against **any** Minecraft Java server — vanilla, Paper, Spigot, Fabric, Forge, online-mode or cracked, modded or vanilla.
|
|
|
|
The bot is **not a finished application**. It is a seed: a Mineflayer body, a tiny reflex brain, and a hand-off to whatever Minecraft server you point it at. The bot is expected to grow its own toolset over time — writing new reflexes, installing skills, adapting its behaviour as it plays.
|
|
|
|
The name `pepa-pi-bot` is just the project's name (`pepa` from the original test server, `pi` from the original runtime). The bot itself is server-agnostic.
|
|
|
|
## Runtime modes
|
|
|
|
Two ways to run the bot. The hybrid runtime is the default — Pi-only is a fallback for experiments.
|
|
|
|
| Mode | Entry | When to use |
|
|
|---|---|---|
|
|
| **Hybrid runtime** (recommended) | `npm run bot` + `npm run tui` | Day-to-day. Script-driven reflex tick + Ink TUI dashboard + Pi/Codex called only on demand. Fast, cheap, observable. |
|
|
| **Pi-only** (fallback) | `npm run agent` | When you want every decision to go through an LLM (rare, but useful for experiments and code-writing sessions). |
|
|
|
|
See [`docs/runtime.md`](./docs/runtime.md) for the full hybrid runtime guide, IPC protocol, TUI hotkeys, and the self-improvement loop.
|
|
|
|
## Concept
|
|
|
|
Most Minecraft AI bots ship as monolithic projects: hard-coded actions, fixed prompts, a single LLM provider, sometimes a single target server. This repo flips that around with a layered runtime.
|
|
|
|
```
|
|
┌──────────────────────────────────────────────────────────┐
|
|
│ TUI (Ink) — operator dashboard, attaches via Unix sock │
|
|
│ status / live log / MC chat / hotkeys / ask-Pi │
|
|
└──────────────────────┬───────────────────────────────────┘
|
|
│ newline-JSON
|
|
▼
|
|
┌──────────────────────────────────────────────────────────┐
|
|
│ runtime/bot.js — long-running Node daemon │
|
|
│ ├── Mineflayer client (MC TCP, AuthMe, chat, events) │
|
|
│ ├── Reflex loop (defend > eat > sleep > idle) │
|
|
│ │ pure script — no LLM in the hot path │
|
|
│ └── pi-bridge — spawn `pi -p` only on demand │
|
|
└──────────────────────┬───────────────────────────────────┘
|
|
│ TCP 25565 (any host/port)
|
|
▼
|
|
ANY Minecraft Java server (configured in .env)
|
|
```
|
|
|
|
The reflex loop is the brain stem. Pi is the cortex — called only when the reflex loop is genuinely stuck, or when the operator asks for help via the TUI. Mineflayer is the body. The skills, reflexes, and supervision loop are meant to grow over time — both by hand and by the bot itself proposing patches.
|
|
|
|
## Prerequisites
|
|
|
|
| Tool | Why | How to get it |
|
|
|---|---|---|
|
|
| **Pi** ≥ `0.75` | The agent runtime. Reads `AGENTS.md`, loads skills, calls the LLM. | `curl -fsSL https://pi.dev/install.sh \| sh` |
|
|
| **Node.js** ≥ `20` | Required by Pi and by Mineflayer. | `brew install node` / `nvm install 20` |
|
|
| **An LLM credential** | One of: OpenAI / Anthropic / Google API key, or an OAuth-authenticated subscription (`/login` inside Pi). ChatGPT Pro and Claude Max work via OAuth on supported providers. | See [Authentication](#authentication) |
|
|
| **Access to some Minecraft server** | The bot joins as a real player. Cracked or premium, online-mode or offline, doesn't matter — configure it in `.env`. | — |
|
|
| **Network access to that server** | Direct TCP to `host:port`. | — |
|
|
|
|
> The bot does **not** need its own Minecraft client install, server admin access, RCON, or any server-side plugin. It joins as a vanilla player over the standard protocol.
|
|
|
|
## Quickstart
|
|
|
|
```bash
|
|
# 1. Clone + configure
|
|
git clone git@github.com:xmatic-squad/pepa-pi-bot.git
|
|
cd pepa-pi-bot
|
|
cp .env.example .env
|
|
$EDITOR .env # set MC_HOST, MC_USERNAME, auth mode, AuthMe password, etc.
|
|
|
|
# 2. Install Node deps
|
|
npm install
|
|
|
|
# 3. (Optional) Authenticate Pi for the escalation hotkey
|
|
pi /login # OAuth flow — ChatGPT Pro / Claude Max
|
|
# or export OPENAI_API_KEY / ANTHROPIC_API_KEY
|
|
|
|
# 4. Run the bot — two terminals
|
|
# Terminal 1: the daemon (logs in stdout, persists state under state/<host>/)
|
|
npm run bot
|
|
|
|
# Terminal 2: the dashboard (Ink TUI). Hotkeys: p/s/r/c/a/q.
|
|
npm run tui
|
|
```
|
|
|
|
The TUI auto-reconnects to the bot if you restart it. Press `q` to leave the TUI; the bot keeps running.
|
|
|
|
> Want the LLM-driven, single-process flavour? `npm run agent` launches the original Pi runtime instead. See [`docs/runtime.md`](./docs/runtime.md) for the trade-offs.
|
|
|
|
### Sending chat or asking Pi from the TUI
|
|
|
|
- Press **`c`** in the TUI to enter chat mode — type, Enter sends into MC chat (rate-limited per `.env`).
|
|
- Press **`a`** to enter ask-Pi mode — type a prompt, Enter spawns `pi -p "<prompt>"`. Output streams into the Pi panel without leaving the TUI.
|
|
|
|
### TUI hotkeys cheatsheet
|
|
|
|
| Key | Effect |
|
|
|---|---|
|
|
| `p` | Pause / resume the reflex loop (MC connection stays). |
|
|
| `s` | Stop the bot (graceful disconnect + cleanup). |
|
|
| `r` | Force a fresh status snapshot. |
|
|
| `c` | Send a chat message into MC. |
|
|
| `a` | Ask Pi (one-shot subprocess). |
|
|
| `q` | Quit the TUI — bot keeps running. |
|
|
|
|
## Authentication
|
|
|
|
Two dimensions:
|
|
|
|
**1. Minecraft auth.** Configured in `.env` via `MC_AUTH_MODE`:
|
|
- `offline` — cracked servers. Any nickname works. No external auth call.
|
|
- `microsoft` — premium / online-mode servers. Mineflayer handles the device-code flow on first connect and caches the token in `~/.minecraft-auth/`.
|
|
|
|
**2. LLM auth.** Pi supports **15+ providers** and two credential modes:
|
|
- **OAuth subscription login** — `pi` then `/login` inside the TUI. Suitable for ChatGPT Plus/Pro, Claude Max, and other subscriptions that ship an OAuth flow. No metered API billing.
|
|
- **API key environment variables** — `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, etc. Metered, but no UI prompt.
|
|
|
|
You can mix providers via `--provider openai --model gpt-5` at launch — cheaper models for idle ticks, smarter ones for hard decisions.
|
|
|
|
## How the agent extends itself
|
|
|
|
Pi has first-class support for three growth surfaces:
|
|
|
|
- **`skills/`** — Markdown-defined capabilities Pi can invoke. The agent can `Write` new ones at runtime when it discovers a missing capability.
|
|
- **`extensions/`** — TypeScript modules registering new tools, commands, or UI tweaks. Installed project-locally via `pi install -l npm:<pkg>` / `pi install -l git:<url>`, or written in-tree.
|
|
- **`prompts/`** — Reusable prompt templates. Useful for cron-driven tick prompts ("what should I do next minute?").
|
|
|
|
The opening `AGENTS.md` instructs the agent to start by writing a `mineflayer-bridge` extension that can:
|
|
- connect to the configured MC server (any host/port/version)
|
|
- handle the configured auth mode (offline or microsoft)
|
|
- if a login plugin like AuthMe is present, perform `/register` and `/login` from a password supplied in `.env`
|
|
- emit world events back into the agent loop
|
|
- expose `chat / move / dig / place / equip / attack` as Pi tools
|
|
|
|
Everything beyond that — farming, exploration, base-building, player interaction, server-specific quirks — should emerge from the agent itself.
|
|
|
|
### Everything in the repo
|
|
|
|
A hard rule, mirrored in `AGENTS.md`: every artefact the agent produces **lives in this repo**, never in the user's `~/.pi/` directory. That includes skills, extensions, prompt templates, project Pi settings (`.pi/settings.json`), and per-server state (`state/<MC_HOST>/`).
|
|
|
|
The point is reproducibility and **community growth**: a fresh `git clone` should bring along every skill any contributor has written. Pi's own built-in skills (`skill-creator`, `agent-browser`, etc.) stay user-global — the agent is allowed to *use* them, but anything it *authors* lands under `./skills/` or `./extensions/` here.
|
|
|
|
See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the skill format and how to propose changes.
|
|
|
|
## Project layout
|
|
|
|
```
|
|
pepa-pi-bot/
|
|
├── README.md ← you are here
|
|
├── AGENTS.md ← seed prompt, loaded by the Pi-only runtime
|
|
├── .env.example ← all required env vars, no secrets
|
|
├── package.json ← node deps + scripts (`bot`, `tui`, `agent`)
|
|
├── runtime/ ← hybrid runtime (script reflex + IPC server)
|
|
│ ├── bot.js long-running Mineflayer daemon
|
|
│ ├── reflex.js priority-ordered behaviours, no LLM
|
|
│ ├── perceive.js snapshot builder
|
|
│ ├── ipc-server.js Unix-socket server
|
|
│ ├── ipc-protocol.js shared IPC contract
|
|
│ └── pi-bridge.js spawn `pi -p` on demand
|
|
├── tui/ ← Ink TUI dashboard
|
|
│ ├── tui.tsx
|
|
│ └── ipc-client.js
|
|
├── skills/ ← markdown skills (grown by bot or operator)
|
|
├── extensions/ ← Pi extensions (mindcraft-skills, mineflayer-bridge)
|
|
├── prompts/ ← reusable prompt templates
|
|
└── docs/
|
|
├── runtime.md hybrid runtime guide (start here)
|
|
├── architecture.md longer-form design notes
|
|
├── memory-model.md per-server state layout
|
|
├── roadmap.md phased plan
|
|
└── …
|
|
```
|
|
|
|
## Safety boundaries
|
|
|
|
Server-agnostic but with hard defaults the agent must respect on any server it joins:
|
|
|
|
- **Never request OP / admin rights** in chat.
|
|
- **Never break or modify other players' builds** without explicit human request.
|
|
- **Never spam chat** — built-in rate limit (`CHAT_RATE_LIMIT_PER_MIN` in `.env`).
|
|
- **Never leak secrets** from `.env` (auth passwords, API keys) into chat, world signs, books, commits, or web fetches.
|
|
- **No destructive bash** in the repo (`rm -rf`, force pushes) without operator confirmation.
|
|
- **Stop and wait** if kicked or banned — do not auto-reconnect indefinitely.
|
|
|
|
These are mirrored in `AGENTS.md` and re-stated at the top of any system prompt that overrides it.
|
|
|
|
## Status
|
|
|
|
🌳 **Phase 0 — Body** done. Bridge online, AuthMe handled, `hello` sent. See `skills/server-onboarding.md`.
|
|
|
|
🌳 **Phase 1 — Presence** implemented and operator trust wired: the bridge stays online with bounded reconnects, keeps a rolling chat buffer, exposes status/recent-chat/operator/escalation tools, applies `OPERATOR_USERNAMES` as scope-only trust, and can prompt the Pi loop to reply sparingly.
|
|
|
|
🌿 **Phase 2 — Locomotion/build rails** in progress: `mineflayer-pathfinder` is wired with guarded `mc_goto`, plus `mc_build_pyramid_5x5` for the operator-approved empty-site pyramid task. Dynamic following is still pending. Phase 5 self-extension is documented and in progress; Phase 6 escalation logging is implemented.
|
|
|
|
🌱 **Phase 3 — Goal-driven autonomy** seeded: [`docs/memory-model.md`](./docs/memory-model.md) defines shared-knowledge vs personal-memory; per-server `goal.md` / `plan.md` / `current-task.json` / `diary/` shape autonomous behaviour. Kickoff via [`prompts/live-your-life.md`](./prompts/live-your-life.md).
|
|
|
|
Full plan: [`docs/roadmap.md`](./docs/roadmap.md). Memory layout: [`docs/memory-model.md`](./docs/memory-model.md). Day-to-day judgement: "Operating principles" in [`AGENTS.md`](./AGENTS.md).
|
|
|
|
## License
|
|
|
|
[MIT](./LICENSE) © [xmatic-squad](https://github.com/xmatic-squad)
|