●  v1.0.0 · MIT · macOS / Windows / Linux

A desktop pet that breathes with your code.

Seelie is a 10 MB native companion that listens on UDP and reacts to every event your AI coding tool emits. Pick a character with proactive tips, or an ICU-style ECG monitor whose pulse tracks your session.

Download Free→See what's new
Two display modes—Character/ECG
§02 — Pet State Machine

A coherent personality, not a flicker reel.

Seven sustained states + one walking overlay. Working holds across tool gaps, Failed restores Working after the overlay, Greeting only fires from Idle — no ungraceful interrupts when events burst.

01
Idle
no activity
02
Greeting
from idle only
03
Thinking
prompt.submitted
04
Working
tool.before
05
Reviewing
subagent / review
06
Failed
overlay, restores
07
Celebrating
overlay, restores
+ Walking
movement layer
Grace timers. Sustained states don't snap. A short gap between two tool.before events isn't enough to drop out of Working — a 3 s grace timer keeps the character in character.
§03 — Multi-provider TTS

Your pet, out loud.

Tips can speak. Pick from four cloud providers, hot-swap without restart, paste any voice ID — system, cloned, or beta. Audio is cached locally so repeats replay instantly.

Settings · TTS⌘ ,
ProviderStepFun
Token••••••••••••••••••••
Voicecixingnansheng
Modelstep-tts-mini
✓ Synthesised · 412 ms · cached
On-disk voice cache
  • — 100 MB LRU bound
  • — SHA-256 keyed on (provider, voice, model, options, text)
  • — Auto-invalidated on voice / model change
§04 — Features

Built for the long haul

Eight things you'll notice the moment you launch it

F·01

17 canonical events

session.start, tool.before, tool.failed, prompt.submitted, file.edited… each one drives an animation, a tip, or an ECG heartbeat — no gateway-specific code paths.

F·02

Three animation engines

Lottie at 60 fps for vector character anims, Live2D Cubism for expressive models, and a sprite-sheet fallback for retro Clippy-era packs.

F·03

Proactive tips engine

A pattern matcher on a 30 s sliding window detects coding behaviors and surfaces contextual suggestions with a 5-minute cooldown per type.

F·04

Under 10 MB at idle

Native Qt6/C++, no Electron. UDP listener + animation engine — your CPU and battery won't even notice.

F·05

.codex-pet, drag & drop

Native parser for the .codex-pet format from openai/skills' hatch-pet. Drop the file — Seelie reads the 8×9 atlas (192×208 cells) and renders directly, no conversion.

F·06

Global hotkey

Default Ctrl+Shift+O shows or hides the pet from anywhere. Configurable in Settings. Works during fullscreen apps too.

F·07

Gaming Mode

Detects fullscreen apps and steps out of the way — restored automatically when you exit fullscreen. No more pet in front of your boss fight.

F·08

Live i18n

English and Simplified Chinese, hot-swapped from the settings panel. UI, tips, menus update instantly — no restart, no flash.

§06 — Protocol

Framework-agnostic IPC

Newline-delimited JSON over UDP. Works with Claude Code, Codex, OpenCode, Kimi, and anything else that can write a socket.

127.0.0.1:52847 by default. One protocol, 17 events, any tool — any language.

Shellecho {"type":"event","source":"claude-code","event":"session.start"} | nc -u 127.0.0.1 52847
§07 — Integrations

Copy-paste integrations

Hook configs for Claude Code, OpenCode, Codex, Kimi, plus a raw protocol for anything else

~/.claude/settings.json
{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "seelie-gateway --source claude-code --event session.start"
      }]
    }],
    "PreToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "seelie-gateway --source claude-code --event tool.before"
      }]
    }],
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit|NotebookEdit",
        "hooks": [{
          "type": "command",
          "command": "seelie-gateway --source claude-code --event file.edited"
        }]
      },
      {
        "hooks": [{
          "type": "command",
          "command": "seelie-gateway --source claude-code --event tool.after"
        }]
      }
    ],
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "seelie-gateway --source claude-code --event session.end"
      }]
    }]
  }
}

Install the gateway globally: npm install -g @eastlake/seelie-gateway. Make sure Seelie is running and the gateway is on PATH (see README for fnm/nvm wrapper).

AI agentsview the setup skill →
§08 — 1.0.0 audit pass

Quietly hardened.

An end-to-end audit closed a dozen latent issues in 1.0.0 — most invisible to users, all worth shipping.

01ZIP path traversal.opk archives can't escape the pack root
02Audio decode cap50 MB ceiling — hostile audio headers can't OOM
0330 s HTTP timeoutsHung TLS handshakes never wedge TTS
04FBO dimension clampLive2D frame sizes clamped to [1, 4096]
05Debounced config500 ms save coalesces drag-write storms
06Manifest size cap10 MB ceiling before allocating from central directory
§09 — Setup

Three steps to joy

Step 01

Install

Native installers for macOS, Windows, and Linux

Step 02

Connect

Add a hook to your AI tool — Seelie auto-binds on UDP

Step 03

Enjoy

Watch the pet breathe with every event you send

§10 — ECG Mode

ECG Monitor Mode

A second display option, exclusive with the character pet

Pick this mode in Settings → Mode. The ICU-style chassis sits where the character did and reacts to every gateway event: heart rate jumps on session.start / tool.before, a red border flashes for tool.failed and session.error, and 20 s of silence flatlines into asystole — until the next event revives the patient.

ECG Monitor
HR 72 BPM
Trigger a gateway event

Stop poking buttons for 20 seconds — you'll watch the patient code.

§11 — FAQ

Questions?

§12 — Download

Bring your desktop to life.

Free, MIT, 10 MB, no telemetry. Download for your platform and add one hook.

Download Seelie→