Install and set up

Hosting Pip means running the mod in Minecraft and her "brain" on the same computer. On a Mac it takes about ten minutes. Joining a friend who already hosts her is much simpler: see Friends on LAN.

What you need

Minecraft Java Edition (Pip uses release 1.21.1 with the Fabric loader; the setup installs Fabric for you).
A Mac with Homebrew. Linux should work (the scripts are written for it) but hasn't been tried yet; Windows hosts aren't supported yet.
An AI for her to think with. Use what you already have: a free Gemini key (the default), your Claude subscription through Claude Code, another AI's command-line tool you pay for, an API key (OpenAI, Claude API, Groq, OpenRouter, Mistral), or nothing at all with Ollama on your computer.

The steps

Install the tools Java, Python and the local speech-to-text:
```
brew install openjdk@25 python@3.12 whisper-cpp
```

Get the code

git clone https://github.com/PetitPotam/kindred-spirit.git
cd kindred-spirit

Run the setup guide
```
scripts/setup.sh
```
It prepares her brain, then asks what you have for each of the four parts: the AI (how she thinks), speech-to-text (how she hears you), the voice (how she speaks, or subtitles only) and memory (on your computer, or your own deployed gateway). It saves your choices, installs only the local tools you picked, starts everything and tests each part:
```
  ok   AI           Hello, friend, there!
  ok   voice        65 KB of WAV
  ok   speech->text heard: 'Testing 1 2 3.'
  ok   embeddings   384 numbers per text
  ok   memory       stored, found and removed a test memory
```
Anything that fails comes with how to fix it. Your keys go in ~/.kindred-spirit/secrets.env, readable only by you. Want no questions? scripts/setup.sh --defaults picks Gemini and everything else local.
Build the mod
```
(cd mod && ./gradlew build)
```
Add a launcher profile (quit the Minecraft Launcher first):
```
python3 scripts/install_profile.py
```
It adds a Kindred Spirit (Fabric 1.21.1) profile with its own game folder (minecraft-kindred), installs Fabric Loader and Fabric API, and backs up your launcher profiles. Your other profiles, mods and worlds are left alone.
Play Double-click scripts/play-mac.command. It starts everything and opens the launcher from Terminal. Pick the Kindred Spirit profile and press Play.

Why start from Terminal?

On macOS the Minecraft Launcher has no microphone permission of its own. Started from the Dock, the game records silence, so play-mac.command opens it from Terminal, which can use the microphone.

Changing your choices later

Run the guide again: brain/.venv/bin/python scripts/guide.py
Only test everything: brain/.venv/bin/python scripts/guide.py --check
Switch one part in one command, without restarting the game: see Configure her.

Optional: what she knows about Minecraft

Pip answers "how does this work?" questions from a knowledge base on your computer, built from the Minecraft Wiki and the game's own recipe data. You fill it yourself (the recommended set takes about 45 minutes, at a polite one page per second):

python3 services/knowledge/kb.py crawl minecraft-wiki --core --grow 600
python3 services/knowledge/kb.py crawl minecraft-data

She also learns pages she doesn't have yet in the background while you play. The wiki's text is under CC BY-NC-SA 3.0: it stays on your computer, with each passage's page and licence. Details: docs/KNOWLEDGE.md.

Trying it without touching your game

Three levels, from quickest to most real: the automated tests (no game, no key, no network), a fake game that talks to your real setup (brain/tools/fake_game.py), and a throwaway sandbox Minecraft driven by a script. The README explains each: Testing without breaking your game.