lumira 1.13.0 → 1.14.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Real-time statusline HUD for Claude Code and Qwen Code — analytics, quota projection, themes, powerline",
-    "version": "1.13.0"
+    "version": "1.14.0"
   },
   "plugins": [
     {
       "name": "lumira",
       "source": "./",
       "description": "Real-time statusline HUD for Claude Code and Qwen Code. Session analytics, API latency widget, 7-day quota projection, auto-compact warnings, 7 themes, powerline support. Zero runtime dependencies. Run /lumira:setup after install to activate.",
-      "version": "1.13.0",
+      "version": "1.14.0",
       "author": {
         "name": "Carlos Cativo"
       },
@@ -32,5 +32,5 @@
       ]
     }
   ],
-  "version": "1.13.0"
+  "version": "1.14.0"
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lumira",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Real-time statusline HUD for Claude Code and Qwen Code — session analytics, API latency, 7-day quota projection, auto-compact warnings, 7 themes, powerline. Zero runtime deps.",
   "author": {
     "name": "Carlos Cativo"

package/README.md

@@ -111,6 +111,7 @@ See [`docs/competitive-comparison.md`](docs/competitive-comparison.md) for the f
 - **Pace delta** — `usedPct − elapsedPct` of the 5h window. Turtle when behind pace (healthy), car with time-to-exhaustion when ahead. Color escalates green → yellow → orange → blinkRed. Toggle independently via `display.paceDelta`.
 - **7d quota projection** — when the current burn rate would exhaust the 7d quota before the window resets, the 7d segment grows a warning: `⚠ ~24h`, `⚠ ~2d`, `⚠ Tue`, or `🔥 ~8h` (critical icon under 12h). Default on. Toggle via `display.quotaProjection`; off in the `minimal` preset. Different from pace delta — pace looks backwards at the 5h window's actual vs proportional burn, projection looks forwards at the 7d window's exhaustion ETA.
 - **Active agents** — live count of running subagents (`⚡N agents`) plus types parsed from the transcript. Toggle via `display.agents`.
+- **Subagent panel rows** — custom rendering for each row in Claude Code's agent panel via [`lumira subagent`](#subagent-rows): a state glyph (running / done / error), what each agent is doing, and its token count, in your configured theme and icon set. Opt-in at install.
 - **Cache hit rate** — prompt cache efficiency for the current turn (`87%⚡`). Alarm-mode: hidden while ≥90% (Anthropic's prompt cache pins this near 99% in healthy steady state, so an always-on number is wallpaper, not signal). Surfaces as yellow/orange/blinkRed only when the cache is actually degrading. Same hide-when-healthy pattern as rate-limits and agent count.
 - **GSD integration** — current task and update notifications (opt-in).
 - **Config health widget** — surfaces silent fallbacks (theme/powerline degrading in named-ANSI, missing GSD STATE.md). Opt-in.
@@ -259,6 +260,29 @@ lumira stats
 
 **Qwen Code sessions** are parsed the same way, but cost and burn-rate lines are suppressed when the transcript lacks usage blocks (`hasCostData: false` in the JSON output) — no misleading `$0.00`.
 
+## Subagent rows
+
+Claude Code (≥ 2.1.x) exposes a [`subagentStatusLine`](https://code.claude.com/docs/en/statusline#subagent-status-lines) hook that lets a command customize how each subagent renders in the agent panel — replacing the default `name · description · token count` row. `lumira subagent` reads the visible tasks from stdin and renders each row in your configured theme and icon set:
+
+```
+󱎫 reviewing auth module · 15k tok · running
+✓ exploring the codebase · 3k tok · done
+```
+
+The **glyph and colour are driven by state** — running (cyan clock), done (green check), error (red warning) — so a glance tells you what's live, what finished, what failed.
+
+The **row label** identifies each agent. In practice Claude Code reports every Task subagent with the generic `type: "local_agent"` and no `name`, so the per-agent `description` is the only field that distinguishes one row from another — lumira uses it. The full fallback is `name → a meaningful type → description → id`: an explicit `name` or a real agent type wins when Claude Code provides one, otherwise the `description` carries the row. Rows respect your `icons` (`nerd`/`emoji`/`none`) and `colors.mode` config, and are truncated to the width Claude Code budgets.
+
+**Enable it:** the installer offers to register `subagentStatusLine` alongside the main statusline (opt-in — it never writes the second key without asking). To wire it manually, add to `~/.claude/settings.json`:
+
+```json
+{
+  "subagentStatusLine": { "type": "command", "command": "lumira subagent", "padding": 0 }
+}
+```
+
+It's robust by design: on any unreadable or malformed payload it emits nothing and exits 0, so Claude Code falls back to its default rows — a bad render never breaks the panel. Set `LUMIRA_DEBUG=1` to log the raw payload Claude Code sends to stderr.
+
 ## Powerline
 
 `style: "powerline"` (or `--powerline`) renders the statusline with colored segment backgrounds and glyph separators inspired by powerline-go / oh-my-posh. Available separator presets via `powerline.style` (or `--powerline-style=<name>`):

package/dist/commands/subagent.js

@@ -0,0 +1,129 @@
+/**
+ * `lumira subagent` subcommand (issue #176 — `subagentStatusLine` renderer).
+ *
+ * Claude Code (≥ 2.1.x) lets a command customize how each subagent row renders
+ * in the agent panel. CC pipes a JSON object on stdin describing every visible
+ * subagent and expects ONE JSON line back per row (`{ id, content }`). Omitting
+ * an id keeps CC's default rendering for that row; empty content hides it.
+ *
+ * Input schema (distinct from the main statusline's `RawInput`):
+ *   { columns: number, tasks: [ { id, name, type, status, description,
+ *                                 label, startTime, tokenCount, ... } ] }
+ *
+ * Icon choice is by STATE, not agent type. CC's `type` field is open-ended and
+ * user-defined (dozens of agent types in a real setup), so there's no stable
+ * type→glyph map to maintain — but `running/completed/error` map cleanly onto
+ * glyphs lumira already ships across all three icon sets. The state also drives
+ * the colour, so a glance tells you what's live vs done vs failed.
+ *
+ * Robustness contract: this runs inside CC's render loop. On ANY bad input
+ * (unreadable stdin, malformed JSON, missing fields) it emits nothing and exits
+ * 0 — CC then falls back to its default rows. It must never crash the panel.
+ */
+import { formatTokens } from '../utils/format.js';
+import { displayWidth, truncField } from '../render/text.js';
+import { resolveIcons } from '../render/icons.js';
+import { createColors, detectColorMode } from '../render/colors.js';
+import { loadConfig } from '../config.js';
+import { readStdin } from '../stdin.js';
+import { debug } from '../utils/debug.js';
+/** Per-state presentation: glyph + colour + human label. */
+function styleFor(status, icons, colors) {
+    switch (status) {
+        case 'running':
+            return { icon: icons.clock, color: colors.cyan, label: 'running' };
+        case 'completed':
+            return { icon: icons.checkmark, color: colors.green, label: 'done' };
+        case 'error':
+        case 'failed':
+            return { icon: icons.warning, color: colors.red, label: 'error' };
+        default:
+            // Unknown/absent state: no glyph, dim, pass the raw status through as the
+            // label so a future CC state is still legible instead of being dropped.
+            return { icon: '', color: colors.dim, label: status ?? '' };
+    }
+}
+/**
+ * Render the `content` string for a single subagent row:
+ *   `<glyph> <name> · <tokens> · <state-label>`
+ *
+ * The glyph and label are state-coloured; tokens are dim. When `columns` is
+ * given, the name is truncated (with an ellipsis) so the visible row fits,
+ * reserving width for the fixed glyph/meta first.
+ */
+export function renderSubagentContent(task, icons, colors, columns) {
+    const { icon, color, label } = styleFor(task.status, icons, colors);
+    // Identity fallback. CC reports every Task subagent as the generic
+    // `type: "local_agent"` with no `name`, so `description` (the dispatch arg) is
+    // the only field that distinguishes rows — it must win over a generic type.
+    // A *meaningful* type (a real agent_type, if CC ever exposes one) still wins
+    // over description, and an explicit `name` wins over everything.
+    const meaningfulType = task.type && task.type !== 'local_agent' ? task.type : '';
+    const name = (task.name || meaningfulType || task.description || task.id || 'agent').trim();
+    const tokens = Number.isFinite(task.tokenCount) ? `${formatTokens(task.tokenCount)} tok` : '';
+    const prefix = icon ? `${color(icon)} ` : '';
+    const prefixW = icon ? displayWidth(icon) + 1 : 0;
+    // Plain (uncoloured) meta used both for measuring and for assembling the
+    // coloured version, so width math and output never drift apart.
+    const metaPlain = [tokens, label].filter(Boolean);
+    const metaW = metaPlain.length ? displayWidth(` · ${metaPlain.join(' · ')}`) : 0;
+    // Fit the name to whatever width is left after the fixed glyph + meta.
+    let shownName = name;
+    if (columns !== undefined && columns > 0) {
+        const budget = columns - prefixW - metaW;
+        if (budget < displayWidth(name))
+            shownName = budget > 1 ? truncField(name, budget) : '';
+    }
+    const metaColored = [];
+    if (tokens)
+        metaColored.push(colors.dim(tokens));
+    if (label)
+        metaColored.push(color(label));
+    const meta = metaColored.join(' · ');
+    // Avoid a dangling " · " when the name was truncated away entirely.
+    if (!shownName)
+        return `${prefix}${meta}`.trimEnd();
+    return meta ? `${prefix}${shownName} · ${meta}` : `${prefix}${shownName}`;
+}
+/**
+ * Render the full CC response: one `{ id, content }` JSON line per addressable
+ * task. Tasks without an id are skipped (CC keys rows by id, so a row we can't
+ * address can't be overridden). Empty/missing task list → empty string.
+ */
+export function renderSubagentTasks(input, icons, colors) {
+    const tasks = Array.isArray(input?.tasks) ? input.tasks : [];
+    const columns = Number.isFinite(input?.columns) ? input.columns : undefined;
+    const lines = [];
+    for (const task of tasks) {
+        if (!task || typeof task.id !== 'string' || task.id === '')
+            continue;
+        lines.push(JSON.stringify({ id: task.id, content: renderSubagentContent(task, icons, colors, columns) }));
+    }
+    return lines.join('\n');
+}
+/**
+ * Wire stdin → config → render. Reuses the main `readStdin` (its only schema
+ * assertion is "is a plain object", which our payload satisfies). Any failure
+ * degrades to empty stdout + exit 0 so CC's panel is never broken.
+ */
+export async function runSubagentCommand(opts = {}) {
+    const log = debug('subagent');
+    let raw;
+    try {
+        raw = await readStdin(opts.stream ?? process.stdin);
+    }
+    catch (e) {
+        log('stdin read failed:', e.message);
+        return { stdout: '', stderr: '', exitCode: 0 };
+    }
+    if (log.enabled)
+        log('payload:', raw);
+    const config = opts.config ?? loadConfig();
+    const icons = resolveIcons(config.icons);
+    const mode = opts.colorMode
+        ?? (config.colors?.mode && config.colors.mode !== 'auto' ? config.colors.mode : detectColorMode());
+    const colors = createColors(mode);
+    const out = renderSubagentTasks(raw, icons, colors);
+    return { stdout: out ? `${out}\n` : '', stderr: '', exitCode: 0 };
+}
+//# sourceMappingURL=subagent.js.map

package/dist/index.js

@@ -20,6 +20,7 @@ import { runThemesCommand } from './commands/themes.js';
 import { runStatsCommand } from './commands/stats.js';
 import { runCustomRefreshFromStdin } from './commands/custom-refresh.js';
 import { runCustomCommand } from './commands/custom.js';
+import { runSubagentCommand } from './commands/subagent.js';
 import { EMPTY_TRANSCRIPT } from './types.js';
 import { normalize } from './normalize.js';
 const defaultDeps = {
@@ -121,6 +122,7 @@ Commands:
   stats [path]  Show session statistics
   themes        Browse and preview themes
   custom        Manage custom commands
+  subagent      Render Claude Code agent-panel rows (reads tasks JSON from stdin)
 
 Options:
   --help, -h    Show this help
@@ -181,6 +183,19 @@ if (isDirectRun()) {
             process.exit(1);
         });
     }
+    else if (cmd === 'subagent') {
+        // CC's subagentStatusLine hook: reads the tasks JSON from its own stdin and
+        // emits one JSON line per row. Degrades to empty output on any error so a
+        // bad payload never breaks CC's agent panel.
+        runSubagentCommand().then(r => {
+            if (r.stdout)
+                process.stdout.write(r.stdout);
+            if (r.stderr)
+                process.stderr.write(r.stderr);
+            if (r.exitCode !== 0)
+                process.exit(r.exitCode);
+        }).catch(() => process.exit(0));
+    }
     else if (cmd === '__custom-refresh') {
         // Internal: invoked by the renderer as a detached child to refresh a
         // single custom command's cache entry without keeping the renderer's

package/dist/installer.js

@@ -25,6 +25,25 @@ const header = () => `\n${CYAN} lumira installer${RST}\n`;
 function makeStatusLine(command) {
     return { type: 'command', command, padding: 0 };
 }
+/** Atomically write settings.json: temp file + fsync + rename, mode 0600. */
+function writeSettingsAtomic(settings, settingsPath) {
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    const tmp = `${settingsPath}.${process.pid}.${Date.now()}.lumira.tmp`;
+    try {
+        const fd = openSync(tmp, 'wx', 0o600);
+        writeSync(fd, JSON.stringify(settings, null, 2) + '\n');
+        fsyncSync(fd);
+        closeSync(fd);
+        renameSync(tmp, settingsPath);
+    }
+    catch (e) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { }
+        throw e;
+    }
+}
 // Rank a statusLine command by per-render speed (higher = faster).
 //   3 = bare `lumira` binary — always resolves to the current installed version
 //   2 = node /path/dist/index.js or plugin-cache path — fast but version-pinned
@@ -153,6 +172,31 @@ function emitFooter(lines, homeOverride) {
     lines.push(`\n  Restart Claude Code to see your statusline.\n`);
 }
 // ── Install ─────────────────────────────────────────────────────────
+/**
+ * Optionally register Claude Code's `subagentStatusLine` hook (CC ≥ 2.1.x)
+ * alongside the main statusLine, pointing it at `<cmd> subagent`.
+ *
+ * Opt-in and interactive-only: we never add a second settings key without
+ * explicit consent, and skip silently in non-TTY runs (so CI/scripted installs
+ * stay predictable). No-op when it already points at lumira. Returns true when
+ * the key was added, so the caller knows it must flush settings to disk.
+ */
+async function maybeRegisterSubagent(args) {
+    const { settings, baseCmd, confirm, isTTY, lines } = args;
+    // Only register when the key is absent. If it's already lumira there's nothing
+    // to do; if it's a *foreign* command we leave it untouched rather than clobber
+    // a user's own subagent renderer without an explicit backup/replace flow.
+    if (settings.subagentStatusLine != null)
+        return false;
+    if (!isTTY)
+        return false;
+    const accepted = await confirm('Customize subagent panel rows too? (subagentStatusLine)');
+    if (!accepted)
+        return false;
+    settings.subagentStatusLine = makeStatusLine(`${baseCmd} subagent`);
+    lines.push(ok(`Configured subagentStatusLine → ${DIM}${baseCmd} subagent${RST}`));
+    return true;
+}
 export async function install(opts = {}) {
     const settingsPath = opts.settingsPath ?? defaultSettingsPath();
     const configPath = opts.configPath ?? defaultConfigPath();
@@ -243,6 +287,11 @@ export async function install(opts = {}) {
     // here — it may point to a stale version and should be migrated to `lumira`.
     if (existingIsLumira && commandSpeed(existingCmd) >= 3) {
         lines.push(ok('lumira is already configured (optimal command)'));
+        // statusLine needs no rewrite, but a returning user may still want to opt
+        // into the subagent hook — offer it and flush only if they accept.
+        const added = await maybeRegisterSubagent({ settings, baseCmd: existingCmd, confirm, isTTY: !!stdin?.isTTY, lines });
+        if (added)
+            writeSettingsAtomic(settings, settingsPath);
         return finalize();
     }
     // Resolve the fastest per-render command this environment can offer.
@@ -254,6 +303,9 @@ export async function install(opts = {}) {
         // so we never downgrade a user's direct binary to npx.
         if (commandSpeed(resolvedCmd) <= commandSpeed(existingCmd)) {
             lines.push(ok('lumira is already configured'));
+            const added = await maybeRegisterSubagent({ settings, baseCmd: existingCmd, confirm, isTTY: !!stdin?.isTTY, lines });
+            if (added)
+                writeSettingsAtomic(settings, settingsPath);
             return finalize();
         }
     }
@@ -263,22 +315,8 @@ export async function install(opts = {}) {
         lines.push(ok(`Backed up existing settings → ${DIM}settings.json.lumira.bak${RST}`));
     }
     settings.statusLine = makeStatusLine(resolvedCmd);
-    mkdirSync(dirname(settingsPath), { recursive: true });
-    const tmp = `${settingsPath}.${process.pid}.${Date.now()}.lumira.tmp`;
-    try {
-        const fd = openSync(tmp, 'wx', 0o600);
-        writeSync(fd, JSON.stringify(settings, null, 2) + '\n');
-        fsyncSync(fd);
-        closeSync(fd);
-        renameSync(tmp, settingsPath);
-    }
-    catch (e) {
-        try {
-            unlinkSync(tmp);
-        }
-        catch { }
-        throw e;
-    }
+    await maybeRegisterSubagent({ settings, baseCmd: resolvedCmd, confirm, isTTY: !!stdin?.isTTY, lines });
+    writeSettingsAtomic(settings, settingsPath);
     lines.push(ok(existingIsLumira
         ? `Upgraded statusline command → ${DIM}${resolvedCmd}${RST} (faster)`
         : 'Configured lumira as statusline'));
@@ -339,21 +377,10 @@ export function uninstall(opts = {}) {
         return lines.join('\n') + '\n';
     }
     delete uninstSettings.statusLine;
-    const uninstTmp = `${settingsPath}.${process.pid}.${Date.now()}.lumira.tmp`;
-    try {
-        const fd = openSync(uninstTmp, 'wx', 0o600);
-        writeSync(fd, JSON.stringify(uninstSettings, null, 2) + '\n');
-        fsyncSync(fd);
-        closeSync(fd);
-        renameSync(uninstTmp, settingsPath);
-    }
-    catch (e) {
-        try {
-            unlinkSync(uninstTmp);
-        }
-        catch { }
-        throw e;
-    }
+    // Only remove the subagent hook if it's ours — never wipe a foreign renderer.
+    if (isLumira(uninstSettings.subagentStatusLine))
+        delete uninstSettings.subagentStatusLine;
+    writeSettingsAtomic(uninstSettings, settingsPath);
     lines.push(ok('Removed lumira statusline from settings'));
     // Remove skill from both destinations (best effort)
     for (const root of [join(home, '.claude'), join(home, '.qwen')]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumira",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Real-time statusline HUD for Claude Code and Qwen Code. Includes session analytics CLI, API latency overhead widget, 7d quota projection, auto-compact proximity warnings, themes, and powerline. Zero deps.",
   "type": "module",
   "main": "dist/index.js",