holocube-emotes

# Holocube Emotes

Turn a GeekMagic holocube into your AI's face. Generate holographic character sprites, upload them to the device, then swap expressions in real-time based on agent/session state.

## First-Time Setup

### 0. Find the device

Auto-discover holocubes on your network:

```bash
python3 scripts/holocube.py --discover
```

Output: `FOUND: 192.168.0.245 — HelloCubic-Lite V7.0.22`

If discovery fails, find the IP on the device's screen or your router's client list.

### 1. Generate sprites

Create a full emote sprite kit (requires nano-banana-pro skill with `GEMINI_API_KEY`):

```bash
python3 scripts/generate_sprites.py --output-dir ./sprites
```

Custom character:
```bash
python3 scripts/generate_sprites.py --output-dir ./sprites \
  --character "A glowing holographic cat floating in pure black void. Neon purple wireframe style."
```

This generates 7 emotes (neutral, happy, thinking, surprised, concerned, laughing, sleeping) as both static JPG and animated GIF, sized for the 240x240 display.

### 2. Upload to device

```bash
python3 scripts/setup_device.py --sprites-dir ./sprites --clear --backup-dir ./backup
```

Flags:
- `--clear` removes existing images (recommended — device has ~3MB storage)
- `--backup-dir` saves existing files before clearing
- `--ip` auto-discovers if not provided, or specify manually

### 3. Configure TOOLS.md

Add the holocube IP and emote mappings to your workspace TOOLS.md for reference. See references/tools-example.md.

## Daily Usage

### Set emote directly

```bash
python3 scripts/holocube.py happy
python3 scripts/holocube.py thinking --static   # Use JPG instead of GIF
```

### Set by agent state

```bash
python3 scripts/holocube.py working    # → thinking
python3 scripts/holocube.py complete   # → happy
python3 scripts/holocube.py error      # → concerned
python3 scripts/holocube.py opus       # → thinking (heavy model)
python3 scripts/holocube.py haiku      # → neutral (light model)
```

### Auto-select by time of day

```bash
python3 scripts/holocube.py --auto
```

- 11pm–7am → sleeping
- 7am–9am → happy
- Rest of day → neutral

### Check status

```bash
python3 scripts/holocube.py --status
python3 scripts/holocube.py --list
```

## Heartbeat Integration

Add to HEARTBEAT.md to auto-manage the emote:

```markdown
## Holocube Emote Check
- Run `python3 scripts/holocube.py --auto` to set time-appropriate emote
```

## When to Set Emotes

Use these during normal agent operations:

| Context | Command | Emote |
|---|---|---|
| Idle, waiting for input | `neutral` | 🤖 |
| Processing, running tools | `thinking` or `working` | 🔧 |
| Task completed | `happy` or `complete` | 😊 |
| Error occurred | `error` (→ surprised) | 😮 |
| Funny moment | `laughing` or `funny` | 😂 |
| Unexpected input | `surprised` or `unexpected` | 😮 |
| Night/inactive | `sleeping` or `night` | 😴 |
| Spawning sub-agent | `spawning` (→ thinking) | 🔧 |
| On-demand custom | `custom` | ✨ |

## Custom Slot

A reserved file `adam-custom.gif` on the device can be overwritten at any time for on-demand or one-off animations. Generate a GIF, upload as `adam-custom.gif`, then `python3 holocube.py custom`. Switch back to a standard emote when done.

## Device Notes

- **Model:** GeekMagic HelloCubic-Lite (240x240px glass display)
- **Format:** GIF (animated) or JFIF JPEG. Use Pillow for JPEG (ffmpeg lacks JFIF headers).
- **Storage:** ~3MB total. 6 animated GIFs use ~1.5MB, leaving ~500KB for custom slot.
- **Art style:** Dark/black backgrounds make glass disappear. Use glowing, holographic, neon elements.
- **⚠️ NEVER send `/set?reset=1`** — that's factory reset, wipes WiFi config.

## Requirements

- GeekMagic HelloCubic-Lite (or compatible) on local network
- Python 3 with Pillow (`pip install Pillow`)
- nano-banana-pro skill with `GEMINI_API_KEY` (for sprite generation only)
- `uv` (`brew install uv`) (for sprite generation only)