English | 简体中文

pi-pompom

A 3D raymarched virtual pet with voice, ambient sounds, AI side chat, weather physics, and agent intelligence — for Pi CLI.

Install · Quick Start · Demo · Commands · Shortcuts · Features · Side Chat · Agent Intelligence · Settings · Theme

Pompom is an interactive coding companion for Pi CLI. It renders a real-time 3D raymarched creature above your editor, speaks with natural TTS voices, plays ambient weather soundscapes, tracks your coding agent's mood, offers an AI side chat with voice input support, and reacts emotionally to hunger, tiredness, weather, and your interactions.

Install

pi install @codexstar/pi-pompom

Quick Start

Pompom appears automatically when you start Pi. Toggle it with:

/pompom on
/pompom off

Open the interactive settings panel with /pompom-settings — 9 tabs covering every feature, no commands to memorize.

Demo Mode

Run an autonomous narrated showcase of every feature (~95 seconds):

/pompom demo

Pompom narrates each feature as it happens — interactions, weather transitions, accessories, games, sleep/wake, color themes. Run /pompom demo again to stop early. Great for recording videos.

Commands

Pet Actions

Voice & Audio

AI & Agent Intelligence

Keyboard Shortcuts

Note: Alt+f, Alt+b, Alt+d, Alt+h, Alt+w are used by Pi's built-in editor. Pompom uses safe alternatives that don't conflict.

Four input methods supported: Ghostty keybinds, ESC prefix, macOS Unicode, Kitty keyboard protocol.

Features

3D Rendering

• Raymarched body with real-time lighting, shadows, and floor reflections
• Hybrid renderer: Unicode quadrant blocks at edges (2x detail), half-blocks in smooth areas
• Kawaii face: white sclera eyes, brown iris, layered pupil/highlights, bright face plate
• 4 color themes: Cloud, Cotton Candy, Mint Drop, Sunset Gold
• Natural animations: blinking, breathing (dual-frequency), ear wiggling, tail wagging
• Visible body pulse synced to breathing cycle
• Widget re-renders at ~7 FPS via 150ms interval

Weather & Physics

• Smooth sky color transitions (dawn to dusk via keyframe interpolation)
• Sun disk with halo, crescent moon with glow, twinkling stars
• Rolling hills, swaying grass with flowers, drifting cloud wisps
• 5 weather types: clear, cloudy, rain, storm, snow
• Arc-based weather transitions with intensity ramping (0.0 to 1.0 over 90s)
• Rain splash particles: multi-droplet splashes on ground impact with ripple effects
• Snow accumulation: settled snowflakes persist as sparkle particles at ground level
• Wind system: storms/rain/snow create wind force that pushes ears, antenna, body, and tail
• Wind gusts: storms have random burst gusts that push Pompom asymmetrically
• Cloud shadows: drifting dark patches across the ground during cloudy/rain/storm
• Ball physics: air resistance, spin transfer on bounce, realistic energy loss
• Firefly: brighter and larger at night, dimmer during day, pulsing glow
• Weather-aware periodic reactions every 2-5 minutes

Text-to-Speech (3 Engines)

Audio tags are engine-aware — ElevenLabs keeps [laughs], Kokoro and Deepgram get them stripped automatically. No engine loses features because of another.

6 Voice Personalities

Emotional Reactions & Activity Requests

Pompom expresses natural emotions based on her needs using ElevenLabs v3 audio tags:

• Hungry (<30%): [sad] My tummy is rumbling..., [crying] Feed me!
• Starving (<15%): [wheezing] Everything looks like food...
• Tired (<15%): [whispers] Just five more minutes..., [sighs] I'm so sleepy...
• Happy (>80%): [laughs] Life is good!, [sings] La la la, happy me!
• Playful (>60%): [excited] Let's play a game!, [mischievously] Wanna throw the ball?

19 spontaneous activity requests — Pompom asks you to play, sing, dance, hug, feed, and more, with shortcut hints shown in the speech bubble. Fires every 2+ minutes during positive emotional states.

Rate-limited to one emotional line every 45 seconds.

Ambient Weather Sounds

Background audio that matches the current weather, with layered one-shot sound effects.

Ambient loops (continuous, looping):

• Custom audio from Envato Elements or any source — drop files in ~/.pi/pompom/ambient/custom/
• Falls back to ElevenLabs Sound Effects API generation (cached locally)
• Auto-ducks to 20% during voice playback, 35% during sleep
• Linux ALSA support: generates WAV format (with PCM+WAV header) when aplay is the detected player

23 layered sound effects (one-shot, contextual):

SFX features: micro-variations (3 variants per sound), time-of-day filtering (crickets at night, birds during day), mood-reactive layers, volume jitter (±15%), sleep ducking, crossfade on ambient loop restart.

Weather Accessories

