chore: bootstrap pepa-pi-bot scaffold
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:
Claude Opus 4.7
@@ -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=
|
||||
+34
@@ -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
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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)
|
||||
@@ -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.
|
||||
@@ -0,0 +1,2 @@
|
||||
# TypeScript extensions grown by the agent live here.
|
||||
# The first one to write is `mineflayer-bridge.ts` — see AGENTS.md.
|
||||
@@ -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"
|
||||
}
|
||||
@@ -0,0 +1,2 @@
|
||||
# Reusable prompt templates (markdown).
|
||||
# Good first one: `tick.md` — what the autonomous tick should consider.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user