holocube-emotes

name	holocube-emotes
description	Control a GeekMagic holocube display as an AI emote system. Generate holographic sprite kits with Gemini, upload to device, and swap expressions based on agent state (idle, working, error, etc.). Use when the user has a GeekMagic holocube (HelloCubic-Lite or similar) and wants their AI assistant to have a physical face that reacts to conversation context.

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:

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):

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

Custom character:

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

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

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

Set by agent state

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

python3 scripts/holocube.py --auto

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

Check status

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

Heartbeat Integration

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

## 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)