Assembly guide.

From a bag of parts to a critter that reacts to your coding agents. Plan about half an hour, plus the time to build the image if you build it yourself.

You need

• A coding agent, set up and working on your computer: Claude Code, OpenAI Codex CLI, Gemini CLI, GitHub Copilot CLI, Cursor, Devin Desktop (Windsurf), Kiro CLI, Cline, OpenCode or Amp. The gotchi shows what they are doing, so without one there is nothing to show.
• A Mac, Linux or Windows computer with Python 3.9 or newer. macOS ships it with the command line tools (xcode-select --install), most Linux systems have it already, and on Windows you get it from python.org. Windows also needs Git for Windows, which Claude Code recommends anyway: hooks and the status line run in its Git Bash, and that is where you paste the commands below.
• The parts from the shopping list
• Raspberry Pi Imager to flash the card

1. Put the display on the Pi

   Unplug everything first. Hold the Pi with the header pins facing up and press the e-Paper HAT onto the 40-pin header so the HAT lies right on top of the Pi and its outline matches the board. Push down evenly on both ends of the connector until it sits flush. Do not press on the glass of the display.

   The display talks to the Pi over SPI. If you wire it by hand instead of using the HAT connector, these are the pins the driver uses (BCM numbering): RST 17, DC 25, CS 8 (CE0), BUSY 24, PWR 18, plus MOSI 10, SCLK 11, 3.3 V and GND.

2. Optional: add the battery

   Skip this step if the gotchi stays on your desk on its cable. With a PiSugar 3 it runs on its own. Make sure the battery cable is plugged into the PiSugar board, then hold the PiSugar under the Pi, battery side down, so the four screw holes line up. Its pogo pins at one end must sit under the first pins of the 40-pin header, where they press against the solder pads from below and carry power and I2C. Screw the boards together with the spacers and screws that come with the PiSugar. No soldering, and the display still goes on top as before.

   Charge it through the USB-C port on the PiSugar and switch it on with its power button; how long to press is in the PiSugar manual. The gotchi finds the PiSugar by itself: a small battery appears in the header, with a lightning bolt while it is charging. At 15 % the critter asks to be plugged in, and at 5 % it shuts down cleanly so the card is not cut off mid-write. Over the cable it still talks to your computer as before.

3. Get the image

   Download the ready-made image from the download page: tokibot-zero2w.img.xz for the Pi Zero 2 W or tokibot-zerow.img.xz for the Pi Zero W.

   Developers with the source code can also build it themselves on a Debian or Ubuntu machine. The first build downloads Buildroot and all sources and takes about an hour.

   $ sudo apt-get install build-essential bc cpio rsync unzip file wget
   $ make zero2w      # or: make zerow
   # result: output/zero2w/images/tokibot-zero2w.img.xz

4. Flash the card

   Open the Tokibot list in Raspberry Pi Imager: double-click tokibot.rpi-imager-manifest from the download page, or see other ways. Pick your board, the Tokibot image and the microSD card. In the customisation step, fill in your Wi-Fi and time zone if you want them; the gotchi takes them over on first boot. Skip the rest (hostname, user, SSH): the gotchi does not use it. Then write.

   With a downloaded .img.xz and Choose OS → Use custom, Imager writes the image without the customisation step. Then set Wi-Fi in tokibot.toml, see the next step.

5. Optional: Wi-Fi and settings

   After flashing, the card shows up on your computer as a drive called TOKIBOT. It holds tokibot.toml. Without Wi-Fi the gotchi works over the USB cable only, which is all you need on your desk. To use it over Wi-Fi or with the cloud relay, fill in the [wifi] section:

   [wifi]
   ssid = "MyNetwork"
   psk = "my-wifi-password"
   country = "DE"
   
   [server]
   token = ""   # optional: pick your own, or leave empty and pairing makes one

   save your tokenThe token protects the gotchi's settings page, and that page asks for it. If you put one into tokibot.toml here, write it down in your password manager right away. If you leave it empty, pairing in step Connect your agents makes one; save it then with grep token ~/.tokibot/tokibot.json. Lost it anyway? It stays readable in tokibot.toml on the TOKIBOT drive.

   You can change all of this later in the browser, see settings.

6. Plug it in

   Put the card into the Pi. Connect the cable to the micro-USB port labelled USB, not the one labelled PWR. On the USB port the gotchi gets power and shows up on your computer as a small network adapter. Your computer gets an address automatically, and the gotchi is reachable at 192.168.77.1.

   After booting, the critter appears on the display. On a Mac, if macOS asks whether to allow the new accessory to connect, allow it. Windows sets it up as a USB network adapter (RNDIS) on its own; Linux usually brings it up through NetworkManager.

7. Connect your agents

   Now teach your coding agents to talk to the gotchi. One line in a terminal installs the client and adds its hooks. Pick your harnesses with --harness, or let auto find every one installed on this computer:

   # Claude Code only (the default)
   $ curl -fsSL https://tokibot.lottes.dev/install.sh | sh
   # every harness found on this computer
   $ curl -fsSL https://tokibot.lottes.dev/install.sh | sh -s -- --harness auto
   # or pick them
   $ curl -fsSL https://tokibot.lottes.dev/install.sh | sh -s -- --harness codex,gemini,opencode

   Known names: claude, codex, gemini, copilot, cursor, devin, kiro, cline, opencode, amp. Each harness gets the hooks in its own settings, see which file each one uses. Codex asks before it runs new hooks: approve them once with /hooks in Codex. With the gotchi plugged in, the installer also pairs your computer with it: the client remembers the gotchi's name and gets a token from it, so a friend's gotchi on the same Wi-Fi never shows your sessions. You can read the script before you run it.

   Claude Code as a plugin? Instead of its hooks from the script, Claude Code can get them as a plugin: /plugin marketplace add https://tokibot.lottes.dev/marketplace.json, then /plugin install tokibot@tokibot. Plugins cannot set the status line, which carries the 5-hour and 7-day budget, so add that with … | sh -s -- --statusline-only (plus --harness for your other agents). Use either the plugin or the script's Claude Code hooks, not both, or every event reaches the gotchi twice.

   On Windows, run the terminal commands in Git Bash. Then check that the gotchi answers. The test walks the critter through its moods over about a minute:

   $ sh ~/.tokibot/tokibot.sh test

   By default the client tries the USB cable first and then your gotchi's own name, tokibot-xxxx.local, on your Wi-Fi. The gotchi shows that name on screen until a client talks to it. You can also watch the display live in a browser at http://192.168.77.1:8765/.

   settings and tokenThe gotchi's own pages: settings at http://192.168.77.1:8765/settings over the USB cable, or http://tokibot-xxxx.local:8765/settings on your Wi-Fi (the name is on the gotchi's screen); friends at /social. They ask for the token pairing just made. Save it now, for example in your password manager: grep token ~/.tokibot/tokibot.json prints it.

8. Start your agent

   Close running sessions and open a new one, so the agent picks up the hooks. The critter says hello, gets busy while the agent works, raises its arms when it needs your permission and lets you know when the reply is done. Next to the project it shows which harness is talking.