FAQ

What is a Tokibot?

A Tokibot is a small gadget for your desk: a Raspberry Pi Zero with a 2.13 inch e-paper display. A pixel critter on the display shows what your coding agent sessions (Claude Code, Codex, Gemini CLI, Copilot CLI, Cursor, Devin, Kiro, Cline, OpenCode, Amp) are doing: working, waiting for you, asking for permission, done, or stuck at a rate limit. They report to it through hooks, and the tokens they use are its food. It was called Claudegotchi until version 0.4. The gotchi runs its own small operating system image, built with Buildroot.

Do I need Claude Code?

No, but you need at least one coding agent: Claude Code, OpenAI Codex CLI, Gemini CLI, GitHub Copilot CLI, Cursor, Devin Desktop (Windsurf), Kiro CLI, Cline, OpenCode or Amp. Pick them with install.py --harness, or --harness auto for all that are installed. Only Claude Code reports its rate limits and context, so the budget bars need it. Claude Code needs a Claude subscription or an Anthropic API account. It can run on your computer (terminal or IDE extension) or in the cloud, for example in a Claude Project. For cloud sessions see How do cloud sessions reach the gotchi?.

Which computers are supported?

macOS, Linux and Windows. All of them need Python 3.9 or newer for the small client that talks to the gotchi. Windows also needs Git for Windows, because Claude Code runs hooks and the status line in Git Bash there. Over the USB cable the gotchi works without a driver on all three: Windows uses its built-in RNDIS driver, macOS and Linux use CDC-ECM.

Which hardware do I need?

A Raspberry Pi Zero 2 WH (or Zero W/WH), a Waveshare 2.13 inch e-Paper HAT (V4 by default, V1 to V3 work too), a microSD card with 8 GB or more and a micro-USB data cable. That is about 50 to 60 euros and needs no soldering if the Pi already has its header. A PiSugar 3 battery is optional. The full list is at https://tokibot.lottes.dev/parts.html.

Does it work with a Raspberry Pi 3, 4 or 5, or another display?

The image targets the Pi Zero 2 W and the Pi Zero W only, so no Pi 3, 4 or 5. For displays, the gotchi supports the Waveshare HATs that Pwnagotchi builds use: the 2.13 inch V1, V2, V3 and V4, the 2.13 inch B V4 (black, white and red) and the 2.7 inch V1 and V2. Pick yours under Display on the settings page; the revision is printed on the back of the display board. Smaller displays such as the Inky pHAT, PaPiRus or OLED HATs do not work, because the picture is drawn for 250 × 122 pixels.

I have a Pwnagotchi. Can I reuse its hardware?

Yes, if it has one of the displays above: flash the Tokibot image onto a second microSD card and keep the Pwnagotchi card as it is. Set the display on the settings page, or copy the name from Pwnagotchi's ui.display.type into display in tokibot.toml; names like waveshare_3 or waveshare_4 are understood. A PiSugar 3 works as well.

What data does the gotchi get? Does it see my code?

Only metadata: the event name, session ID, project folder name, tool name, error or notification type, limit and context percentages, and categories of shell commands (test run, commit, push, pull request) that the client recognises on your computer. Prompts, code, commands and replies never leave your computer. With the cloud relay, that metadata passes through the ntfy server you chose.

Which image do I download?

tokibot-zero2w.img.xz for the Raspberry Pi Zero 2 W and tokibot-zerow.img.xz for the first-generation Pi Zero W. Both are on https://tokibot.lottes.dev/download.html with SHA-256 checksums. Flash the .img.xz file as it is; Raspberry Pi Imager unpacks it.

How do I flash the card?

Open the Tokibot list in Raspberry Pi Imager: double-click tokibot.rpi-imager-manifest from https://tokibot.lottes.dev/download.html#imager, or enter https://tokibot.lottes.dev/downloads/imager.json under App Options → Content Repository → Use custom URL. Pick your board, the Tokibot image and the microSD card, and write. Without the list, Choose OS → Use custom with the downloaded .img.xz works too.

