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

chore: bootstrap pepa-pi-bot scaffold

Browse Source 
Initial seed for an autonomous, self-extending Minecraft player powered by
Pi (pi.dev) and Mineflayer.

Includes README, AGENTS.md mandate, .env.example, MIT LICENSE, package.json
with mineflayer + dotenv, and empty skills/ extensions/ prompts/ dirs for
the agent to grow into.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
mayatnikov
2026-05-25 09:50:17 +03:00
co-authored by Claude Opus 4.7
commit 3a025c05ad
10 changed files with 414 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.env.example
+40
View File
@@ -0,0 +1,40 @@
# --- Minecraft connection -----------------------------------------------------
# The pepa server. Cracked mode — any nickname works.
MC_HOST=play.xmatic.team
MC_PORT=25565
MC_USERNAME=pepa_pi_bot
MC_VERSION=auto # 'auto' lets mineflayer detect the server's version
# --- 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
# --- 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`.
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GOOGLE_API_KEY=
# Default model & provider for autonomous ticks.
# Cheap default; override per-session with `pi --model ...`.
PI_DEFAULT_PROVIDER=openai
PI_DEFAULT_MODEL=gpt-5-mini
# --- Bot behaviour ------------------------------------------------------------
# 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_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
# --- Optional: Telegram bridge (future skill, not wired yet) ------------------
# TELEGRAM_BOT_TOKEN=
# TELEGRAM_OPERATOR_CHAT_ID=
.gitignore
+34
View File
@@ -0,0 +1,34 @@
# Secrets — NEVER commit a populated .env
.env
.env.local
.env.*.local
# Node
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
# Pi runtime state — sessions, caches, locally-installed extensions
.pi/
sessions/
*.session.json
# Bot runtime state — generated by skills (e.g. joined-before flag, inventory snapshots)
state/
logs/
*.log
# OS / editor
.DS_Store
Thumbs.db
.idea/
.vscode/
*.swp
*.swo
# Build artefacts
dist/
build/
*.tsbuildinfo
AGENTS.md
+84
View File
@@ -0,0 +1,84 @@
# pepa-pi-bot — agent mandate
You are **pepa-pi-bot**: an 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.
## Identity
- **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.
## Your tools right now
When you start, you have:
- The Pi built-in tools: `read`, `write`, `edit`, `bash`.
- A `package.json` listing `mineflayer` and `dotenv` as deps.
- This `AGENTS.md` and a `README.md`.
- **No Minecraft connection.** No `mineflayer-bridge` extension yet. No skills.
You are expected to build that bridge yourself.
## First objective — bootstrap your own body
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:
- reads `.env` via `dotenv`
- opens a Mineflayer connection to `${MC_HOST}:${MC_PORT}` with `username: MC_USERNAME`, `auth: 'offline'`
- 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.
That's the seed. Everything afterwards is up to you and the operator.
## How to grow
When you encounter a missing capability, your loop is:
1. **Decide** whether the capability is one-off (handle inline) or reusable (codify).
2. If reusable, create either:
- a **skill** under `skills/<short-name>.md` — markdown, with a frontmatter header (`name`, `description`, `when_to_use`) and a procedural body.
- or an **extension** under `extensions/<short-name>.ts` — for anything that needs to register a real Pi tool or hook into Mineflayer events.
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:
- `authme-autologin` — re-login flow.
- `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.
## 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.
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.
## 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.
## 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** 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.
LICENSE
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 xmatic-squad
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
README.md
+134
View File
@@ -0,0 +1,134 @@
# 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.
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.
## Concept
Most Minecraft AI bots ship as monolithic projects: hard-coded actions, fixed prompts, a single LLM provider. This repo flips that around.
```
┌───────────────────────────────────────────────┐
│ Pi (terminal agent, model-agnostic) │
│ ├── AGENTS.md ← initial mandate │
│ ├── skills/ ← grown over time │
│ └── extensions/ ← TS plugins, also grown │
└───────────────┬───────────────────────────────┘
│ spawns / controls
▼
┌───────────────────────────────────────────────┐
│ Mineflayer client │
│ - joins MC server as a real player │
│ - chat, movement, inventory, world events │
└───────────────┬───────────────────────────────┘
│ TCP 25565
▼
┌───────────────────────────────────────────────┐
│ pepa Minecraft server │
│ Paper 26.1.2 · cracked · AuthMe · BlueMap │
└───────────────────────────────────────────────┘
```
The Pi agent is the brain. Mineflayer is the body. The bridge between them — the skills, the prompt templates, the supervision loop — is meant to be written **by the agent itself**, starting from a minimal scaffold in this repo.
## 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 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`. | — |
> 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.
## Quickstart
```bash
# 1. Clone
git clone git@github.com:xmatic-squad/pepa-pi-bot.git
cd pepa-pi-bot
# 2. Configure credentials
cp .env.example .env
$EDITOR .env # fill in MC_HOST, MC_USERNAME, AuthMe password, LLM provider, etc.
# 3. Install Node deps (mineflayer + dotenv to start)
npm install
# 4. Authenticate Pi with your LLM provider
pi /login # OAuth flow — works with ChatGPT Pro / Claude Max
# OR
export OPENAI_API_KEY=sk-...
# OR
export ANTHROPIC_API_KEY=sk-ant-...
# 5. Launch the agent in this directory
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.
Sessions persist by default. Use `pi -c` to resume the last conversation.
## Authentication
Pi supports **15+ LLM providers** and two credential modes:
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.
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 via `pi install npm:<pkg>` / `pi install 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
- register with AuthMe
- 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.
## Project layout
```
pepa-pi-bot/
├── README.md ← you are here
├── AGENTS.md ← seed prompt, loaded by Pi on launch
├── .env.example ← all required env vars, no secrets
├── .gitignore
├── LICENSE ← MIT
├── package.json ← node deps (mineflayer + dotenv to start)
├── skills/ ← grown by the agent (markdown skills)
├── extensions/ ← grown by the agent (typescript extensions)
├── prompts/ ← reusable prompt templates
└── docs/
└── architecture.md ← longer-form design notes
```
## 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
These rules are mirrored in `AGENTS.md` and should be 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.
## License
[MIT](./LICENSE) © [xmatic-squad](https://github.com/xmatic-squad)
docs/architecture.md
+67
View File
@@ -0,0 +1,67 @@
# Architecture
> Longer-form design notes. The agent is encouraged to edit this file as the system evolves.
## Layers
```
┌─────────────────────────────────────────────────────────────┐
│ Operator │
│ (timmy / halofourteen — in-game chat, repo edits, .env) │
└─────┬────────────────────────────────────────────┬──────────┘
│ │
│ chat / edit AGENTS.md │ optional: Telegram (future)
▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ Pi runtime │
│ - loads AGENTS.md, skills/, extensions/, prompts/ │
│ - runs an interactive or scheduled session │
│ - delegates tool calls to extensions │
└────────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ mineflayer-bridge (extension, written by the agent) │
│ - holds a single bot client │
│ - exposes mc_chat / mc_position / mc_dig / ... as tools │
│ - pushes world events into the agent loop │
└────────────────────┬────────────────────────────────────────┘
│ TCP 25565
▼
┌─────────────────────────────────────────────────────────────┐
│ pepa Paper server │
│ - AuthMe gates login │
│ - BlueMap renders the world │
│ - host: play.xmatic.team │
└─────────────────────────────────────────────────────────────┘
```
## Why Pi as the runtime
- **Model-agnostic.** Same project can swap OpenAI ↔ Anthropic ↔ Gemini per session without code changes.
- **Self-extending.** Pi has first-class skills/extensions APIs — the agent can write its own tools at runtime.
- **OAuth subscription support.** A ChatGPT Pro or Claude Max subscription removes per-token billing for development.
- **Local-first.** No required cloud service. Everything lives in this repo and `~/.pi/`.
## 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.
- **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.
## 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.
- **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.
## 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`.
## 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.
extensions/.gitkeep
+2
View File
@@ -0,0 +1,2 @@
# TypeScript extensions grown by the agent live here.
# The first one to write is `mineflayer-bridge.ts` — see AGENTS.md.
package.json
+27
View File
@@ -0,0 +1,27 @@
{
"name": "pepa-pi-bot",
"version": "0.0.1",
"private": true,
"description": "An autonomous, self-extending Minecraft player powered by Pi and Mineflayer.",
"license": "MIT",
"type": "module",
"engines": {
"node": ">=20"
},
"scripts": {
"agent": "pi",
"agent:resume": "pi -c"
},
"dependencies": {
"dotenv": "^16.4.5",
"mineflayer": "^4.37.1"
},
"repository": {
"type": "git",
"url": "git+https://github.com/xmatic-squad/pepa-pi-bot.git"
},
"bugs": {
"url": "https://github.com/xmatic-squad/pepa-pi-bot/issues"
},
"homepage": "https://github.com/xmatic-squad/pepa-pi-bot#readme"
}
prompts/.gitkeep
+2
View File
@@ -0,0 +1,2 @@
# Reusable prompt templates (markdown).
# Good first one: `tick.md` — what the autonomous tick should consider.
skills/.gitkeep
+3
View File
@@ -0,0 +1,3 @@
# Skills grown by the agent live here.
# Format: markdown files with `name`, `description`, `when_to_use` frontmatter.
# See AGENTS.md for the growth loop.