English | 简体中文

Pi-Pompom — a terminal pet for Pi CLI with voice, ambient weather, side chat, and agent-aware commentary.

pi-pompom

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

Install · Why Pompom · Side Chat · Pi Listen · Agent Intelligence · Voice Setup · Commands · Shortcuts · Demo · Features · Settings

Pompom is an interactive coding companion for Pi CLI. She lives in your terminal while you code, watches your agent work, and lets you talk to her about what's happening in your session without interrupting anything.

Install

pi install @codexstar/pi-pompom

For the best experience, use a GPU-accelerated terminal like Ghostty or Kitty.

Why Pompom

Pompom is not just a cute face. She is a parallel AI assistant that runs alongside your main coding agent.

• Side Chat (⌥/ or Alt+/) opens a floating AI panel. Ask her what the agent is doing, what went wrong, or get a full session recap. She watches every tool call and catches errors in real time.
• Voice Input with Pi Listen. Hold Space to talk directly to Pompom when her chat is focused.
• Agent Dashboard shows active tools, success rates, mood, and timing.
• Stuck Detection alerts you when your agent is looping on errors or stalled.
• Session Analysis gives you deep AI-powered insights and recommendations.

While all of that works in the background, she is also playful. She asks you to pet her, give her treats, throw a ball, dance together, and sing songs. She reacts to real weather, wears accessories, plays ambient sounds, and has a full mood system.

Side Chat

Press ⌥/ (macOS) or Alt+/ (Windows/Linux) or run /pompom:chat to open a floating AI chat panel alongside the main agent.

• Pompom has her own AI instance running in parallel. She does not interrupt your main agent.
• Read-only tools only. 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 in the chat for built-in shortcuts: analyze, stuck, recap, status.
• Per-session conversations. Each new session starts fresh.
• Anchored at the center of the viewport, 60% max height.
• Press Esc to close, ⌥/ to toggle focus.

Pi Listen / Voice Input

Pompom integrates with Pi's built-in voice input system. When Pompom's side chat is focused, holding Space activates pi listen and your speech is transcribed directly into the chat.

How it works:

1. Open side chat with ⌥/ (macOS) or Alt+/
2. Hold Space to start talking
3. Release Space and your speech gets transcribed into the Pompom chat
4. Pompom responds as a separate AI, with full context of what the main agent is doing

What happens during voice input:

• Pompom's mouth animates in sync with your audio level
• All TTS playback pauses automatically so your mic stays clean
• All sound effects are silenced
• Ambient weather sounds duck to a lower volume
• Everything resumes when you stop recording

No extra setup needed. If pi listen works in your Pi CLI, it works with Pompom's chat.

Agent Intelligence

Pompom watches your coding agent and reacts in real time.

AI Analysis Commands

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. Storms on errors, snow on celebrations.

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.

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.

Voice Setup

Pompom supports 3 TTS engines. ElevenLabs gives the best experience with expressive audio tags.

Quick Setup

/pompom:voice setup

This walks you through picking an engine, selecting a voice, and testing it.

Engines

Audio tags are engine-aware. ElevenLabs keeps [laughs], Kokoro and Deepgram get them stripped automatically.

Voice Commands

6 Personalities

Commands

Pet Actions

Audio & Ambient

Utilities

Keyboard Shortcuts

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

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

Demo Mode

Run an autonomous narrated showcase of every feature (~135 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.

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
• 4 color themes: Cloud, Cotton Candy, Mint Drop, Sunset Gold
• Natural animations: blinking, breathing, ear wiggling, tail wagging
• Widget renders at ~7 FPS via 150ms interval

Weather & Physics

• Smooth sky color transitions (dawn to dusk)
• 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
• Rain splash particles with ripple effects
• Snow accumulation as sparkle particles at ground level
• Wind system: storms push ears, antenna, body, and tail
• Ball physics with air resistance and spin transfer
• Firefly that glows brighter at night
• Weather-aware reactions every 2-5 minutes

Ambient Weather Sounds

Background audio that matches the current weather with 23 layered sound effects.

• Custom audio: drop files in ~/.pi/pompom/ambient/custom/
• Falls back to ElevenLabs Sound Effects API (cached locally)
• Auto-ducks during voice playback and sleep
• Linux ALSA support with WAV format generation

Emotional Reactions

Pompom expresses emotions based on her needs:

• Hungry (<30%): asks for food with sad expressions
• Starving (<15%): dramatic hunger pleas
• Tired (<15%): sleepy whispers and yawns
• Happy (>80%): laughing and singing
• Playful (>60%): asks to play, dance, throw balls

19 spontaneous activity requests. She asks you to play, sing, dance, hug, and feed her during positive emotional states.

Weather Accessories

• /pompom give umbrella for rain/storm
• /pompom give scarf for snow
• /pompom give sunglasses for clear weather
• /pompom give hat as 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
• Score announced with game-end jingle

Multi-Terminal Awareness

• Primary instance election via heartbeat files (oldest terminal wins)
• Only the primary terminal plays ambient audio, weather SFX, and greetings
• /pompom demo narration plays in the terminal that starts it
• User-triggered SFX play on the active terminal
• /pompom:terminals shows all running instances

Settings Panel

Run /pompom-settings to open the interactive 9-tab settings panel. No commands to memorize. Everything is right there.

Navigate with arrow keys, Enter to select, Esc to close.

Footer

Pompom adds a compact, information-rich status bar at the bottom of your Pi terminal.

• 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 shows just the face, ultra-wide shows everything

Theme

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

• Warm pink accent with rosewater text
• Cozy message bubbles, gentle green/red tool result glows
• Thinking level borders that progress from cold/dark to warm/pink
• 51 color tokens fully compliant with Pi's theme schema

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