• Pompom asks for accessories when weather changes (sunglasses during clear daytime)
• /pompom give umbrella — appears during rain/storm
• /pompom give scarf — appears during snow
• /pompom give sunglasses — appears in clear weather
• /pompom give hat — a cute collectible
• Accessories persist across sessions

Mini-Game: Star Catcher

• /pompom game starts a 20-second challenge
• Golden stars fall from the sky with sparkle effects
• Star chime plays on each catch
• Score announced with game-end jingle

Contextual Shortcut Bar

The status bar below Pompom shows only the 3-4 most relevant shortcuts for her current state:

• Sleeping: only ⌥a Wake
• Hungry: ⌥e Feed highlighted in peach
• Tired: ⌥s Sleep highlighted in lavender
• State-specific: idle/walk/singing/game each get their own relevant shortcuts
• Bold keys with paw icon prefix, dim labels, right-aligned state message

Side Chat

Press Alt+/ or run /pompom:chat to open a floating AI chat panel alongside the main agent.

• Pompom has her own AI instance running in parallel — doesn't interrupt your main agent
• Read-only tools — safe inspection mode, no accidental file edits
• peek_main tool lets Pompom see what the agent is working on (with redacted tool output)
• Type help for built-in shortcuts: analyze, stuck, recap, status
• Pi Voice integration: hold-to-talk with pi listen types directly into the Pompom chat when it's focused
• Per-session conversations — each new session starts fresh
• Anchored at the center of the viewport, 60% max height
• Press Esc to close, Alt+/ to toggle focus

Agent Intelligence

Pompom watches your coding agent and reacts in real time.

7 Mood States

idle → curious → focused → busy → concerned → celebrating → sleepy

Mood is determined by tool call patterns, error rates, and activity timing. Weather reflects agent state — storm on errors, snow on celebrations.

Commentary System

10 event buckets with probability-based speech: agent start/end, tool calls, tool errors, messages. Commentary gap: 30s minimum between lines, 60s for same bucket.

Stuck Detection

Monitors consecutive error streaks, stalled progress (>5 min), high error rate (>50%), and repetitive tool calls. Pompom alerts with a speech bubble when confidence is high.

AI Analysis Commands

• /pompom:ask <question> — ask anything about the current session
• /pompom:recap — concise session summary
• /pompom:analyze — deep AI-powered analysis with recommendations
• /pompom:agents — real-time dashboard: active tools, success rate, mood, timing

Multi-Terminal Awareness

• Primary instance election via heartbeat files (oldest terminal wins)
• Only the primary terminal plays ambient audio, weather SFX, and greetings
• Secondary terminals run visual-only (animation renders, no audio)
• User-triggered SFX (pet, feed, etc.) play on the active terminal
• /pompom:terminals shows all running instances

Settings Panel

Run /pompom-settings to open the interactive 9-tab settings panel.

Fully responsive — adapts to any terminal width. 2-column action grid for wide terminals, scrolling tab bar with indicators for narrow ones. Navigate with arrow keys, Enter to select, Esc to close.

Theme

Pompom ships with a Catppuccin Mocha warm theme (themes/pompom.json) that auto-activates on install:

• Warm pink accent (#f5c2e7) with rosewater text for conversations
• Cozy message bubbles (#362933), gentle green/red tool result glows
• Thinking level borders that progress from cold/dark to warm/pink
• Warm syntax highlighting: rosewater variables, flamingo inline code
• 51 color tokens fully compliant with Pi's theme schema
• Custom warm_surface, warm_bubble, warm_green_glow, warm_red_glow, warm_border vars

Single-Line Footer

A compact status bar at the bottom of Pi with progressive disclosure:

• Pompom's mood face + name (always visible)
• Hunger/energy bars with color-coded thresholds
• Weather icon + agent activity indicator
• Session timer, context usage bar, working directory, cost tracker
• Voice and ambient audio indicators
• Model name (intelligently shortened)
• All Nerd Font icons, Catppuccin Mocha colors, Powerline separators

Adapts content based on terminal width: ultra-narrow (face + model only) to ultra-wide (all indicators).

How It Works

The renderer is a software raymarcher running in your terminal. Each frame:

1. Physics simulation updates position, particles, and state machines (60fps sub-stepping)
2. Scene objects (body, ears, paws, tail, antenna, ball, food, accessories) are built with rotation, oscillation, wind lean, and breathing scale
3. For each cell, 4 quadrant samples are taken. Edge cells use quadrant characters for 2x horizontal detail. Smooth cells use half-blocks.
4. Object hits are shaded with diffuse + wrap lighting, ambient occlusion, specular highlights, subsurface scattering, and firefly point light
5. The shaded pixels are encoded as ANSI true-color escape sequences
6. Speech bubbles, weather particles (rain/snow/splash/accumulation), and overlays are composited on top

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Security

See SECURITY.md for reporting vulnerabilities.

License

MIT. See LICENSE.

Made by Abhishek Tiwari

Website · 𝕏 Twitter · GitHub · npm · Report a Bug · Pi CLI