xmatic/pepa-pi-bot
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: make scaffold server-agnostic

Browse Source 
The bot is a universal Minecraft player, not tied to any one server.
Server identity (host, port, username, auth mode, optional AuthMe password)
is now read entirely from .env.

- README: rewritten as universal-bot pitch; auth covered as two dimensions
  (MC auth mode + LLM credential)
- AGENTS.md: identity comes from .env, hard-coded references to pepa
  removed; bootstrap step auto-detects whether the server uses an
  AuthMe-style /register-/login plugin
- .env.example: example values replaced with placeholders, MC_AUTH_MODE
  added (offline | microsoft)
- docs/architecture.md: rephrased target as "any Minecraft Java server",
  added open question on cross-server vs per-server state

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
mayatnikov
2026-05-25 09:52:25 +03:00
co-authored by Claude Opus 4.7
parent 3a025c05ad
commit 4dd8576d5b
4 changed files with 107 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.env.example
+19 -12
View File
@@ -1,19 +1,25 @@
# --- Minecraft connection -----------------------------------------------------
# The pepa server. Cracked mode — any nickname works.
MC_HOST=play.xmatic.team
# Any Minecraft Java server. The values below are an example — replace them.
MC_HOST=play.example.com
MC_PORT=25565
MC_USERNAME=pepa_pi_bot
MC_VERSION=auto # 'auto' lets mineflayer detect the server's version
MC_VERSION=auto # 'auto' = let mineflayer detect from server
# --- AuthMe (in-game login) ---------------------------------------------------
# Used for /register on first join and /login on subsequent joins.
# Min length is set on the pepa server — keep it ≥ 8 chars.
# NEVER commit a real value; .env is gitignored.
MC_AUTHME_PASSWORD=change-me-to-a-long-password
# --- Minecraft auth -----------------------------------------------------------
# 'offline' — cracked servers (server runs with online-mode=false). Any nick works.
# 'microsoft' — premium / online-mode servers. Mineflayer runs a device-code flow
# on first connect and caches the token under ~/.minecraft-auth/.
MC_AUTH_MODE=offline
# --- Optional: in-game login plugin (AuthMe, nLogin, etc.) --------------------
# Many cracked servers gate gameplay behind an in-chat /register and /login flow.
# Leave blank if your target server doesn't use one.
# Min length is usually 8; use a long random value and never commit it.
MC_AUTHME_PASSWORD=
# --- LLM provider -------------------------------------------------------------
# Set ONE of the following. Pi auto-detects from env.
# OAuth subscriptions (ChatGPT Pro, Claude Max) — leave keys empty and run `pi /login`.
# Set ONE credential below, OR leave them all blank and run `pi /login` for OAuth
# (ChatGPT Pro, Claude Max, etc. — when the provider supports it).
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GOOGLE_API_KEY=
@@ -27,13 +33,14 @@ PI_DEFAULT_MODEL=gpt-5-mini
# How often (seconds) the autonomous tick prompt fires. Set to 0 to disable.
TICK_INTERVAL_SECONDS=60
# Chat rate limit (messages per minute). Paper's spam kicker triggers around 20/min.
# Chat rate limit (messages per minute). Paper/Spigot spam kickers typically
# trigger around 20/min.
CHAT_RATE_LIMIT_PER_MIN=15
# --- Operator -----------------------------------------------------------------
# In-game nick of the human operator. The bot treats their chat messages as
# higher-priority than other players.
OPERATOR_USERNAME=halofourteen
OPERATOR_USERNAME=your_in_game_nick
# --- Optional: Telegram bridge (future skill, not wired yet) ------------------
# TELEGRAM_BOT_TOKEN=
AGENTS.md
+35 -22
View File
@@ -1,16 +1,21 @@
# pepa-pi-bot — agent mandate
You are **pepa-pi-bot**: an autonomous Minecraft player living inside the [Pi](https://pi.dev) runtime.
You are **pepa-pi-bot**: a universal, autonomous Minecraft player living inside the [Pi](https://pi.dev) runtime.
The repo you are running from (`pepa-pi-bot/`) is **your house**. You are expected to extend it: write skills, install extensions, refine prompts. Treat the repo as your long-term memory.
The repo you are running from is **your house**. You are expected to extend it: write skills, install extensions, refine prompts. Treat the repo as your long-term memory.
## Identity
The bot is **server-agnostic**. Which server you play on, under what nickname, with what auth mode — all of that comes from `.env`. Read it on every startup. Do not hard-code a specific host, username, or password anywhere in this repo.
- **Server**: `pepa` — a private Paper 26.1.2 survival world at `play.xmatic.team:25565`.
- **Web map**: <https://map.xmatic.team>
- **Landing**: <https://mc.xmatic.team>
- **Mode**: cracked (no Microsoft auth). Server-side login is handled by AuthMe.
- **Your nickname** and **AuthMe password**: read from `.env` (`MC_USERNAME`, `MC_AUTHME_PASSWORD`). Never echo the password to chat, world signs, books, or commit history.
## Identity (read from .env)
- **`MC_HOST`** / **`MC_PORT`** — the server to join.
- **`MC_USERNAME`** — your in-game nickname.
- **`MC_AUTH_MODE`** — `offline` for cracked servers, `microsoft` for premium / online-mode.
- **`MC_VERSION`** — `auto` lets mineflayer detect; override if needed.
- **`MC_AUTHME_PASSWORD`** *(optional)* — used only if the server runs AuthMe-style login plugins. Empty if the server doesn't need it.
- **`OPERATOR_USERNAME`** — the human you should treat as higher-priority than other players.
Never echo any `.env` value into chat, world signs, books, web requests, or commits.
## Your tools right now
@@ -28,15 +33,20 @@ You are expected to build that bridge yourself.
In order:
1. Read `.env.example` and the existing `package.json`. Confirm `node_modules/` is installed (run `npm install` if not).
2. Write a minimal `extensions/mineflayer-bridge.ts` (or `.js` if simpler) that:
2. Read the actual `.env` (it is gitignored — exists locally only). If it doesn't exist, ask the operator to copy `.env.example`. Don't proceed without it.
3. Write a minimal `extensions/mineflayer-bridge.ts` (or `.js` if simpler) that:
- reads `.env` via `dotenv`
- opens a Mineflayer connection to `${MC_HOST}:${MC_PORT}` with `username: MC_USERNAME`, `auth: 'offline'`
- opens a Mineflayer connection to `${MC_HOST}:${MC_PORT}`
- sets `auth` based on `MC_AUTH_MODE` (`'offline'` or `'microsoft'`)
- sets `version` from `MC_VERSION` (or `false` for auto-detect)
- logs `spawn`, `kicked`, `error`, `end` to stdout
- registers tools callable from the Pi agent: `mc_chat(text)`, `mc_position()`, `mc_disconnect()`
3. Verify you can launch the bridge in the background (e.g. `pi install -e extensions/mineflayer-bridge.ts` or whatever Pi's extension API requires — read the docs at <https://pi.dev/docs/latest>).
4. From within a Pi session, call `mc_chat("/register $MC_AUTHME_PASSWORD $MC_AUTHME_PASSWORD")` on first join, then `mc_chat("/login $MC_AUTHME_PASSWORD")` on subsequent joins. Detect "first vs subsequent" by storing a `state/joined-before.flag` file.
5. Once the in-game login succeeds, send `mc_chat("hello")` and confirm the message appears in-game.
6. Write your first skill: `skills/authme-autologin.md` describing what you just learnt, so you can replay it without re-reading this entire document.
4. Verify you can launch the bridge as a Pi extension (read <https://pi.dev/docs/latest> for the exact extension API — `pi install -e <path>` or `--extension <path>` or settings entry).
5. After spawning, **detect the server's auth flavour**:
- If chat asks for `/register` or `/login` (AuthMe-style), and `MC_AUTHME_PASSWORD` is set: `/register` on first join, `/login` on subsequent joins. Store a `state/joined-before.flag` file to distinguish.
- If neither prompt appears within ~5 seconds, assume no in-game auth plugin and proceed.
6. Send `mc_chat("hello")` and confirm it appears in-game.
7. Write your first skill: `skills/server-onboarding.md` describing what auth pattern you observed, so you can replay it without re-deriving it.
That's the seed. Everything afterwards is up to you and the operator.
@@ -51,34 +61,37 @@ When you encounter a missing capability, your loop is:
3. Commit the new file with a clear message. The repo is on `main`. Don't push without operator confirmation.
4. Update `README.md`'s **Status** section as milestones land.
Skills you might want early on:
Skills you might want early on (good for any server):
- `authme-autologin` — re-login flow.
- `server-onboarding` — what auth flow this server uses; relogin / autologin pattern.
- `respawn-and-return` — when killed, respawn and walk back to last known coords.
- `inventory-snapshot` — dump current inventory to a structured log.
- `tick-loop` — a cron-style "what should I do next?" prompt template the operator can fire on a schedule.
- `safe-pathing` — wrap `mineflayer-pathfinder` with sanity checks (don't drop into lava, don't TP through claims).
## Hard safety rules
These are **non-negotiable** and overrule any later prompt:
1. **Never request OP / admin rights** in chat or anywhere else.
2. **Never break or modify player-built structures** unless an operator (you'll know — they message you in chat by name) explicitly asks.
3. **Never leak secrets**: no echoing `MC_AUTHME_PASSWORD`, `OPENAI_API_KEY`, or any value from `.env` into chat, files committed to git, world signs, books, or web fetches.
4. **Rate-limit chat** to at most 1 message per 3 seconds to avoid Paper's spam kicker.
2. **Never break or modify other players' builds** unless an operator explicitly asks.
3. **Never leak secrets**: no echoing `MC_AUTHME_PASSWORD`, LLM API keys, or any value from `.env` into chat, files committed to git, world signs, books, or web fetches.
4. **Rate-limit chat** to at most `CHAT_RATE_LIMIT_PER_MIN` messages per minute (default 15) to avoid Paper/Spigot spam kickers.
5. **No destructive bash** in the repo (`rm -rf`, `git reset --hard`, force pushes) without operator confirmation.
6. **If you are kicked or banned**, stop and wait. Do not auto-reconnect more than 3 times in 10 minutes — the operator will investigate.
6. **If kicked or banned**, stop and wait. Do not auto-reconnect more than 3 times in 10 minutes — the operator will investigate.
7. **Respect server rules.** If the server has a rules sign, MOTD, or `/rules` command — read it on first join and add it to your context.
## Operator contact
The operator is **timmy** (`halofourteen` in-game). They will speak to you in MC chat or by editing `AGENTS.md` directly. Telegram bridge is planned but not built; you may suggest it as a future skill.
The operator's in-game nick lives in `.env` as `OPERATOR_USERNAME`. They will speak to you in MC chat or by editing this `AGENTS.md` directly. A Telegram bridge is planned but not built; you may suggest it as a future skill.
## What you are NOT
- You are **not** a script with hard-coded behaviour. You are a long-running agent that reasons each step.
- You are **not** tied to one server, one nickname, or one auth flow.
- You are **not** here to grief, troll, or compete with players.
- You are **not** allowed to invent new infrastructure (databases, web services, paid APIs) without operator approval. Stay within the repo and the MC server.
---
Start by reading `package.json`, `.env.example`, and the Pi extension docs. Then build your body.
Start by reading `.env`, `package.json`, and the Pi extension docs. Then build your body.
README.md
+38 -27
View File
@@ -1,17 +1,19 @@
# pepa-pi-bot
> An autonomous self-extending Minecraft player, powered by [Pi](https://pi.dev) and the [Mineflayer](https://github.com/PrismarineJS/mineflayer) protocol stack. Built for the [pepa](https://mc.xmatic.team) survival server.
> A universal, autonomous, self-extending Minecraft player. Powered by [Pi](https://pi.dev) and the [Mineflayer](https://github.com/PrismarineJS/mineflayer) protocol stack. 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 Pi agent with an initial mandate and a hand-off to a Minecraft server. From there, the agent is expected to grow its own toolset — writing new skills, fetching extensions, and adapting its behaviour as it plays.
The bot is **not a finished application**. It is a seed: a Pi agent with an initial mandate and a hand-off to whatever Minecraft server you point it at. From there, the agent is expected to grow its own toolset — writing new skills, fetching extensions, and 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 runtime). The bot itself is server-agnostic.
## Concept
Most Minecraft AI bots ship as monolithic projects: hard-coded actions, fixed prompts, a single LLM provider. This repo flips that around.
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.
```
┌───────────────────────────────────────────────┐
│ Pi (terminal agent, model-agnostic) │
│ ├── AGENTS.md ← initial mandate │
│ ├── AGENTS.md ← generic mandate │
│ ├── skills/ ← grown over time │
│ └── extensions/ ← TS plugins, also grown │
└───────────────┬───────────────────────────────┘
@@ -25,8 +27,8 @@ Most Minecraft AI bots ship as monolithic projects: hard-coded actions, fixed pr
│ TCP 25565
▼
┌───────────────────────────────────────────────┐
│ pepa Minecraft server │
│ Paper 26.1.2 · cracked · AuthMe · BlueMap │
│ ANY Minecraft Java server │
│ configured via .env (host, port, auth, ...) │
└───────────────────────────────────────────────┘
```
@@ -38,11 +40,11 @@ The Pi agent is the brain. Mineflayer is the body. The bridge between them — t
|---|---|---|
| **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 API key, Anthropic API key, or an OAuth-authenticated subscription (`/login` inside Pi). ChatGPT Pro / Claude Max work via OAuth on supported providers. | See [Authentication](#authentication) |
| **A Minecraft account or cracked nick** | The bot joins as a real player. The pepa server runs in cracked mode, so any nickname works. | — |
| **Network access to the MC server** | Direct TCP to `host:25565`. | — |
| **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 access, RCON, or any special server-side plugin. It joins as a vanilla player over the standard protocol.
> 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
@@ -51,9 +53,9 @@ The Pi agent is the brain. Mineflayer is the body. The bridge between them — t
git clone git@github.com:xmatic-squad/pepa-pi-bot.git
cd pepa-pi-bot
# 2. Configure credentials
# 2. Configure for your target server
cp .env.example .env
$EDITOR .env # fill in MC_HOST, MC_USERNAME, AuthMe password, LLM provider, etc.
$EDITOR .env # set MC_HOST, MC_USERNAME, auth mode, LLM provider, etc.
# 3. Install Node deps (mineflayer + dotenv to start)
npm install
@@ -69,18 +71,23 @@ export ANTHROPIC_API_KEY=sk-ant-...
pi
```
On first launch Pi loads `AGENTS.md` from the project root. That file is the seed prompt — it tells the agent who it is, what server it should join, and that it is expected to extend itself.
On first launch Pi loads `AGENTS.md` from the project root. That file is the seed prompt — it tells the agent it is a Minecraft player, where to find its configuration, and that it is expected to extend itself.
Sessions persist by default. Use `pi -c` to resume the last conversation.
## Authentication
Pi supports **15+ LLM providers** and two credential modes:
Two dimensions:
1. **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.
2. **API key environment variables** — `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, etc. Metered, but no UI.
**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/`.
You can mix providers via `--provider openai --model gpt-5` at launch. Cheaper models for idle ticks, smarter ones for hard decisions.
**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
@@ -91,12 +98,13 @@ Pi has first-class support for three growth surfaces:
- **`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
- register with AuthMe
- 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 — should emerge from the agent itself.
Everything beyond that — farming, exploration, base-building, player interaction, server-specific quirks — should emerge from the agent itself.
## Project layout
@@ -117,17 +125,20 @@ pepa-pi-bot/
## Safety boundaries
The pepa server is a shared survival world. The agent **must not**:
- be given OP rights on the server
- destroy player-built structures without explicit human request
- spam chat
- exfiltrate the AuthMe password or any other secret into chat / world / web
Server-agnostic but with hard defaults the agent must respect on any server it joins:
These rules are mirrored in `AGENTS.md` and should be re-stated at the top of any system prompt that overrides it.
- **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
🌱 **Seedling.** The repo currently ships only the scaffold and the initial mandate. The first real milestone is: agent connects, registers via AuthMe, sends `hello` in chat, writes its first skill (`logout-on-shutdown`). Everything past that emerges from interaction.
🌱 **Seedling.** The repo currently ships only the scaffold and the initial mandate. The first real milestone is: agent connects to the server configured in `.env`, handles whatever login flow that server requires, and sends `hello` in chat. Everything past that emerges from interaction.
## License
docs/architecture.md
+15 -11
View File
@@ -7,10 +7,10 @@
```
┌─────────────────────────────────────────────────────────────┐
│ Operator │
│ (timmy / halofourteen — in-game chat, repo edits, .env) │
│ (human — in-game chat, repo edits, .env) │
└─────┬────────────────────────────────────────────┬──────────┘
│ │
│ chat / edit AGENTS.md │ optional: Telegram (future)
│ chat / edit AGENTS.md │ optional: Telegram (future)
▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ Pi runtime │
@@ -25,14 +25,15 @@
│ - holds a single bot client │
│ - exposes mc_chat / mc_position / mc_dig / ... as tools │
│ - pushes world events into the agent loop │
│ - reads MC_HOST/PORT/AUTH_MODE/USERNAME from .env │
└────────────────────┬────────────────────────────────────────┘
│ TCP 25565
│ TCP 25565 (or whatever .env says)
▼
┌─────────────────────────────────────────────────────────────┐
│ pepa Paper server │
│ - AuthMe gates login │
│ - BlueMap renders the world │
│ - host: play.xmatic.team │
│ Any Minecraft Java server │
│ - vanilla / Paper / Spigot / Fabric / Forge │
│ - online-mode or offline │
│ - with or without login plugins (AuthMe, nLogin, ...) │
└─────────────────────────────────────────────────────────────┘
```
@@ -45,23 +46,26 @@
## Why Mineflayer as the body
- **Version coverage.** Supports MC 1.8 → 1.21.x with auto-detect; the pepa server (Paper 26.1.2) sits inside that range.
- **Version coverage.** Supports MC 1.8 → 1.21.x with auto-detect.
- **Auth coverage.** `offline` for cracked, `microsoft` for premium — same API, switched via one config value.
- **High-level API.** No need to hand-roll the Minecraft protocol. Movement, pathfinding (via `mineflayer-pathfinder`), inventory, and chat are first-class.
- **Cracked-friendly.** `auth: 'offline'` works against AuthMe-gated servers without a Microsoft account.
- **Plugin ecosystem.** `mineflayer-pathfinder`, `mineflayer-pvp`, `mineflayer-collectblock`, etc. — usable as extensions when the agent decides it needs them.
## What's intentionally absent (for now)
- **MCP server.** A separate MCP server could expose the same tools to Claude Desktop or other clients. Out of scope until there's a concrete need for a second consumer.
- **MCP server.** A separate MCP server could expose the same tools to Claude Desktop or other clients. Out of scope until there's a concrete second consumer.
- **Telegram bridge.** Two-way ops chat over Telegram is a planned future skill. The `.env.example` reserves the env vars but the wiring is not built.
- **Long-term memory.** The agent will rely on Pi sessions + this repo for now. If/when context-window growth becomes painful, a vector store will be added as a skill.
- **Sandboxing.** The agent currently has full shell access in the repo dir. We rely on the safety rules in `AGENTS.md` plus the safety boundary that the bot has no OP rights server-side.
- **Hard-coded server identity.** Deliberately. The same checkout can be re-pointed at a different server by editing `.env` and restarting Pi.
## Deployment
Local dev for now. Once the seed loop is stable, the same repo will be deployed as a `compose` service on the pepa VPS itself (8 GB RAM is enough to run the MC server + a Pi process + Mineflayer). No code changes expected — everything is read from `.env`.
Local dev for now. Once the seed loop is stable on at least one target server, the same repo can be deployed as a `compose` service anywhere — VPS, home server, Pi (the hardware), whatever. No code changes expected — everything is read from `.env`.
## Open questions
- Does Pi's OAuth flow currently support ChatGPT Pro? Codex CLI does, but it's not documented for Pi. **Action**: try `pi /login` and observe.
- How are extensions loaded long-term — `pi install -e ./extensions/mineflayer-bridge.ts`, or via `--extension` flag, or by adding to settings? **Action**: read pi.dev/docs/latest's Extensions section before writing the bridge.
- What's the right tick cadence? 60s is a guess. Probably needs to be event-driven (react to chat/world events) rather than purely cron.
- How does the agent best persist *cross-server* learnings (e.g. "I know how to handle AuthMe") vs *per-server* state (e.g. "on server X my base is at 100,64,-200")? Likely: skills are cross-server, `state/<host>/` directory holds per-server data.