Can I enter the Wi-Fi in Raspberry Pi Imager?

Yes, with the Tokibot list in Imager (see above): its OS customisation asks for Wi-Fi and time zone, and the gotchi moves both into tokibot.toml on first boot and deletes Imager's files. Hostname, user account, SSH and Raspberry Pi Connect are not used; the gotchi keeps its own name tokibot-xxxx. With Use custom Imager does not offer the customisation, because it cannot tell how the image wants to be customised. Then put the Wi-Fi into tokibot.toml on the TOKIBOT drive.

Windows says "You need to format the disk" after flashing. What do I do?

Click Cancel. Do not format. The card has partitions that Windows cannot read, which is normal for a Linux image. Formatting would erase the image. The partition Windows can read is called TOKIBOT and holds tokibot.toml.

macOS says "The disk you inserted was not readable by this computer".

Click Ignore. The card has a Linux partition that macOS cannot read, which is normal. The TOKIBOT drive with tokibot.toml shows up next to it.

How do I check the download?

Compare the SHA-256 checksum with the one on the download page. On macOS run shasum -a 256 tokibot-zero2w.img.xz, on Linux sha256sum tokibot-zero2w.img.xz, on Windows in PowerShell Get-FileHash tokibot-zero2w.img.xz.

Which USB port do I use?

The micro-USB port labelled USB, the middle one of the three ports. Not the one labelled PWR at the edge. On the USB port the gotchi gets power and shows up on your computer as a network adapter; on PWR it only gets power and your computer does not see it.

My computer does not see the gotchi at all.

Check these in order:

• The cable is in the port labelled USB, not PWR.
• The cable carries data. Many micro-USB cables only charge. Try another cable, or one you have used for data before.
• The first boot takes a little while. Wait until the critter is on the display.
• Open http://192.168.77.1:8765/ in a browser. If the preview of the display loads, the connection works and the problem is in the client setup.

What address does the gotchi have?

Over the USB cable it is always 192.168.77.1, port 8765. Your computer gets an address from the gotchi automatically (DHCP, 192.168.77.2 to .10). On Wi-Fi the gotchi has a name of its own, tokibot-xxxx.local; it shows that name on screen until a client talks to it. See Two gotchis on the same Wi-Fi. The gotchi does not route your internet traffic; your normal connection keeps working.

Windows: the gotchi does not show up as a network adapter.

Open Device Manager. The gotchi should be under Network adapters as a USB RNDIS adapter (for example Remote NDIS Compatible Device). If it is under Other devices with a warning sign instead, Windows did not pick the driver itself: right-click it, choose Update driver → Browse my computer → Let me pick, then Network adapters → Microsoft → Remote NDIS Compatible Device. Some company laptops block RNDIS adapters by policy; then use Wi-Fi instead.

Windows shows "Unidentified network" for the gotchi. Is that a problem?

No. The gotchi's USB network has no internet and no gateway on purpose, so Windows calls it unidentified. Your internet connection is not affected. The client reaches the gotchi at 192.168.77.1 anyway.

macOS asks "Allow accessory to connect?"

Click Allow. Newer macOS versions ask before a new USB device may connect. If you clicked Don't Allow, unplug and plug the gotchi in again, or allow it under System Settings → Privacy & Security.

macOS shows a self-assigned IP address (169.254.x.x) for the gotchi.

The gotchi's DHCP server has not answered yet. Wait until the critter is on the display, then unplug and plug in the cable again. In System Settings → Network the gotchi's adapter should get an address from 192.168.77.2 to .10.

Linux: the adapter shows up but gets no address.

Set the new wired connection to DHCP. With NetworkManager it is usually automatic; if not, set IPv4 to Automatic (DHCP) for the adapter (nmcli device lists it, often named usb0 or enx…). With systemd-networkd or a manual setup, run a DHCP client on that interface. The gotchi itself is always 192.168.77.1.

