vibeaudio 0.20.0 → 0.21.0

package/README.md

@@ -1,11 +1,13 @@
 # 🎧 VibeAudio
 
 <p align="center">
-  <img src="docs/og.png?v=2" alt="VibeAudio — Focus music while your AI codes" width="720">
+  <img src="docs/og.png?v=3" alt="VibeAudio — Focus music while your AI codes" width="720">
 </p>
 
 [![test](https://github.com/kiril6/vibeaudio/actions/workflows/test.yml/badge.svg)](https://github.com/kiril6/vibeaudio/actions/workflows/test.yml) [![npm](https://img.shields.io/npm/v/vibeaudio)](https://www.npmjs.com/package/vibeaudio) [![license](https://img.shields.io/npm/l/vibeaudio)](LICENSE) [![node](https://img.shields.io/node/v/vibeaudio)](https://nodejs.org) [![downloads/month](https://img.shields.io/npm/dm/vibeaudio)](https://npm-stat.com/charts.html?package=vibeaudio) [![M8ven Score](https://m8ven.ai/badge/mcp/kiril6/vibeaudio)](https://m8ven.ai/mcp/kiril6/vibeaudio?s=readme)
 
+<a href="https://www.producthunt.com/products/vibeaudio/reviews/new?utm_source=badge-product_review&utm_medium=badge&utm_source=badge-vibeaudio" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/product_review.svg?product_id=1317092&theme=light" alt="VibeAudio - Focus&#0032;music&#0032;while&#0032;your&#0032;AI&#0032;codes&#0046; | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
+
 > **Procedural focus music while your AI coding tools think.**
 > Every project gets its own arrangement. Zero dependencies, zero audio files.
 > Works with Claude Code, Codex, Cursor, Grok, Gemini CLI, Copilot CLI, Qwen Code, Windsurf, Antigravity, Aider — and any terminal command.
@@ -423,6 +425,30 @@ Installing the Claude Code hooks also adds a `/vibe` command (`~/.claude/command
 
 It asks Claude to run the matching `vibe` command, so Claude Code will ask permission for that command the first time. If you already have your own `vibe.md` there, VibeAudio leaves it alone and says so; `--uninstall-hooks` removes only its own.
 
+### `/vibeaudio`: instant controls and a pane (Claude Code mod)
+
+`/vibe` is a prompt, so Claude has to read it, run a command and answer: it costs a turn and a few tokens, and it waits for the current turn to end. The optional **VibeAudio mod** runs inside Claude Code instead, so `/vibeaudio mute` takes effect at once, even while Claude is working, and costs no tokens.
+
+```text
+claude plugin marketplace add kiril6/vibeaudio
+claude plugin install vibeaudio-mod@vibeaudio
+```
+
+Then `/reload-plugins` or a new session; `/plugin` shows `1 mod active`.
+
+```text
+/vibeaudio               open the pane: mute, music, genre, volume, speech, banners, test signal
+/vibeaudio mute 30       silence for 30 minutes (unmute ends it)
+/vibeaudio genre jazz    also: volume <n>, music on|off, speak off|auto|always, notify on|off, stop
+/vibeaudio card          make your week card; the pane shows it in terminals that draw images
+```
+
+While you are muted, a line above the prompt says how many minutes are left, so a forgotten mute does not look like a broken tool. Nothing is shown otherwise.
+
+- **It changes nothing itself.** Every action runs the `vibe` command with a fixed argument list (no shell), so settings stay in `~/.vibeaudio/config.json` and the pane cannot disagree with the CLI. It needs `vibe` on your `PATH` (`npm i -g vibeaudio`) and **Claude Code 2.1.287 or later** (Desktop app 2.1.286). It draws in the terminal and the Desktop app; in the VS Code panel and `claude -p` the same commands answer in text. It makes no network request.
+- **A mod is code, not configuration.** It runs inside Claude Code with your permissions and is not sandboxed, which is why `--install-hooks` never installs it for you. Read it first: it is [`mods/vibe/hooks/register.js`](mods/vibe/hooks/register.js), and `claude plugin validate mods/vibe` lists every call it makes (it reads two files in `~/.vibeaudio/`, runs `vibe`, and draws).
+- **`/vibe` stays.** It works on every Claude Code version and surface; the mod is the faster path where it loads. Remove the mod with `claude plugin uninstall vibeaudio-mod@vibeaudio`.
+
 ### Changing the sound later
 
 One command, and it reaches everything:
@@ -494,6 +520,8 @@ plus where the time went by project and, for windows up to two weeks, by day. "Y
 
 </details>
 
+**Share it:** `vibe --report --card` (or `--report 30 --card`) saves the same totals as a square image to `~/.vibeaudio/card.png` (`--out <path>` writes it elsewhere). It shows your time with agents, turns, typical and longest turn, a bar per day, the agents VibeAudio hooks into, and where to get it. It carries totals only — never a project name — and is written locally, never uploaded: attach it to a post yourself. The PNG needs macOS; elsewhere you get the SVG, which any browser opens. One file, replaced on each run.
+
 ### The chime is in the music's key
 
 The success chime is the tonic chord of whatever key your genre sits in — C major for lofi, 8bit, jazz and piano, D minor for synthwave and electronic, D major for zen, A minor for drone — so it lands as the resolution of the piece rather than a bell over it. `rain`, `ocean` and `random` have no single key to match and keep the original C major chime.
@@ -832,6 +860,7 @@ The full order, highest first: **a flag** → **an environment variable** → **
 | `--speak` / `--speak-always` / `--no-speak` | Say which project finished, failed or needs you, after the chime: only with two or more sessions going (`--speak`), or every time (`--speak-always`). Saved to `config.json` | off |
 | `--announcements <on\|off>` | Turn `vibe --announce` on or off for good. Saved to `config.json` | on |
 | `--report [days]` | How long you waited on agents, and on which projects, from the local turn log | `7` days |
+| `--card [--out <path>]` | With `--report`: the totals as a shareable image - PNG on macOS, SVG anywhere - saved to `~/.vibeaudio/card.png`, replaced each run | off |
 | `--statusline` | The same state as one plain line for tmux or a shell prompt (`working ×2`, `waiting: api`); prints nothing when idle | — |
 | `--state` | What every agent on the machine is doing, as one line of JSON: `idle`, `working`, `stuck` or `waiting` | — |
 | `--events` | Stream agent state changes as JSON lines, starting with the current state, until stopped | — |
@@ -1040,3 +1069,5 @@ Support development: <a href="https://ko-fi.com/K3K2X0ERJ"><img src="https://ko-
 
 ## 📄 License
 MIT © 2026
+
+VibeAudio is not affiliated with or endorsed by Claude Code, Codex, Cursor, Grok, Gemini CLI, GitHub Copilot CLI, Qwen Code, Windsurf, Antigravity or any other tool it works with. Their names are used only to say what it works with.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeaudio",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Procedural focus music while your AI coding tools (Claude Code, Codex, Cursor, Grok, Gemini, Copilot) think — a different arrangement per project.",
   "bin": {
     "vibeaudio": "bin/vibeaudio.js",
@@ -10,7 +10,7 @@
   "scripts": {
     "test": "node test/test-synth.js",
     "start": "node bin/vibeaudio.js",
-    "version": "node -e \"const fs=require('fs'),v=require('./package.json').version;for(const f of ['.claude-plugin/plugin.json','.codex-plugin/plugin.json']){const j=JSON.parse(fs.readFileSync(f,'utf8'));j.version=v;fs.writeFileSync(f,JSON.stringify(j,null,2)+'\\n')}\" && git add .claude-plugin/plugin.json .codex-plugin/plugin.json"
+    "version": "node -e \"const fs=require('fs'),v=require('./package.json').version;for(const f of ['.claude-plugin/plugin.json','.codex-plugin/plugin.json','mods/vibe/.claude-plugin/plugin.json']){const j=JSON.parse(fs.readFileSync(f,'utf8'));j.version=v;fs.writeFileSync(f,JSON.stringify(j,null,2)+'\\n')}\" && git add .claude-plugin/plugin.json .codex-plugin/plugin.json mods/vibe/.claude-plugin/plugin.json"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/src/card.js

@@ -0,0 +1,129 @@
+/**
+ * `vibe --report --card`: the report as a picture you can post. The SVG is
+ * built as a string (pure, no I/O, so a test can read it); macOS also gets a
+ * PNG through Quick Look, since every other platform would need a rasterizer
+ * and this package has no dependencies.
+ *
+ * It carries totals only, never a project name or path: a card is made to be
+ * shared, and a project is the user's to name. It is written locally and
+ * sent nowhere.
+ */
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const { formatDuration, summarize, dayTotals } = require("./history");
+const { TARGETS } = require("./hooks");
+
+const CARD_DIR = path.join(os.homedir(), ".vibeaudio");
+// Square, because Quick Look scales a thumbnail to fit its height and crops the rest.
+const SIZE = 1080;
+const MAX_BARS = 14;
+
+/** The card's SVG for a non-empty list of turns over the last `days` days. */
+function renderCard(turns, days, now = Date.now()) {
+  const s = summarize(turns);
+  const rows = dayTotals(turns, Math.min(days, MAX_BARS), now);
+  const peak = Math.max(...rows.map((r) => r.ms)) || 1;
+  const period = days === 1 ? "today" : `last ${days} days`;
+
+  const slot = 920 / rows.length;
+  const barW = Math.min(46, slot * 0.6);
+  const bars = rows.map((r, i) => {
+    const h = r.ms ? Math.max(10, Math.round((r.ms / peak) * 160)) : 4;
+    const x = Math.round(80 + i * slot + (slot - barW) / 2);
+    return `<rect x="${x}" y="${780 - h}" width="${barW}" height="${h}" rx="${Math.min(barW / 2, 12)}" fill="${r.ms ? "url(#bar)" : "#3c2a5e"}"/>`;
+  }).join("") + rows.map((r, i) =>
+    `<text x="${Math.round(80 + i * slot + slot / 2)}" y="806" class="d" text-anchor="middle">${r.date.toLocaleDateString("en-US", { weekday: "short" })}</text>`).join("");
+
+  // Pills, not the agents' logos: those are their owners' marks, and a pill
+  // from TARGETS cannot fall out of step with what we actually hook into.
+  let cx = 80;
+  let cy = 864;
+  const pills = Object.values(TARGETS).map(({ name }) => {
+    const w = Math.round(name.length * 12 + 34);
+    if (cx + w > 1000) { cx = 80; cy += 50; }
+    const out = `<rect x="${cx}" y="${cy}" width="${w}" height="38" rx="10" fill="#120b1f" stroke="#3c2a5e" stroke-width="2"/><text x="${cx + w / 2}" y="${cy + 26}" class="c" text-anchor="middle">${name}</text>`;
+    cx += w + 12;
+    return out;
+  }).join("");
+
+  const stat = (x, value, label) =>
+    `<text x="${x}" y="552" class="v">${value}</text><text x="${x}" y="586" class="l">${label}</text>`;
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${SIZE} ${SIZE}" width="${SIZE}" height="${SIZE}">
+<defs>
+<linearGradient id="hero" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#ff2e97"/><stop offset="1" stop-color="#ffb454"/></linearGradient>
+<linearGradient id="bar" x1="0" y1="1" x2="0" y2="0"><stop offset="0" stop-color="#a855f7"/><stop offset="0.55" stop-color="#ff2e97"/><stop offset="1" stop-color="#ffb454"/></linearGradient>
+<radialGradient id="gp" cx="0.08" cy="0.04" r="0.65"><stop offset="0" stop-color="#ff2e97" stop-opacity="0.24"/><stop offset="1" stop-color="#ff2e97" stop-opacity="0"/></radialGradient>
+<radialGradient id="gc" cx="0.98" cy="0.06" r="0.55"><stop offset="0" stop-color="#00e5ff" stop-opacity="0.16"/><stop offset="1" stop-color="#00e5ff" stop-opacity="0"/></radialGradient>
+<radialGradient id="gv" cx="0.5" cy="1.02" r="0.7"><stop offset="0" stop-color="#a855f7" stop-opacity="0.16"/><stop offset="1" stop-color="#a855f7" stop-opacity="0"/></radialGradient>
+<clipPath id="card"><rect width="${SIZE}" height="${SIZE}" rx="48"/></clipPath>
+<filter id="glow" x="-20%" y="-40%" width="140%" height="180%"><feGaussianBlur stdDeviation="7" result="b"/><feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge></filter>
+<style>text{font-family:ui-monospace,'SF Mono',Menlo,Monaco,monospace;fill:#f2ecff}.t{font-size:60px;font-weight:800}.h{font-size:84px;font-weight:800}.v{font-size:44px;font-weight:700}.l{font-size:21px;fill:#b3a3d6}.s{font-size:26px;fill:#b3a3d6}.m{font-size:30px;font-weight:800;letter-spacing:2px}.f{font-size:20px;fill:#9584be}.c{font-size:20px}.u{font-size:23px;font-weight:700;fill:#ff2e97}.n{font-size:14px;fill:#8272ad}.d{font-size:16px;fill:#9584be}.i{font-size:20px;font-weight:700;fill:#00e5ff}</style>
+</defs>
+<g clip-path="url(#card)"><rect width="${SIZE}" height="${SIZE}" fill="#07050d"/><rect width="${SIZE}" height="${SIZE}" fill="url(#gp)"/><rect width="${SIZE}" height="${SIZE}" fill="url(#gc)"/><rect width="${SIZE}" height="${SIZE}" fill="url(#gv)"/></g>
+<rect x="3" y="3" width="${SIZE - 6}" height="${SIZE - 6}" rx="46" fill="none" stroke="#3c2a5e" stroke-width="3"/>
+<g transform="translate(80 78) scale(0.17) translate(-60 -100)"><path d="M120 300V272a136 136 0 0 1 272 0V300" fill="none" stroke="url(#bar)" stroke-width="30" stroke-linecap="round"/><rect x="86" y="286" width="76" height="136" rx="32" fill="url(#bar)"/><rect x="350" y="286" width="76" height="136" rx="32" fill="url(#bar)"/><g fill="#00e5ff"><rect x="212" y="326" width="22" height="56" rx="11"/><rect x="245" y="296" width="22" height="116" rx="11"/><rect x="278" y="318" width="22" height="72" rx="11"/></g></g>
+<text x="164" y="126" class="m">VIBE<tspan fill="#ff2e97" style="fill:#ff2e97" filter="url(#glow)">AUDIO</tspan></text>
+<text x="1000" y="124" class="u" text-anchor="end">kiril6.github.io/vibeaudio</text>
+<text x="80" y="224" class="t" filter="url(#glow)">Focus music</text>
+<text x="80" y="298" class="t" filter="url(#glow)">while your <tspan style="fill:#00e5ff">AI</tspan> codes.</text>
+<text x="80" y="420" class="h" style="fill:url(#hero)">${formatDuration(s.waited)}</text>
+<text x="80" y="462" class="s">with my <tspan style="fill:#00e5ff" font-weight="800">AI</tspan> agents working · ${period}</text>
+${stat(80, String(s.count), s.count === 1 ? "turn" : "turns")}${stat(360, formatDuration(s.median), "typical turn")}${stat(680, formatDuration(s.longest.ms), "longest turn")}
+${bars}
+${rows.length < days ? `<text x="1000" y="842" class="f" text-anchor="end">bars: last ${rows.length} days</text>` : ""}
+<text x="80" y="842" class="f">works as a hook for</text>
+${pills}
+<rect x="80" y="972" width="578" height="52" rx="10" fill="#0a1a22" stroke="#00e5ff" stroke-opacity="0.45" stroke-width="2"/>
+<text x="100" y="1005" class="i">npm i -g vibeaudio &amp;&amp; vibe --install-hooks</text>
+<text x="1000" y="1000" class="n" text-anchor="end">Not affiliated with or endorsed</text>
+<text x="1000" y="1020" class="n" text-anchor="end">by the tools named.</text>
+</svg>
+`;
+}
+
+/** Write `file` by renaming a temp file into place, so an interrupted run leaves no torn card. */
+function writeAtomic(file, data) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, data);
+  fs.renameSync(tmp, file);
+}
+
+/**
+ * Writes the card as one fixed file, replaced on every run, so nothing
+ * accumulates. `out` is a user-chosen path (kept as given); without it the card
+ * lives in ~/.vibeaudio. Returns the SVG path and the PNG path (null off macOS
+ * or when Quick Look could not render).
+ */
+function writeCard(turns, days, { out = null, now = Date.now(), dir = CARD_DIR } = {}) {
+  const base = out ? path.resolve(out.replace(/\.(svg|png)$/i, "")) : path.join(dir, "card");
+  fs.mkdirSync(path.dirname(base), { recursive: true });
+  const svgPath = `${base}.svg`;
+  writeAtomic(svgPath, renderCard(turns, days, now));
+
+  let pngPath = null;
+  if (process.platform === "darwin") {
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "vibe-card-"));
+    try {
+      // SIGKILL as well as a timeout: a hung system helper ignores SIGTERM.
+      const r = spawnSync("qlmanage", ["-t", "-s", String(SIZE), "-o", scratch, svgPath], { stdio: "ignore", timeout: 15000, killSignal: "SIGKILL" });
+      const rendered = path.join(scratch, `${path.basename(svgPath)}.png`);
+      if (r.status === 0 && fs.existsSync(rendered)) {
+        // Copy, not rename: the scratch dir and `--out` may be on different volumes.
+        const png = `${base}.png`;
+        writeAtomic(png, fs.readFileSync(rendered));
+        pngPath = png;
+      }
+    } catch (e) {
+      pngPath = null;
+    } finally {
+      fs.rmSync(scratch, { recursive: true, force: true });
+    }
+  }
+  return { svgPath, pngPath };
+}
+
+module.exports = { CARD_DIR, renderCard, writeCard };

package/src/cli.js

@@ -86,6 +86,7 @@ Procedural focus music while your AI coding tools think.
       --speak-always           Like --speak, but every time, even with one session
       --announcements <on|off> Turn vibe --announce on or off for good (a saved setting; on by default)
       --report [days]          How long you waited on agents, and where (default: 7 days)
+      --card [--out <path>]    With --report: save the totals as an image (PNG on macOS, SVG anywhere) to ~/.vibeaudio/card.*, replaced each run
       --state                  Print what every agent is doing as JSON: idle, working, stuck or waiting
       --announce <text>        Play the signals for something that is not an agent (CI, a deploy, a script), then exit (spoken too when --speak is on)
       --outcome <o>            With --announce: success (default), failure or attention
@@ -190,7 +191,8 @@ const VALUE_FLAGS = new Set([
   "--announce",
   "--outcome",
   "--exit-code",
-  "--port"
+  "--port",
+  "--out"
 ]);
 
 function parseArgs(argv) {
@@ -238,6 +240,8 @@ function parseArgs(argv) {
   let speakFlag = null;
   let announcementsFlag = null;
   let reportDays = null;
+  let cardFlag = false;
+  let cardOut = null;
   let stopFlag = false;
   let muteFlag = null;
   let muteMinutes = null;
@@ -432,6 +436,18 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--card") {
+      cardFlag = true;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--out") {
+      cardOut = args[i + 1];
+      i += 2;
+      continue;
+    }
+
     if (arg === "--notify" || arg === "--no-notify") {
       notifyFlag = arg === "--notify";
       i += 1;
@@ -636,6 +652,8 @@ function parseArgs(argv) {
     speak: speakFlag,
     announcements: announcementsFlag,
     report: reportDays,
+    card: cardFlag,
+    cardOut,
     stop: stopFlag,
     mute: muteFlag,
     muteMinutes,
@@ -1125,15 +1143,6 @@ function doctorChecks() {
   return checks;
 }
 
-/** 95 -> "1m 35s", 4_000_000 -> "1h 06m". */
-function formatDuration(ms) {
-  const s = Math.round(ms / 1000);
-  if (s < 60) return `${s}s`;
-  const m = Math.floor(s / 60);
-  if (m < 60) return `${m}m ${String(s % 60).padStart(2, "0")}s`;
-  return `${Math.floor(m / 60)}h ${String(m % 60).padStart(2, "0")}m`;
-}
-
 /**
  * The summary of ~/.vibeaudio/history.jsonl. "You waited" is the agent's own
  * working time - a turn's length minus the stretches it spent blocked on a
@@ -1143,7 +1152,7 @@ function formatDuration(ms) {
  * over RETURN_WINDOW_MS read as breaks and left out.
  */
 function printReport(days, now = Date.now()) {
-  const { readTurns, returnTimes } = require("./history");
+  const { readTurns, returnTimes, formatDuration, working, summarize, dayTotals } = require("./history");
   const turns = readTurns(days, now);
   const dim = (s) => `\x1b[90m${s}\x1b[0m`;
   const bold = (s) => `\x1b[1m${s}\x1b[0m`;
@@ -1157,14 +1166,7 @@ function printReport(days, now = Date.now()) {
     return;
   }
 
-  const working = (t) => t.ms - (t.blockedMs || 0);
-  const sum = (xs) => xs.reduce((a, b) => a + b, 0);
-  const sorted = turns.map((t) => t.ms).sort((a, b) => a - b);
-  const median = sorted[Math.floor(sorted.length / 2)];
-  const longest = turns.reduce((a, b) => (b.ms > a.ms ? b : a));
-  const failed = turns.filter((t) => t.outcome === "failure").length;
-  const waitedOnAgents = sum(turns.map(working));
-  const blocked = sum(turns.map((t) => t.blockedMs || 0));
+  const { failed, waited: waitedOnAgents, blocked, median, longest } = summarize(turns);
 
   // Two projects called `api` under different parents stay apart.
   const names = new Map();
@@ -1211,15 +1213,9 @@ function printReport(days, now = Date.now()) {
 
   if (days <= 14) {
     console.log(`\n${bold("By day")}`);
-    const byDay = new Map();
-    for (const t of turns) {
-      const key = new Date(t.at).toLocaleDateString("en-CA");
-      byDay.set(key, (byDay.get(key) || 0) + working(t));
-    }
-    const maxDay = Math.max(...byDay.values()) || 1;
-    for (let d = days - 1; d >= 0; d--) {
-      const date = new Date(now - d * 86400000);
-      const ms = byDay.get(date.toLocaleDateString("en-CA")) || 0;
+    const rows = dayTotals(turns, days, now);
+    const maxDay = Math.max(...rows.map((r) => r.ms)) || 1;
+    for (const { date, ms } of rows) {
       const name = `${date.toLocaleDateString("en-US", { weekday: "short" })} ${date.getDate()}`;
       console.log(`  ${name.padEnd(8)}${(ms ? formatDuration(ms) : "—").padStart(8)}  ${"█".repeat(ms ? Math.max(1, Math.round((ms / maxDay) * 14)) : 0)}`);
     }
@@ -1227,6 +1223,31 @@ function printReport(days, now = Date.now()) {
   console.log();
 }
 
+/** `--report --card`: the report as an image, written locally and never uploaded. */
+function printCard(days, out) {
+  const { readTurns } = require("./history");
+  const turns = readTurns(days, Date.now());
+  if (!turns.length) {
+    console.log(`\n  No turns recorded in the last ${days === 1 ? "day" : `${days} days`}, so there is nothing to draw yet.`);
+    console.log(`\x1b[90m  Turns are logged when your agent's hooks fire (vibe --install-hooks).\x1b[0m\n`);
+    return;
+  }
+  const { writeCard } = require("./card");
+  let written;
+  try {
+    written = writeCard(turns, days, { out });
+  } catch (e) {
+    console.error(`\x1b[31m[vibeaudio] Could not write the card: ${e.message}\x1b[0m`);
+    process.exit(1);
+  }
+  const { formatDuration, summarize } = require("./history");
+  const shown = written.pngPath || written.svgPath;
+  console.log(`\n  Card saved: \x1b[1m${shown}\x1b[0m`);
+  if (!written.pngPath) console.log(`\x1b[90m  PNG needs macOS; the SVG opens in any browser.\x1b[0m`);
+  console.log(`\x1b[90m  Totals only - no project names. It stays on this machine; attach it to a post yourself.\x1b[0m`);
+  console.log(`\n  ${formatDuration(summarize(turns).waited)} with my AI agents working, with focus music from VibeAudio: https://kiril6.github.io/vibeaudio  (npm i -g vibeaudio && vibe --install-hooks)\n`);
+}
+
 function printDoctor() {
   const mark = { ok: "\x1b[32m✔\x1b[0m", warn: "\x1b[33m!\x1b[0m", fail: "\x1b[31m✘\x1b[0m" };
   const checks = doctorChecks();
@@ -1796,6 +1817,8 @@ async function run() {
     speak: speakChange,
     announcements: announcementsChange,
     report: reportDays,
+    card: cardFlag,
+    cardOut,
     stop: shouldStop,
     mute: muteChange,
     muteMinutes,
@@ -1841,6 +1864,7 @@ async function run() {
       : speakChange !== null ? (speakChange === "off" ? "--no-speak" : speakChange === "always" ? "--speak-always" : "--speak")
       : announcementsChange !== null ? "--announcements"
       : announceReq.text !== null ? "--announce"
+      : cardFlag ? "--card"
       : null;
     if (own && cmdArgs.length > 0) {
       console.error(`\x1b[31m[vibeaudio] ${own} does not wrap a command, so '${cmdArgs.join(" ")}' was not run.\x1b[0m ` +
@@ -1979,6 +2003,12 @@ async function run() {
     return;
   }
 
+  if (cardOut !== null && !cardFlag) {
+    console.error("\x1b[31m[vibeaudio] --out goes with --card.\x1b[0m");
+    process.exit(1);
+  }
+  if (cardFlag) return printCard(reportDays ?? 7, cardOut);
+
   if (reportDays !== null) {
     return printReport(reportDays);
   }

package/src/history.js

@@ -85,4 +85,49 @@ function returnTimes(turns) {
   return gaps;
 }
 
-module.exports = { HISTORY_FILE, RETURN_WINDOW_MS, recordTurn, readTurns, returnTimes };
+/** 95 -> "1m 35s", 4_000_000 -> "1h 06m". */
+function formatDuration(ms) {
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${String(s % 60).padStart(2, "0")}s`;
+  return `${Math.floor(m / 60)}h ${String(m % 60).padStart(2, "0")}m`;
+}
+
+/** A turn's working time: its length minus the stretches it spent blocked on you. */
+const working = (t) => t.ms - (t.blockedMs || 0);
+
+/**
+ * The headline numbers of a non-empty list of turns. `--report` and
+ * `--report --card` both read these, so the card can never disagree with the
+ * text it is a picture of.
+ */
+function summarize(turns) {
+  const sum = (xs) => xs.reduce((a, b) => a + b, 0);
+  const sorted = turns.map((t) => t.ms).sort((a, b) => a - b);
+  return {
+    count: turns.length,
+    failed: turns.filter((t) => t.outcome === "failure").length,
+    waited: sum(turns.map(working)),
+    blocked: sum(turns.map((t) => t.blockedMs || 0)),
+    median: sorted[Math.floor(sorted.length / 2)],
+    longest: turns.reduce((a, b) => (b.ms > a.ms ? b : a))
+  };
+}
+
+/** Working time per calendar day for the last `days` days, oldest first. */
+function dayTotals(turns, days, now = Date.now()) {
+  const byDay = new Map();
+  for (const t of turns) {
+    const key = new Date(t.at).toLocaleDateString("en-CA");
+    byDay.set(key, (byDay.get(key) || 0) + working(t));
+  }
+  const out = [];
+  for (let d = days - 1; d >= 0; d--) {
+    const date = new Date(now - d * 86400000);
+    out.push({ date, ms: byDay.get(date.toLocaleDateString("en-CA")) || 0 });
+  }
+  return out;
+}
+
+module.exports = { HISTORY_FILE, RETURN_WINDOW_MS, recordTurn, readTurns, returnTimes, formatDuration, working, summarize, dayTotals };