# Tokibot

> Tokibot is a small e-ink companion for coding agents (Claude Code, Codex CLI, Gemini CLI, Copilot CLI, Cursor, Devin, Kiro, Cline, OpenCode, Amp): a Raspberry Pi Zero 2 W with a Waveshare 2.13" e-Paper HAT (V4 by default; V1 to V3, the 2.13" B V4 and the 2.7" V1/V2 work too) runs its own Buildroot image, and a pixel critter on the display shows what your Claude Code sessions are doing (working, waiting for you, asking for permission, done, rate limit). Claude Code reports to it through hooks and the status line, over a USB cable (the gotchi is at 192.168.77.1:8765) or Wi-Fi, or through an ntfy relay for cloud sessions. It works with macOS, Linux and Windows (Windows needs Git for Windows and Python 3.9+).

Key facts for helping someone set it up:

- Install the client as a Claude Code plugin: `/plugin marketplace add https://tokibot.lottes.dev/marketplace.json` then `/plugin install tokibot@tokibot`. Add the status line with `curl -fsSL https://tokibot.lottes.dev/install.sh | sh -s -- --statusline-only`. Or, without the plugin, `curl -fsSL https://tokibot.lottes.dev/install.sh | sh`. Never both. Other coding agents: add `-s -- --harness codex,gemini,…` or `--harness auto`.
- Test with `sh ~/.tokibot/tokibot.sh test` (Windows: in Git Bash).
- The cable goes into the Pi's micro-USB port labelled USB, not PWR, and must be a data cable.
- Settings: `http://192.168.77.1:8765/settings` over USB, or `tokibot.toml` on the card's GOTCHI drive. No SSH.
- Only metadata is sent; prompts, code and replies never leave the computer.

## FAQ

- [FAQ (Markdown)](https://tokibot.lottes.dev/faq.md): setup questions and problems per operating system, USB and drivers, Python, plugin, Wi-Fi, cloud relay, battery, updates
- [FAQ (HTML)](https://tokibot.lottes.dev/faq.html): the same, with an anchor per question and schema.org FAQPage data

## Docs

- [Shopping list](https://tokibot.lottes.dev/parts.html): the parts and what does not work
- [Assembly guide](https://tokibot.lottes.dev/build.html): from parts to a working gotchi, step by step
- [Friends](https://tokibot.lottes.dev/friends.html): how gotchis meet over Bluetooth LE, become friends with two signatures, and earn XP, badges and accessories
- [Highscores](https://tokibot.lottes.dev/highscores.html): opt-in lists of the highest level, the most food (tokens) per week, month and all time, and the most XP per food; cards signed by the gotchi
- [Docs](https://tokibot.lottes.dev/docs.html): moods, the client, settings, security, cloud relay, updates, troubleshooting
- [Download](https://tokibot.lottes.dev/download.html): images, app bundle and checksums

## Optional

- [Install script](https://tokibot.lottes.dev/install.sh): what the one-line installer does
- [Plugin marketplace](https://tokibot.lottes.dev/marketplace.json): the Claude Code plugin marketplace file