💀🔥 Pyrejam

A terminal flaming-skull rocker that dances to your Spotify music while watching your AI coding agents burn tokens.

The skull's fire is your burn-rate meter — a runaway agent shows up instantly as an inferno screaming from the corner of your screen.

Note — demo recording coming soon (docs/demo.gif, TODO).

What is this?

Pyrejam is a tiny, fun, useful terminal companion you leave open while you code with an AI agent. It does two things at once:

• Watches your spend. It tails your pi agent sessions and shows live cost, today's total, tokens, cache hit-rate, budget, and context fill — all recomputed from the session files, so it's always accurate and survives restarts.
• Makes it fun. A flaming pixel skull headbangs to your Spotify music. Its mood, eye-glow, and flame height are driven by your burn rate — chill amber embers when you're idle, a white-hot inferno when an agent is hemorrhaging dollars.

Fun and useful are the same pixels: burn = amp gain, budget = set length, context = time-til-stage-dive.

Install

npm install -g pyrejam
pyrejam

Or run it without installing:

npx pyrejam

Usage

Run pyrejam in its own terminal window while you work with pi in another. It passively reads your pi session files — nothing to configure to get started.

| Key | Action | | --- | --- | | space | play / pause Spotify | | n / → | next track | | p / ← | previous track | | + / - | volume | | m | mute (restores previous volume) | | t | tap tempo | | b | toggle rock / plain labels | | q | quit |

Features

• 🔥 Burn-rate mood — the skull's flame + colour track your live $/min; a gain meter goes to 11.
• 💸 Honest wallet — today's spend, session cost, tokens, and cache % summed across all your pi sessions, recomputed from disk every tick (restart-proof).
• 🎸 Spotify transport — now-playing + full playback control from the keyboard, via osascript.
• 🥁 Beat-synced dance — a tap-tempo metronome phase-locked to the Spotify position; the skull steps and the EQ pulses on the beat.
• 🎚️ Always alive — a four-state matrix (music × activity) means the skull is never frozen: full rock show, music visualizer, unplugged token-headbang, or an idle breathing screensaver.
• 🤘 Celebrations — cache wins and cheap turns flash the skull green with horns up.
• 🎨 Truecolor pixel art — a half-block rendered, gradient-shaded visual with graceful 256-color / non-TTY fallbacks.
• 🧩 Pluggable visualizers — the flaming skull is the first (and default) visual. The renderer is built so more animation types can drop in; the live signals (beat, burn rate, mood) stay the same.

How it works

   Spotify (osascript)        pi sessions (~/.pi/agent/sessions/*.jsonl)
          │                                  │
     BeatSource                        ActivitySource
   (tempo + beat ticks)          (token bursts + usage/cost)
          └───────────────┬──────────────────┘
                          ▼
                  Ink render core
        flaming skull · EQ · gauges · counters

• ActivitySource tails pi's session JSONL. The most-recently-active session drives the skull; the wallet aggregates every session since local midnight.
• Burn rate ($/min) maps to the skull's mood: chill → working → shred → inferno, with an auto-calibrated panic line (~3× your trailing-hour median).
• BeatSource is a tap-tempo metronome phase-locked to the Spotify player position. (A real audio-tap beat is on the roadmap.)

Configuration

On first run Pyrejam writes ~/.pyrejam/config.json:

| Field | Default | Meaning | | --- | --- | --- | | budgetCap | 10 | Daily budget in dollars (the BUDGET gauge) | | lingo | "rock" | "rock" or "plain" labels | | lastTempo | 120 | Remembered tap-tempo BPM | | burnThresholds | (unset) | Optional absolute $/min thresholds; overrides auto-calibration |

Requirements

• macOS (Spotify control uses osascript).
• A truecolor terminal for the best skull — Kitty, iTerm2, Ghostty, WezTerm. Falls back to 256-color elsewhere.
• Node 18+.
• pi for the token data (Spotify is optional — without it you get an idle visualizer).

Roadmap

• 🔊 Real beat detection via a macOS Core Audio tap on Spotify (replacing the metronome).
• ⚡ Live per-token intensity via a pi extension streaming deltas over a socket.
• 🤖 Claude Code as a second token provider (~/.claude/...).
• 🎭 More visualizers — additional animation types beyond the flaming skull (the visual layer is pluggable).

Contributing

PRs welcome — see CONTRIBUTING.md. Be excellent to each other: Code of Conduct.

License

MIT © Pyrejam contributors