Iris is an open-source interactive eye system built from sixteen hand-authored poses (11 gaze directions, blink frames, and expressions). Instead of swapping discrete images, a continuous gaze field bilinear-blends between neighbors so movement feels smooth and alive — whether the input is a webcam, a mouse, or manual control.

The repo ships three isolated packages, each tuned to a different surface:

user-tracker/ — Pygame desktop viewer with optional MediaPipe face tracking. Your position in the webcam frame maps to gaze in real time. Toggle manual vs tracking, run ASCII or PNG render modes, and use it as a standalone demo or kiosk display.

web-tracker/ — A reusable Next.js <Eyes /> client component with pointer tracking, canvas bloom, and a full behavior layer: auto-blink, idle drowsy, click → wide, cursor-shake → chase → squint. Props cover render mode, glow, smoothing, controlled expressions, and per-frame telemetry. Live demo: eyes-that-follow.vercel.app.

lively-wallpaper/ — The same eyes as an interactive Windows desktop wallpaper via Lively Wallpaper. Cursor follow, customizable hue/scale/glow/FPS, and a CPU-conscious render loop that pauses when the wallpaper is hidden. Download Iris.zip from GitHub Releases.

All three share the same asset pipeline (output/ PNG + ANSI) and the same design language: ember-red glow, black void background, and optional duotone recoloring via an SVG luminance filter.Creative ways to use itThe components are deliberately modular — the hard part (gaze blending, expression precedence, reactive behaviors) is done; you plug in input and context:Landing pages & portfolios — Drop <Eyes /> on a hero section so the site literally watches the visitor. Works as ambient presence without a full character rig.AI / agent interfaces — Wire onTelemetry to your chat or voice pipeline so eyes drift toward activity, go drowsy when idle, or react when the user clicks — cheap “alive” feedback for bots and copilots.Stream overlays & OBS — Run the web component in a browser source; pointer or scripted expression overrides become a reactive mascot layer.Installations & kiosks — Use user-tracker --track for face-following displays at events, booths, or museum pieces where the artwork tracks whoever stands in frame.Desktop identity — Lively wallpaper for a personalized, reactive desktop that’s more than a looped video.Horror, sci-fi, and retro UI — ASCII mode reads as terminal/cyberpunk; PNG mode reads as cinematic. Same API, different aesthetic for games, ARGs, or album art sites.Embedded widgets — Scale, tint, and glow are all props/settings — the eyes can fill a stage or sit small in a corner as a “watching” indicator.Forking & extension — New gaze states are a PNG + neighbor graph entry + asset sync; behaviors live in a DOM-free state machine you can unit test and extend (e.g. new triggers, synced to music, tied to system events).The project is MIT-licensed and structured so you can take one package without the rest — eyes on the web, on the desktop, or behind your icons.