TamaClaude

Tamagotchi + Claude — a virtual pet whose moods are your coding sessions.

🌐 English · ไทย

What the screen says · What you need · Getting started · Troubleshooting

Before you start

• macOS only. The app that talks to Claude Code is a Swift menu bar app for macOS 14 or newer. There is no Linux or Windows build, and the firmware alone does nothing without it.
• Unofficial. A personal hobby project, not affiliated with or endorsed by Anthropic. "Claude" and "Claude Code" belong to them.
• As-is. Flashing firmware overwrites whatever is on the board, and you do it at your own risk. No warranty — see LICENSE.
• Reading your quota from claude.ai is optional and needs an account credential. Read step 5 before you turn it on.

A desk device that shows what Claude Code is doing right now. A blocky orange mascot lives on a small screen next to your keyboard: it types when Claude types, waves when a session needs your answer, and celebrates when a build finishes. The bars at the bottom are your Claude usage quota.

The board, and the menu bar app that feeds it.

Nothing leaves your network. A menu bar app on your Mac reads Claude Code's hooks and pushes a small snapshot to the board over Bluetooth LE — and, if you set up Wi-Fi, over your own LAN as a sealed fallback when Bluetooth goes quiet. The board never talks to claude.ai.

What the screen says

While a session runs

Busy	Waiting for you	Done
Up to three sessions and the tool each one is using.	A session stopped and wants an answer.	The mascot celebrates a finished turn.

When nothing is happening

Idle	No sessions	Offline
One session, sleeping. Night sky and clock.	The mascot strolls. Clock and date.	The Mac is out of range or the app is not running.

Quota

Normal	Running hot	Unknown
The current 5-hour window and the weekly one.	Near the limit; the tick marks your pace against the clock.	--, never a guess, when no number has arrived.

Over Wi-Fi

Still live	Nobody feeding it
Bluetooth is gone, so the label is the board's IP and the icon is a wave — but the snapshot still arrives, sealed, over the network.	The board is on the network with nothing to show: the Mac is asleep or the app is not running.

What you need

Hardware

• An ESP32-2432S028R board — the "Cheap Yellow Display", 2.8" 320x240, roughly 300 baht. Tested against ESP32-D0WD-V3 rev 3.1, 4 MB flash, no PSRAM.
• A USB data cable for the board's micro-USB port. Charge-only cables do not enumerate.

Mac

• macOS 14 or newer, with Bluetooth.
• Claude Code installed and logged in.

The Mac app is always built from source. The firmware you can either download or build — step 2 has both routes.

1. Get the repository and the Swift compiler

xcode-select --install
git clone https://github.com/thaitop/tamaclaude.git
cd tamaclaude

2. Put the firmware on the board

Plug the board in and put its serial port into a variable, so the commands below work as written:

PORT=$(ls /dev/cu.usbserial-* | head -1)
echo "$PORT"

That should print one path, something like /dev/cu.usbserial-1420 — the number differs from board to board and from port to port, which is why nothing below spells it out. If it prints nothing, see Troubleshooting.

PORT only exists in the terminal window you typed it in; if you open a new one, set it again.

Option A — flash a ready-made image (no ESP-IDF)

Download tamaclaude-esp32-*.bin from the latest release. It is one file, about 1 MB, containing the bootloader, the partition table and the app.

python3 -m pip install esptool
python3 -m esptool --chip esp32 --port "$PORT" \
    write_flash 0x0 ~/Downloads/tamaclaude-esp32-1.0.4.bin

That is the whole toolchain: about 10 MB of Python, no compiler. Skip to step 3.

Option B — build it yourself

Take this route if you want to change the firmware, or if your board turns out to need different panel settings.

Build tools:

brew install cmake ninja dfu-util python3

ESP-IDF — this is the big one, roughly 2 GB. v5.5 is what this firmware is built and tested against; the component manifest accepts 5.4 and newer:

mkdir -p ~/esp && cd ~/esp
git clone -b v5.5 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf && ./install.sh esp32

Then, from the repository, load the toolchain into your shell and flash:

cd firmware
. $HOME/esp/esp-idf/export.sh
idf.py -p "$PORT" flash monitor

The export.sh line is per-shell and is not permanent; open a new terminal and you run it again. The first build takes several minutes. If anything here goes wrong, Espressif's own getting-started guide is the authority.

Either way

The screen lights up and the board starts announcing itself over Bluetooth as tamaclaude-3f7a — the last part comes from its MAC address, so you can tell two boards apart. With idf.py monitor running you can watch it happen; press Ctrl+] to leave.

3. Install the Mac app

cd ../host
./Scripts/make-app.sh --install

This builds TamaClaude.app, copies it to /Applications, and launches it. macOS asks for Bluetooth permission the first time — say yes, or the app can never see the board.

A small mascot icon appears in your menu bar. Click it for the quota panel; click the gear for settings. The foot of the panel tells you whether the board is connected and what each session is doing.

The badge next to the icon is your session usage, and it turns red when you are burning through the window faster than the clock is.

