README.md

metadata

title: Puck
emoji: 🧚
colorFrom: green
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
license: mit
short_description: A mischievous desktop fairy that comments on your work
tags:
  - build-small
  - thousand-token-wood
  - off-brand
  - off-the-grid
  - field-notes
  - best-demo
  - track:wood
  - sponsor:nvidia
  - sponsor:modal
  - achievement:offgrid
  - achievement:offbrand
  - achievement:llama
  - achievement:fieldnotes

🧚 Puck — a desktop fairy familiar

Puck is a small, mischievous creature that lives on your screen. He roams, peeks at one little patch of whatever you're doing, and murmurs a single in-character line about it — then drifts on. He's not an assistant and not a notifier. He's company: marginally useful, reliably charming.

This Space is the playable demo (a simulated desktop in your browser). Puck's real home is a transparent always-on-top overlay on your actual Mac desktop — that's the video. Here you can poke him, watch him roam, peek, react, and blend into the desktop.

▶️ Demo video: watch on YouTube · 📣 Social post: on X · 📓 Field notes: read the writeup

What he does

• Roam → peek → quip. Every so often he flutters somewhere and looks at the small region under him. A vision-language model sees that patch and speaks in his voice in one shot — the AI is doing the fun thing, not narrating from a script.
• Feels things. Each peek is classified into an emotion that drives his whole reaction together — a gesture (giddy laugh, NANI-confusion, a worried tremble, a wistful droop), an aura color, and an emotional voice (pitch + pace). Puck's a learning creature, so confusion is his honest default — and endearing.
• Reads the room. On a real terminal he uses on-device OCR to tell which coding agent you're running (Claude Code vs Codex vs opencode vs pi) and grounds his quip in the actual text on screen.
• Camouflages. Sit still and he cloaks — his skin clears so the desktop reads right through him, with a faint shimmer and two watching eyes. Move, and he snaps back.
• Dreams. At night he blooms the day's peeks into a small garden of memories.

Built Small

Puck is a constellation of small, laptop-sized models — nothing over 32B, and it fits in your pocket:

• 👁️ Vision + voice-of-the-fairy: Holotron-12B — H Company's computer-use VLM post-trained from NVIDIA's Nemotron-Nano-12B-VL (one model that both sees and speaks the quip).
• 🔤 Tool/site recognition: on-device Vision OCR + an ONNX CLIP ViT-B/32 (~88M) fingerprinter.
• 🗣️ Neural voice: Kokoro-82M, running in-browser (WebGPU) — a fairy voice in 82M params.

The whole companion runs locally and offline ("Off the Grid"). This hosted Space uses a cloud (Modal) copy of the 12B so it works in your browser — which scales to zero, so the first peek may take a moment while Puck stretches his wings. ✨

Under the hood

A custom React UI served by a gradio.Server daemon (Off-Brand) — two habitats from one app: this browser sim, and a Tauri overlay for the real desktop. Region peeks, an emotion contract, a memory log that blooms into a garden.

HF Build Small — Thousand Token Wood (Creative).