tokibot-xxxx.local does not resolve.

.local names need mDNS. On Linux install and start avahi with nss-mdns (on Debian and Ubuntu: libnss-mdns). On Windows .local lookups are often unreliable. Over the USB cable this does not matter: the client tries 192.168.77.1 first. On Wi-Fi you can set a fixed address instead, for example --url http://192.168.1.50:8765 or the Gotchi address setting of the plugin.

Plugin or install script: which one should I use?

Either one, never both, or every event reaches the gotchi twice. The Claude Code plugin is the usual way: in Claude Code run /plugin marketplace add https://tokibot.lottes.dev/marketplace.json and /plugin install tokibot@tokibot. Plugins cannot set the status line, so add it with curl -fsSL https://tokibot.lottes.dev/install.sh | sh -s -- --statusline-only. Without the plugin, curl -fsSL https://tokibot.lottes.dev/install.sh | sh installs hooks and status line in one go.

Why does the plugin need an extra step for the status line?

Claude Code plugins can add hooks but cannot set the status line. The gotchi learns how much of your 5-hour and 7-day budget is used only from the status line, so without it the budget bars stay empty and the critter cannot get tired or show the limit in advance. install.sh --statusline-only adds just the status line and keeps an existing one: it is still shown.

/plugin marketplace add with the URL fails.

Update Claude Code. The plugin is served as a zip archive from the website, and archive sources need Claude Code 2.1.224 or newer. Also check that your network can reach tokibot.lottes.dev. As an alternative, curl -fsSL https://tokibot.lottes.dev/install.sh | sh installs the same client without the plugin system.

I installed both the plugin and install.sh.

Remove the hooks from one of them, or every event is counted twice. To keep the plugin, run curl -fsSL https://tokibot.lottes.dev/install.sh | sh -s -- --uninstall and then curl -fsSL https://tokibot.lottes.dev/install.sh | sh -s -- --statusline-only. To keep the script instead, remove the plugin in /plugin.

Windows: which terminal do I use for the commands?

Git Bash, which comes with Git for Windows. The curl … | sh commands and sh ~/.tokibot/tokibot.sh test are shell commands and do not work in PowerShell or cmd. Claude Code itself also runs the gotchi's hooks through Git Bash.

Windows: "python3" opens the Microsoft Store or is not found.

Install Python from https://www.python.org/downloads/ and keep the option that adds Python to PATH. On Windows python3 is often only a stub that opens the Store. The Tokibot client and install.sh do not depend on it: in Git Bash they try py -3, then python, then python3, and take the first one that is Python 3.9 or newer.

Windows: hooks do nothing, and Git for Windows is not installed.

Install Git for Windows from https://git-scm.com/downloads/win and restart Claude Code. Without Git Bash, Claude Code runs hooks in PowerShell, where the gotchi's hook command (sh …) does not exist, so nothing is sent.

macOS: "python3" asks me to install the command line developer tools.

Install them: click Install, or run xcode-select --install. They bring Python 3, which the client needs. Then run the install command again.

How do I test the connection?

Run sh ~/.tokibot/tokibot.sh test (on Windows in Git Bash). It walks the critter through its moods over about a minute and prints, for every step, which address answered. If a step fails it prints the addresses it tried. Both the full install script and --statusline-only put this file there.

The critter does not react to Claude Code.

Check these in order:

• Start a new Claude Code session. Sessions that were already running keep their old settings and hooks.
• Run the test: sh ~/.tokibot/tokibot.sh test.
• If the gotchi has a token, the client needs the same one: set it in /plugin (plugin) or run the install script again with --token.
• If the test says 409, the address answered with another gotchi than yours, for example a friend's. Pair again with yours, see How do I pair.
• Check that plugin and install script are not both installed, see I installed both.

Does it work with Claude Code in VS Code or JetBrains?