4. Connect it to Claude Code

Everything below is in gear ▸ Settings… ▸ General:

• Install hooks in settings.json — this is the one that matters. It teaches Claude Code to tell the app what it is doing. Nothing appears on the board without it. Your existing settings are kept, and a backup is written beside the file.
• Board — pick your board by name, or leave it on Any board.
• Brightness — the slider drives the screen's backlight.
• Launch at login — so it is running before you start work.

Start a Claude Code session in any terminal. Within a second or two the mascot should start moving.

5. Quota on the board

The bars at the bottom of the screen have two independent sources, both optional:

• Read quota from the statusline (Settings ▸ General) installs a Claude Code statusline that hands the app your current usage. It needs no password, but it only updates while Claude Code is running.
• Set session key… (Settings ▸ General) lets the app ask claude.ai directly, so the number keeps moving even with Claude Code closed. Refresh quota then chooses how often (Off / 60s / 5 min).

About the session key. It is the sessionKey cookie of a logged-in claude.ai browser session, and it is a full-account credential — anyone holding it can act as your account. The app stores it in ~/.tamaclaude/session-key with mode 600 and never puts it in a command line, an environment variable, or a log. Take it out at any time by deleting that file, and revoke it by logging out of claude.ai in the browser you copied it from. If you would rather not, skip this — the statusline route above still shows a number.

To get one: in your browser, open claude.ai while logged in → DevTools → Application → Cookies → claude.ai → copy the value of sessionKey.

Taking over the statusline slot never changes what you see: your own statusline command is handed the same input and its output is printed as is. If you never had one, the app draws this instead — the same elements, colours, and ~/.claude/statusline-config.txt as the statusline that ships with Claude Usage.

6. Wi-Fi, so the screen survives Bluetooth (optional)

Bluetooth is the main path and always wins. It also drops — you walk past the board, the Mac half-sleeps — and until now that left a frozen screen. Put the board on your network and the app keeps feeding it when Bluetooth has been quiet for ten seconds.

gear ▸ Settings… ▸ Wi-Fi, with the board in Bluetooth range:

1. The list fills in as the board scans — not your Mac, so what you see is what the board can actually reach. It is 2.4 GHz only; a 5 GHz-only network will not appear.
2. Pick a network, type the password, Connect. macOS pairs with the board the first time; there is no six-digit code to enter.
3. It says Connected to <name> with the board's address. The board remembers up to five networks and comes back on its own after a power cut.

You do not have to configure anything on the Mac side. The snapshot is sealed with AES-256-GCM under a key the app generates and pushes to the board over the same encrypted channel as your Wi-Fi password, and the board is found over mDNS — the address box at the bottom of the tab is only for networks that filter it.

The board still never talks to claude.ai; your session key never leaves the Mac.

Troubleshooting

No /dev/cu.usbserial-* when the board is plugged in. Usually the cable — many micro-USB cables carry power only. Failing that, the board's USB-serial chip (CH340) may need a driver on older macOS releases.

Flashing stops at "Connecting........". Hold the BOOT button on the board, start idf.py flash, and release it once the log says Connecting. Also close any serial monitor still holding the port.

The screen is on but the colours are wrong, or the image is mirrored. Some batches of this board ship a different panel than the one this firmware was measured against. Run the probe project in firmware/probe/ to read out what your panel actually reports, then change the two constants it disagrees with in firmware/main/ct_lcd.c: the 0x36 (MADCTL) value for orientation and mirroring, and 0x20 (inversion off) versus 0x21 (inversion on) for inverted colours.

The board never shows up in the Board menu. Check that the app has Bluetooth permission in System Settings → Privacy & Security → Bluetooth, that the board is powered, and that nothing else is connected to it — the firmware accepts exactly one connection at a time.

macOS asks for Bluetooth permission again after every rebuild. Expected. The app is signed ad-hoc, so each build is a new identity as far as macOS is concerned. There is no way around it without an Apple Developer ID.

The mascot never moves. The hooks are probably not installed — Settings ▸ General → Install hooks in settings.json. Sessions already open when you install them keep the old settings; start a new one. Open log in the same tab shows what the app is receiving.

The Wi-Fi list stays empty, or the spinner never stops. Wi-Fi is set up over Bluetooth, so the board has to be connected first — the tab says so when it is not. The list only ever holds 2.4 GHz networks.

The board is on the network and pings, but the screen still freezes when Bluetooth goes. macOS 15 and newer ask for Local Network permission separately, and a refusal silences both mDNS and direct connections with no error at all. System Settings ▸ Privacy & Security ▸ Local Network.

Known limits

• macOS only. The app that talks to Claude Code is a Swift menu bar app; there is no Linux or Windows build.
• No over-the-air updates. New firmware means plugging the USB cable back in.
• The touchscreen and speaker are unused. The panel is touch-capable and the board has a speaker pin; neither is wired up yet.
• Ad-hoc signing. The app is not notarised, so it is built per-machine rather than handed around.

License

MIT — see LICENSE.