tamaclaude

KO | EN

gitlite — search

#python #hacktoberfest #react #ai #typescript #llm #rust #deep-learning #java #kubernetes #vue #pytorch #security #openai

(★ 37)

Desk device that mirrors live Claude Code session state onto a Cheap Yellow Display over BLE

tamaclaude Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">TamaClaude</h1>

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

🌐 English · <a href="README.th.md">ไทย</a>

<a href="#what-the-screen-says">What the screen says</a> ·
 <a href="#what-you-need">What you need</a> ·
 <a href="#1-get-the-repository-and-the-swift-compiler">Getting started</a> ·
 <a href="#troubleshooting">Troubleshooting</a>

> **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](LICENSE).
> - Reading your quota from claude.ai is optional and needs an account credential. Read
>   [step 5](#5-quota-on-the-board) 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**

**When nothing is happening**

**Quota**

| Normal | Running hot | Unknown |
|:--|:--|:--|
| ![usage](https://raw.githubusercontent.com/thaitop/tamaclaude/main/docs/images/screen_usage.gif) | ![usage hot](https://raw.githubusercontent.com/thaitop/tamaclaude/main/docs/images/screen_usage_hot.gif) | ![usage unknown](https://raw.githubusercontent.com/thaitop/tamaclaude/main/docs/images/screen_usage_unknown.gif) |
| 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. |

**The same bar, top and bottom**

Every page wears the same top bar — the page you are on, the current quota, the clock, and
whether the snapshot is arriving over Bluetooth or Wi-Fi — and never repeats what the page
below it already shows bigger. The foot carries the page pips: they say which page you are
on, and the lit one drains as the rotation clock runs down, so "where am I" and "how long
until it moves" are one row rather than two. The four data pages also keep a mini mascot down
there, so you can still see what your sessions are doing while you read the weather.

**The other pages**

The screen holds five pages now — the mascot, weather, crypto, stocks, and your calendar.
Swipe left or right across the glass to change page, or leave it alone and it turns on its
own every 20 seconds; a swipe holds that page for five minutes before the rotation picks up
where it left off. The board keeps the clock, so the pages keep turning with the Mac asleep,
and it jumps back to the mascot on its own when a session needs your answer.

If you would rather it stayed put, turn the round off in **Settings ▸ Screen** and the page
only ever changes when you swipe it. The board still jumps to the mascot when a session needs
you — and then goes back to the page you left it on, instead of stranding you there.

| Weather | Crypto | Stocks |
|:--|:--|:--|
| ![weather](https://raw.githubusercontent.com/thaitop/tamaclaude/main/docs/images/weather_rain.gif) | ![crypto](https://raw.githubusercontent.com/thaitop/tamaclaude/main/docs/images/crypto_full.gif) | ![stocks](https://raw.githubusercontent.com/thaitop/tamaclaude/main/docs/images/stocks_full.gif) |
| Now, today's high and low, and the next five hours — drawn under the sky of that hour. | The first coin gets a card with its logo and its 24-hour shape; the rest are one row each. | The same card, but the box plots where the price sits in today's swing instead. |

| Calendar | Long stale | Never arrived |
|:--|:--|:--|
| ![calendar](https://raw.githubusercontent.com/thaitop/tamaclaude/main/docs/images/calendar_full.gif) | ![stale](https://raw.githubusercontent.com/thaitop/tamaclaude/main/docs/images/weather_stale.gif) | ![no weather](https://raw.githubusercontent.com/thaitop/tamaclaude/main/docs/images/weather_empty.gif) |
| What is next, how long until it starts, and the two after it. | Far past the refresh window, so it says so out loud rather than in small print. | The page says what is missing instead of showing an empty frame. |

Every page says how old its figures are, because a Mac that sleeps freezes every number on
the screen. The mascot's own sky follows the weather page while it is at it — rain on the
weather page means rain behind the mascot.

Pages are turned on, reordered, and given their rotation in **Settings ▸ Screen**: one card,
the five pages in the order they come round, each row with its own switch and an arrow into
its settings. Weather needs a city name and comes from Open-Meteo, crypto from CoinGecko —
neither wants an account. Stocks come from Finnhub and need your own free API key; the free
plan covers US symbols and the page only refreshes while the US market is open. The calendar
is read from this Mac through EventKit, so macOS asks for calendar permission once and you
tick the calendars that may appear — nothing about it goes over the network. Watchlists hold
five symbols each, and the ones with artwork on the board are offered by name rather than
typed blind.

*Settings ▸ Screen — the round, in the order the board runs it.*

Your Mac does all the fetching, at its own pace per page. The board still never goes online
itself, and your session key never leaves the Mac.

**Over Wi-Fi**

| Still live | Nobody feeding it |
|:--|:--|
| ![lan](https://raw.githubusercontent.com/thaitop/tamaclaude/main/docs/images/screen_lan.gif) | ![wifi](https://raw.githubusercontent.com/thaitop/tamaclaude/main/docs/images/screen_wifi.gif) |
| Bluetooth is gone, so the icon in the top bar turns into a wave — but the snapshot still arrives, sealed, over the network, and every figure on the page stays live. | Nobody is feeding it: the bar says `no link` and the screen counts how long it has been since it last heard anything. |

## 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](https://claude.com/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

```bash
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:

```bash
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](#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](https://github.com/thaitop/tamaclaude/releases/latest). It is one file,
about 1 MB, containing the bootloader, the partition table and the app.

```bash
python3 -m pip install esptool
python3 -m esptool --chip esp32 --port "$PORT" \
    write_flash 0x0 ~/Downloads/tamaclaude-esp32-1.2.3.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:

```bash
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:

```bash
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:

```bash
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](https://docs.espressif.com/projects/esp-idf/en/v5.5/esp32/get-started/)
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

```bash
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

The settings window has four panes down its side — **Board**, **Screen**, **Wi-Fi**, and
**Claude**. Two of them matter now:

**gear ▸ Settings… ▸ Claude**

- **Hooks ▸ Install** — 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.
- **Launch at login** — so it is running before you start work.
- **Auto-start a session when idle** — off by default; when on, the app opens a session of
  its own only while nothing else is running.

**gear ▸ Settings… ▸ Board**

- **Use** — pick your board by name, or leave it on *Any board*.
- **Brightness** — the slider drives the screen's backlight. One brightness all day; it never
  dims on its own.

*Settings ▸ Claude and Settings ▸ Board.*

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 ▸ Claude) 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.
- **Session key ▸ Set…** (Settings ▸ Claude) lets the app ask claude.ai directly, so the
  number keeps moving even with Claude Code closed. **Refresh** 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.

![The statusline the app draws: directory, branch, model, changed lines, token count, then the 5-hour and weekly quota bars with a pace mark and a reset countdown](https://raw.githubusercontent.com/thaitop/tamaclaude/main/docs/images/statusline.jpg)

## 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 in
Settings ▸ Board 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 ▸ Claude → *Hooks ▸ Install*. Sessions
already open when you install them keep the old settings; start a new one. *Log ▸ Open* in
the same pane 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 pane 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.
- **Touch is swipes only, and the speaker is unused.** Left and right swipes change page;
  there are no taps, no touch zones, and nothing is wired to the speaker pin.
- **Touch constants were measured on one board.** A batch with a different panel may read
  differently; swipes are judged by coarse distance, which absorbs some of that but has not
  been confirmed on anyone else's board.
- **Ad-hoc signing.** The app is not notarised, so it is built per-machine rather than
  handed around.

## License

MIT — see [LICENSE](LICENSE).

tamaclaude

tamaclaude Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

tamaclaude

tamaclaude Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README