The IDE extensions run Claude Code with the same ~/.claude settings, so the hooks reach the gotchi there as well. The terminal and the IDE can run at the same time; the gotchi counts every session.

Several sessions at once: what does the gotchi show?

The state that needs you most wins: a permission request or a session waiting for you beats a working one. The footer shows how many sessions are working (▶), waiting for you (?) or done (✓). With three or more sessions working at once the critter juggles.

How do I remove the client?

Remove the plugin in /plugin, and the status line or full install with curl -fsSL https://tokibot.lottes.dev/install.sh | sh -s -- --uninstall. The uninstall puts your previous status line back. A backup of your original settings is in ~/.claude/settings.json.tokibot-backup.

How do I put the gotchi on Wi-Fi?

Either before the first start: put the card into your computer, open tokibot.toml on the TOKIBOT drive and fill in ssid, psk and country under [wifi]. Or later in the browser: open http://192.168.77.1:8765/settings over the USB cable. Without Wi-Fi the gotchi works over the USB cable only, which is all you need on your desk.

Where are the settings?

On the settings page at http://tokibot-xxxx.local:8765/settings, or http://192.168.77.1:8765/settings over USB. It changes Wi-Fi, time zone, rotation, token, relay and Bluetooth and writes tokibot.toml on the card. You can also edit that file directly on the TOKIBOT drive.

How do I pair my computer with my gotchi?

The install script pairs right away if the gotchi is plugged in with the USB cable. For Wi-Fi only, pass the name the gotchi shows on screen: --gotchi tokibot-xxxx. To pair again later, run sh ~/.tokibot/tokibot.sh pair (over USB) or sh ~/.tokibot/tokibot.sh pair tokibot-xxxx (over Wi-Fi). Pairing remembers the gotchi's name. If the gotchi has no token yet, it makes one, saves it in tokibot.toml and hands it to your computer, so from then on only your computer gets through. Without pairing, the client learns the name the first time it reaches a gotchi over USB, but without a token.

Two gotchis on the same Wi-Fi: does mine get my events?

Yes. Every gotchi has its own network name, tokibot-xxxx.local, where xxxx comes from the Pi's serial number and stays the same after reflashing. The client sends your gotchi's name with every event, and a gotchi with another name refuses it (HTTP 409). A friend's gotchi on the same network never shows your sessions.

Should I set a token?

Yes, as soon as the gotchi is on a Wi-Fi you share with others. Without a token, anyone who can reach the gotchi on port 8765 can send it events and open the settings page. Pairing sets one up for you: if the gotchi has no token yet, it makes one and hands it to your computer, see How do I pair. You can also set it on the settings page and give the client the same one: in /plugin for the plugin, or with --token for the install script.

The picture is upside down.

Set Rotate display to 180 on the settings page, or rotate = 180 under [device] in tokibot.toml.

The clock is wrong.

Set your time zone on the settings page (timezone, for example Europe/Berlin). On Wi-Fi the gotchi gets the time from the internet (NTP); without Wi-Fi it takes the time from your computer.

Can I log in to the gotchi with SSH?

No. The image has no SSH, and its root filesystem is read-only. Everything you can change is on the settings page or in tokibot.toml. App updates are uploaded on the settings page.

How do cloud sessions reach the gotchi?

Sessions in a Claude Project or in Claude Code on the web run in a cloud container that cannot see your desk. They send their events to a relay, an ntfy topic, and the gotchi listens to that topic over Wi-Fi. Setup, once: give the gotchi Wi-Fi; create a relay with curl -fsSL https://tokibot.lottes.dev/install.sh | sh -s -- --new-relay and enter the printed token and relay URL on the gotchi's settings page; print the setup script with curl -fsSL https://tokibot.lottes.dev/install.sh | sh -s -- --cloud-setup > cloud-setup.sh; on claude.ai add your own cloud environment that allows ntfy.sh and runs that script. The full walkthrough is at https://tokibot.lottes.dev/docs.html#cloud.

Cloud sessions do not reach the gotchi.

