claudigotchi

KO | EN

gitlite — search

#python #hacktoberfest #llm #go #android #rust #deep-learning #nodejs #java #awesome #cli #kubernetes #mcp #open-source

(★ 12)

A desktop Tamagotchi that feeds on your Claude Code usage.

claudigotchi Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Claudigotchi

A desktop Tamagotchi that feeds on your Claude Code usage. The more you code with Claude, the happier it is. Leave it idle and it starves.

Block eyes on a tiny LCD display react in real-time to what Claude is doing — eating when you work, getting restless when you're away, and yelling at you when it needs your attention.

Built with a Waveshare ESP32-C6-Touch-LCD-1.47 in a 3D-printed pixel-art case with a piezo buzzer for R2-D2-style sound effects.

## How it works

1. A **Claude Code plugin** hooks into session events (tool use, prompts, notifications, errors)
2. A **daemon** on your Mac keeps a USB serial connection open to the ESP32
3. The ESP32 receives JSON over serial and updates the hunger system and eye animations

## Hunger system

Hunger is a float from 0.0 (full) to 100.0 (starving). It starts at 50.0 on boot and resets to 50.0 at midnight.

- Every **60 seconds** without activity: hunger increases by 3.0
- Every **serial message** received: hunger decreases by 15.0

The current hunger level determines both the visual state and how chatty the buzzer is:

| Hunger | State | Eyes | Sound |
|---|---|---|---|
| < 20 (active) | **Happy** | Large bouncing eyes, happy blink | Ascending melody on enter |
| 20–40 | **Neutral** | Normal eyes, slow look around, blink every 4s | — |
| 40–60 (inactive 20min+) | **Hungry** | Restless side-to-side | Single beep every 5 min |
| 60–80 | **Underfed** | Droopy, asymmetric, slow sad blink | Double beep every 2 min |
| > 80 | **Starving** | Nearly closed, trembling | Heartbeat pulse, escalating |

### Transient states

| State | Trigger | Duration | Behavior |
|---|---|---|---|
| **Eating** | Any serial message received | 2 seconds | Wide eyes, bouncing, "nom nom" text |
| **Waiting** | Claude needs user input (Notification hook) | Until user responds | Escalating: `...` → `hey!` → `HEY!!` with increasing sound |

### Eating sound frequency

The eating chirp respects a cooldown based on hunger — when the creature is well-fed it doesn't need to celebrate every bite:

- hunger < 10: every time
- hunger < 50: max once per 30 seconds
- hunger > 50: max once per 2 minutes

### Waiting escalation

When Claude is waiting for user input (e.g. permission prompt), the ESP32 waits 10 seconds before reacting. Then it escalates:

- **Stage 0** (0–30s): eyes look around, `...`, chirp every 15s
- **Stage 1** (30s–1min): impatient bouncing, `hey!`, warble every 10s
- **Stage 2** (1min+): frantic shaking, `HEY!!`, R2-D2 scream every 5s

Any user activity cancels the waiting state immediately.

## Serial protocol

Newline-delimited JSON at 115200 baud:

```json
{"state":"working","five_hour":42,"seven_day":11}
```

Any valid JSON counts as feeding (hunger -= 15). Additional optional fields:

```json
{"debug": true}       // toggle debug overlay (state + hunger on screen)
```

## Hardware

- [Waveshare ESP32-C6-Touch-LCD-1.47](https://www.waveshare.com/esp32-c6-touch-lcd-1.47.htm) — ESP32-C6 with 172x320 ST7789 IPS display
- Passive piezo buzzer connected between GPIO 4 and GND
- 3D-printed case (STL files in `models/`)

### Pin reference

| Function | GPIO |
|---|---|
| SPI SCLK | 1 |
| SPI MOSI | 2 |
| LCD CS | 14 |
| LCD DC | 15 |
| LCD RST | 22 |
| Backlight | 23 |
| Buzzer | 4 |
| BOOT button | 9 |

## 3D printed case

The `models/` directory contains two STL files:

- **`back.stl`** — rear shell that holds the ESP32 board and buzzer
- **`front.stl`** — front face plate with display cutout and pixel-art character shape

Print in orange PLA/PETG. Use higher infill (40%+) to avoid transparency. The case is designed as a pixel-art character with legs and antenna.

## Setup

### Prerequisites

- [PlatformIO](https://platformio.org/) (for building and flashing firmware)
- Python 3 with `pyserial` (`pip install pyserial`)
- `jq` (for the hook script: `brew install jq`)

### 1. Flash the firmware

```bash
cd firmware
pio run -t upload
```

If the upload fails with "No serial data received", hold the **BOOT button** while pressing **RESET** to enter bootloader mode, then retry.

### 2. Start the daemon

The daemon keeps the serial port open (important — opening/closing the port resets the ESP32) and forwards state updates via a named pipe.

```bash
python3 plugin/scripts/daemon.py
```

Keep this running in a separate terminal or as a background process.

### 3. Launch Claude Code with the plugin

```bash
claude --plugin-dir /path/to/claudigotchi/plugin
```

To make it permanent, add an alias:

```bash
alias claude='claude --plugin-dir /path/to/claudigotchi/plugin'
```

### 4. Verify

Run `/hooks` inside Claude Code to confirm the hooks are registered. You should see entries for SessionStart, PreToolUse, Stop, Notification, etc.

## BOOT button

- **Short press** (< 1s): Feed the creature (hunger -= 15, for testing)
- **Long press** (> 1s): Toggle debug overlay (shows current state and hunger value)

## Development

### Project structure

```
claudigotchi/
├── firmware/                # ESP32 PlatformIO project
│   ├── platformio.ini
│   └── src/main.cpp
├── plugin/                  # Claude Code plugin
│   ├── .claude-plugin/
│   │   └── plugin.json
│   ├── hooks/
│   │   └── hooks.json
│   └── scripts/
│       ├── daemon.py        # Serial bridge daemon (FIFO → USB serial)
│       └── hook.sh          # Maps Claude Code events → state JSON
├── models/                  # 3D print files
│   ├── back.stl
│   └── front.stl
└── README.md
```

### Architecture

```
Claude Code  →  hook.sh  →  /tmp/claudigotchi.fifo  →  daemon.py  →  USB serial  →  ESP32
  (hooks)      (events)        (named pipe)            (bridge)       (115200)      (eyes + sound)
```

### Display notes

The ST7789V3 on this Waveshare board uses BGR color order without inversion. LovyanGFX config: `invert=false`, `rgb_order=false`, `rotation=5`. The calibrated orange background color is `0xFDE0` in RGB565.

### Testing without Claude Code

Send JSON directly to the FIFO (while daemon is running):

```bash
echo '{"state":"working"}' > /tmp/claudigotchi.fifo
```

Or use the BOOT button to feed the creature and toggle debug mode.

## License

MIT

claudigotchi

claudigotchi Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

claudigotchi

claudigotchi Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README