Check these in order:

• The gotchi is on Wi-Fi with internet. The relay does not work over the USB cable alone.
• The token and relay URL on the gotchi's settings page match what --new-relay printed.
• The cloud environment allows ntfy.sh under Network access. The built-in environment of a Claude Project blocks it and has no settings, so you need your own environment (Project settings → Cloud environment → Add cloud environment).
• The setup script is pasted in that environment, and the project uses that environment. Only sessions started after the change use it.

Is the relay secure?

The topic name is the secret: anyone who knows it can read the events, which are metadata only, and could publish to it. The gotchi ignores relay messages without the right token. You can run your own ntfy server and point --relay at it; set [relay] auth on the gotchi if your server needs an access token.

How do I fit the PiSugar 3 battery?

Screw it under the Pi, battery side down, with the screws and spacers that come with it. Its pogo pins press against the pads of the first pins of the 40-pin header from below and carry power and I2C, so no soldering is needed. The display still goes on top. Step by step: https://tokibot.lottes.dev/build.html#battery.

The gotchi does not show the battery.

The gotchi looks for the PiSugar on I2C (address 0x57) when it starts. If no battery shows in the header: check that the PiSugar is screwed on firmly so the pogo pins touch the header pads, then restart the gotchi. In tokibot.toml, model under [battery] must be auto or pisugar3, not none. Only the PiSugar 3 and 3 Plus are supported.

Why did the gotchi switch itself off?

On battery, at 15 % the critter asks to be plugged in, and at 5 % it says good night and shuts down cleanly so the SD card is not cut off mid-write. Charge it through the PiSugar's USB-C port and switch it on with the PiSugar's power button. The threshold is shutdown_at under [battery].

The display stays blank.

Check that the HAT sits flush on all 40 pins, and that it is the V4 revision of the 2.13 inch display (printed on the back). Give it a moment: e-paper refreshes slowly and the first boot takes a little while. Faint traces of the previous picture are normal for e-paper.

How do gotchis become friends?

Gotchis that meet in real life notice each other over Bluetooth LE. Open the friends page at http://tokibot-xxxx.local:8765/social and press Befriend next to a gotchi nearby (new gotchis are Open for new friends from the start; untick it to stay anonymous); its owner presses Accept on their social page. Both gotchis sign the friendship. Only game data travels over Bluetooth: never session contents, folder names or prompts. Turn it off on the settings page (Meet other gotchis) or with [social] enabled = false.

How do I keep my critter's progress when I change the card?

Download a backup on the social page. It is encrypted with a passphrase you choose and holds the identity, friends and progress. Restore it on the new card or gotchi. Without a backup, all of that lives only on the SD card.

How do I get on the highscores?

New gotchis join right away: Join the highscores on the settings page is ticked from the start ([leaderboard] enabled = true). The gotchi posts a small card signed with its own key once an hour: its name from the social page, level, XP, best streak, and food and XP per day. Nothing about your projects, prompts or code. A gotchi without Wi-Fi gets posted by the client on your computer after a reply. Untick it and the gotchi asks the site to delete its entry. The lists are at https://tokibot.lottes.dev/highscores.html.

How are the highscores fair across harnesses and plans?

They count food points, not raw tokens: input, output and cache writes in full, cache reads at 10 %. Glutton counts only real token counts, never the estimates for harnesses that report none. Gourmet ranks XP per million food points, so getting a lot done with little counts too. Weeks and months are fixed calendar periods in UTC. No list looks at the 5-hour or weekly limits of any plan.

How do I update the gotchi?

Download tokibot-app.tar.gz from https://tokibot.lottes.dev/download.html and upload it on the settings page. The gotchi checks that the new version starts and keeps it; if it crashes three times in a row right after starting, it goes back to the version built into the image. Kernel or system changes need a new image on the card.

How do I update the client on my computer?

The plugin updates through /plugin when a new version is out. For the install script, run the same install command again; it keeps your address, token and relay.