contextspin 0.1.2 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contextspin",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Replace Claude Code spinner/statusline text with live org context (meetings, Slack, CI, incidents, PRs) aggregated from your existing MCP servers, CLIs, and HTTP endpoints.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -2,7 +2,6 @@
 // src/cli.js — Commander-based command-line interface for ContextSpin.
 
 import fs from 'node:fs';
-import fsp from 'node:fs/promises';
 import path from 'node:path';
 import process from 'node:process';
 import readline from 'node:readline/promises';
@@ -12,10 +11,13 @@ import { Command } from 'commander';
 
 import {
   CONFIG_PATH,
+  STATUSLINE_SH,
+  CLAUDE_SETTINGS_PATH,
   configExists,
   loadConfig,
   saveConfig,
   normalizeConfig,
+  defaultConfig,
 } from './config.js';
 import {
   startDaemonDetached,
@@ -25,6 +27,7 @@ import {
 } from './daemon.js';
 import { installStatusline, uninstallStatusline } from './inject/statusline.js';
 import { installPatcher, restorePatcher } from './inject/patcher.js';
+import { detectSources } from './detect.js';
 
 /** Absolute path to this module's directory. */
 const HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -91,27 +94,8 @@ function printSetupHint() {
 }
 
 /**
- * Write the bundled example config to the destination path. Confirms before
- * overwriting an existing file unless `force` is true.
- * @param {string} dest
- * @param {boolean} force
- * @returns {Promise<boolean>} true if written, false if skipped.
- */
-async function writeExampleConfig(dest, force) {
-  const examplePath = path.join(ROOT, '.contextspin.example.json');
-  const raw = await fsp.readFile(examplePath, 'utf8');
-  if (fs.existsSync(dest) && !force) {
-    console.log(`Config already exists at ${dest} (left unchanged).`);
-    return false;
-  }
-  await fsp.writeFile(dest, raw);
-  console.log(`Wrote example config to ${dest}`);
-  return true;
-}
-
-/**
- * Run the setup command: create a config either non-interactively (example
- * config) or via an interactive prompt that builds a minimal config.
+ * Run the setup command: create a config either non-interactively (a REAL
+ * config built from detected sources) or via an interactive prompt.
  * @param {{ yes?: boolean }} opts
  * @returns {Promise<void>}
  */
@@ -119,11 +103,13 @@ async function runSetup(opts = {}) {
   const interactive = process.stdin.isTTY && !opts.yes;
 
   if (!interactive) {
-    // Non-TTY or --yes: drop the example config unless one already exists.
+    // Non-TTY or --yes: write a real detected config unless one already exists.
     if (configExists()) {
       console.log(`Config already exists at ${CONFIG_PATH} (left unchanged).`);
     } else {
-      await writeExampleConfig(CONFIG_PATH, false);
+      const cfg = normalizeConfig(defaultConfig(await detectSources()));
+      await saveConfig(cfg, CONFIG_PATH);
+      console.log(`Wrote a detected config to ${CONFIG_PATH}`);
     }
     console.log('');
     console.log('Next steps:');
@@ -169,35 +155,21 @@ async function runSetup(opts = {}) {
       : 30;
 
     /** @type {Array<object>} */
-    const sources = [];
+    let sources = [];
     const seedAns = (
-      await rl.question('Seed a couple of safe starter sources? (Y/n) ')
+      await rl.question(
+        'Seed the safe starter sources detected for your environment? (Y/n) ',
+      )
     )
       .trim()
       .toLowerCase();
     if (seedAns !== 'n' && seedAns !== 'no') {
-      // Safe starters: read-only `gh` queries that do nothing harmful.
-      sources.push({
-        type: 'cli',
-        command: 'gh pr list --review-requested @me --json title,number --limit 3',
-        format: 'PR #{{ number }} needs your review: {{ title }}',
-        label: 'GitHub',
-        cooldown: 120,
-        maxSnippets: 3,
-      });
-      sources.push({
-        type: 'cli',
-        command: 'gh run list --json status,name,headBranch --limit 5',
-        filter: '{{ status }} == failure',
-        format: 'CI failing: {{ name }} on {{ headBranch }}',
-        label: 'CI',
-        cooldown: 60,
-        maxSnippets: 2,
-      });
+      // Read-only starters detected from the local environment (gh/glab).
+      sources = await detectSources();
     }
 
     const config = normalizeConfig({
-      sources,
+      ...defaultConfig(sources),
       injection: { mode, refresh },
     });
     await saveConfig(config, CONFIG_PATH);
@@ -211,6 +183,77 @@ async function runSetup(opts = {}) {
   }
 }
 
+/**
+ * Whether the Claude Code statusLine is already pointing at our wrapper.
+ * Best-effort: any read/parse/missing-file error -> false.
+ * @returns {boolean}
+ */
+function statuslineIsOurs() {
+  try {
+    if (!fs.existsSync(CLAUDE_SETTINGS_PATH)) return false;
+    const parsed = JSON.parse(fs.readFileSync(CLAUDE_SETTINGS_PATH, 'utf8'));
+    const sl = parsed && parsed.statusLine;
+    return !!(sl && typeof sl === 'object' && sl.command === STATUSLINE_SH);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The ENSURE flow: idempotent, non-interactive, safe to run every session
+ * (this is what the plugin SessionStart hook invokes). It:
+ *   (a) creates a detected config if none exists,
+ *   (b) wires the statusline if the mode is statusline/both and it is not
+ *       already pointing at our wrapper, and
+ *   (c) starts the daemon if it is not already running.
+ * Prints a concise one-line summary. Never throws on the normal paths; any
+ * error prints a clean line and the process still exits 0 (the hook depends on
+ * this — a non-zero exit would surface an error to the user every session).
+ * @returns {Promise<void>}
+ */
+async function runEnsure() {
+  /** @type {string[]} */
+  const did = [];
+  try {
+    let createdConfig = false;
+    if (!configExists()) {
+      const cfg = normalizeConfig(defaultConfig(await detectSources()));
+      await saveConfig(cfg, CONFIG_PATH);
+      createdConfig = true;
+      did.push('created config');
+    }
+
+    const config = await loadConfig();
+    const mode =
+      config && config.injection && config.injection.mode
+        ? config.injection.mode
+        : 'statusline';
+
+    if ((mode === 'statusline' || mode === 'both') && !statuslineIsOurs()) {
+      await installStatusline(config);
+      did.push('wired statusline');
+    }
+
+    if (!isDaemonRunning().running) {
+      startDaemonDetached();
+      did.push('started daemon');
+    }
+
+    if (did.length === 0) {
+      console.log('ContextSpin: already set up.');
+    } else {
+      console.log(
+        `ContextSpin: ${did.join(', ')}.` +
+          (createdConfig ? ` Edit ${CONFIG_PATH} to add your own sources.` : ''),
+      );
+    }
+  } catch (err) {
+    const message = err && err.message ? err.message : String(err);
+    // Never break the session-start hook: report and exit 0.
+    console.log(`ContextSpin: setup skipped (${message}).`);
+  }
+}
+
 /**
  * Start the background daemon. Requires a valid config.
  * @returns {Promise<void>}
@@ -431,10 +474,17 @@ function buildProgram() {
 
   program
     .command('setup')
-    .description('Create a ContextSpin config (interactive, or --yes for example)')
-    .option('--yes', 'skip prompts and write the example config')
+    .description('Create a ContextSpin config (interactive, or --yes for a detected config)')
+    .option('--yes', 'skip prompts and write a detected config')
     .action(action(async (opts) => runSetup(opts)));
 
+  program
+    .command('ensure')
+    .description(
+      'One-shot, idempotent setup (create config + wire statusline + start daemon)',
+    )
+    .action(async () => runEnsure());
+
   program
     .command('start')
     .description('Start the background daemon')

package/src/config.js

@@ -37,6 +37,13 @@ export const STATUSLINE_SH = path.join(STATE_DIR, "statusline.sh");
 /** Path to the generated statusline Node render script. */
 export const STATUSLINE_JS = path.join(STATE_DIR, "statusline-render.js");
 
+/**
+ * Path to the recorded prior statusLine command (captured when we wrap an
+ * existing statusline so we can run it and prepend its output). Holds
+ * { command, type }. Removed on uninstall.
+ */
+export const PREV_STATUSLINE_PATH = path.join(STATE_DIR, "prev-statusline.json");
+
 /** Path to Claude Code's settings file (patched by the statusline injector). */
 export const CLAUDE_SETTINGS_PATH = path.join(HOME, ".claude", "settings.json");
 
@@ -124,6 +131,35 @@ export function normalizeConfig(raw) {
   return { ...input, injection, snippets, sources };
 }
 
+/**
+ * Build a complete default config object from a set of sources. Mirrors the
+ * shipped example config's injection/snippets shape (statusline mode, 30s
+ * refresh, 5 visible, dedup on, a sensible priority order). The result is a
+ * plain config (NOT normalized) — pass it through normalizeConfig before use.
+ *
+ * @param {Array<object>} sources - Source objects (e.g. from detectSources).
+ * @returns {object} A default config: { sources, injection, snippets }.
+ */
+export function defaultConfig(sources) {
+  return {
+    sources: Array.isArray(sources) ? sources : [],
+    injection: { mode: "statusline", refresh: 30, maxVisible: 5 },
+    snippets: {
+      deduplication: true,
+      cooldownAfterShown: 3,
+      priorityOrder: [
+        "incident",
+        "ci",
+        "slack",
+        "calendar",
+        "github",
+        "gitlab",
+        "jira",
+      ],
+    },
+  };
+}
+
 /**
  * Validate a config (raw or normalized). Throws an Error with a clear message on
  * any problem; returns the same config object on success.
@@ -135,8 +171,12 @@ export function validateConfig(config) {
   if (!config || typeof config !== "object" || Array.isArray(config)) {
     throw new Error("Invalid config: expected a JSON object.");
   }
-  if (!Array.isArray(config.sources) || config.sources.length === 0) {
-    throw new Error('Invalid config: "sources" must be a non-empty array.');
+  // sources must be an array, but MAY be empty: a source-less config is valid —
+  // the daemon polls nothing and the injectors degrade to no snippets, which is
+  // the correct "installed but not configured yet" state (and lets `ensure`
+  // wire the statusline + start the daemon without a hard failure).
+  if (!Array.isArray(config.sources)) {
+    throw new Error('Invalid config: "sources" must be an array.');
   }
 
   config.sources.forEach((src, i) => {

package/src/daemon.js

@@ -41,7 +41,10 @@ export async function readCache() {
  * @returns {Promise<void>}
  */
 export async function writeCache(state) {
-  const tmp = CACHE_PATH + ".tmp";
+  // Per-process temp name so the daemon and the statusline render script (which
+  // also writes the cache to bump shownCount) never share one .tmp and tear each
+  // other's writes. rename-onto-target stays atomic.
+  const tmp = CACHE_PATH + "." + process.pid + ".tmp";
   await fsp.writeFile(tmp, JSON.stringify(state, null, 2));
   await fsp.rename(tmp, CACHE_PATH);
 }

package/src/detect.js

@@ -0,0 +1,144 @@
+// src/detect.js — best-effort, zero-network detection of safe starter sources.
+//
+// Detection heuristics (all local, no secrets, no network):
+//   - We probe PATH for the `gh` (GitHub CLI), `glab` (GitLab CLI), and
+//     `kubectl` binaries using a short, swallowed child-process check
+//     (`<tool> --version`). Anything that errors, times out, or exits non-zero
+//     is treated as "not present".
+//   - If `gh` is present we seed two GitHub sources: PRs that requested your
+//     review, and failing CI runs.
+//   - Else if `glab` is present we seed the GitLab equivalents.
+//   - If NEITHER `gh` nor `glab` is present we still return the `gh` pair as a
+//     sensible placeholder. cli sources fail gracefully per-source in the
+//     daemon runner, so a missing binary just yields no snippets rather than
+//     breaking anything — and the config is then a working template the user
+//     can edit.
+//   - `kubectl` is probed for future use / informational purposes; we do not
+//     seed a kubectl source today because a safe, universally-meaningful
+//     read-only query is cluster-specific.
+//
+// All format/filter strings use the double-curly-brace token syntax understood
+// by src/formatter.js. Returned source objects have NO `id` — normalizeConfig
+// assigns ids by index.
+
+import { spawn } from "node:child_process";
+
+/**
+ * Best-effort check whether a binary is on PATH by running `<tool> --version`.
+ * Swallows every failure (missing binary, non-zero exit, timeout, spawn error)
+ * and resolves to a boolean. Never throws.
+ *
+ * @param {string} tool - The binary name to probe (e.g. "gh").
+ * @param {number} [timeoutMs=2000] - Kill the probe after this long.
+ * @returns {Promise<boolean>}
+ */
+function hasBinary(tool, timeoutMs = 2000) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    let child;
+    try {
+      child = spawn(tool, ["--version"], { stdio: "ignore" });
+    } catch {
+      done(false);
+      return;
+    }
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        // ignore
+      }
+      done(false);
+    }, timeoutMs);
+    if (timer.unref) timer.unref();
+    child.on("error", () => {
+      clearTimeout(timer);
+      done(false);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      done(code === 0);
+    });
+  });
+}
+
+/** The GitHub starter pair (PRs needing review + failing CI). */
+function ghSources() {
+  return [
+    {
+      type: "cli",
+      command:
+        "gh pr list --review-requested @me --json title,number --limit 3",
+      format: "PR #{{ number }} needs review: {{ title }}",
+      label: "GitHub",
+      cooldown: 120,
+      maxSnippets: 3,
+    },
+    {
+      type: "cli",
+      command: "gh run list --json status,name,headBranch --limit 5",
+      filter: "{{ status }} == failure",
+      format: "CI failing: {{ name }} on {{ headBranch }}",
+      label: "CI",
+      cooldown: 60,
+      maxSnippets: 2,
+    },
+  ];
+}
+
+/** The GitLab starter pair (MRs needing review + failing CI). */
+function glabSources() {
+  return [
+    {
+      type: "cli",
+      command: "glab mr list --reviewer=@me --output json --per-page 3",
+      format: "MR !{{ iid }} needs review: {{ title }}",
+      label: "GitLab",
+      cooldown: 120,
+      maxSnippets: 3,
+    },
+    {
+      type: "cli",
+      command: "glab ci list --status failed --output json --per-page 5",
+      format: "CI failed: {{ ref }} (#{{ id }})",
+      label: "CI",
+      cooldown: 60,
+      maxSnippets: 2,
+    },
+  ];
+}
+
+/**
+ * Detect a set of safe, read-only starter sources from the local environment.
+ *
+ * Best-effort and side-effect-free beyond local `<tool> --version` probes (no
+ * network). See the file header for the detection heuristics. Always returns a
+ * non-empty array of source objects WITHOUT ids (normalizeConfig assigns ids).
+ *
+ * @param {{ timeoutMs?: number }} [opts]
+ * @returns {Promise<Array<object>>}
+ */
+export async function detectSources(opts = {}) {
+  const timeoutMs = opts.timeoutMs;
+
+  // Probe the three tools in parallel; each probe swallows its own failures.
+  const [gh, glab /*, kubectl */] = await Promise.all([
+    hasBinary("gh", timeoutMs),
+    hasBinary("glab", timeoutMs),
+    hasBinary("kubectl", timeoutMs),
+  ]);
+
+  if (gh) return ghSources();
+  if (glab) return glabSources();
+
+  // Neither present: return the gh pair as a sensible, gracefully-failing
+  // placeholder the user can edit.
+  return ghSources();
+}
+
+export default detectSources;

package/src/inject/statusline.js

@@ -1,6 +1,12 @@
 // src/inject/statusline.js — installs/uninstalls the Claude Code statusLine integration.
-// Generates a self-contained render script (always exits 0, reads+discards stdin)
-// and wires it into ~/.claude/settings.json under the camelCase `statusLine` key.
+// Generates a self-contained render script (always exits 0, buffers stdin) and
+// wires it into ~/.claude/settings.json under the camelCase `statusLine` key.
+//
+// NON-DESTRUCTIVE: if the user already has a statusLine command, we record it to
+// PREV_STATUSLINE_PATH and the generated render script RUNS that prior command
+// (piping Claude Code's stdin to it) and prints its output FIRST, then prints the
+// ContextSpin snippet on its own line beneath. The user's statusline is composed
+// with ours, never discarded.
 
 import fs from "node:fs";
 import fsp from "node:fs/promises";
@@ -9,6 +15,7 @@ import {
   STATE_DIR,
   STATUSLINE_SH,
   STATUSLINE_JS,
+  PREV_STATUSLINE_PATH,
   CACHE_PATH,
   CONFIG_PATH,
   CLAUDE_SETTINGS_PATH,
@@ -19,71 +26,161 @@ import {
  * for each status-bar refresh.
  *
  * Runtime behavior of the generated script:
- *  - Reads and DISCARDS all of stdin (Claude Code pipes a JSON payload; we never
- *    use it, but we must drain it so the writer never gets EPIPE).
- *  - Reads the cache (tolerating a missing file -> exit 0 silently).
+ *  - Reads and BUFFERS all of stdin (Claude Code pipes a JSON payload). We must
+ *    consume it so the writer never gets EPIPE; we also feed it to a wrapped
+ *    prior statusline command (below).
+ *  - If PREV_STATUSLINE_PATH exists and names a command, spawns that command via
+ *    the shell, writes the buffered stdin to ITS stdin, captures its stdout with
+ *    a short timeout (killed on timeout), and prints that output VERBATIM first
+ *    (it may be multiple lines). Any failure here is swallowed.
+ *  - Reads the cache (tolerating a missing file).
  *  - Reads `cooldownAfterShown` from the config (fallback 3).
  *  - Selects snippets where shownCount < cooldownAfterShown, picks the one with
  *    the LOWEST shownCount then the most recent fetchedAt, bumps its shownCount,
  *    and writes the cache back atomically.
- *  - Prints that snippet's text on a single line; prints nothing if none eligible.
- *  - Wraps EVERYTHING so any error still exits 0 with no output (never breaks the
- *    user's status bar).
+ *  - Prints that snippet's text on its OWN line beneath the prior output; prints
+ *    nothing for the ContextSpin line if none eligible.
+ *  - Wraps EVERYTHING so any error still exits 0 with whatever output succeeded
+ *    (the prior statusline must never be lost and the bar must never break).
  *
- * The cache and config paths are baked into the script as string literals so the
- * generated file is fully self-contained and has no import dependencies.
+ * The cache, config, and prev-statusline paths are baked into the script as
+ * string literals so the generated file is fully self-contained with no imports
+ * beyond node builtins.
  *
  * @param {string} cachePath - Absolute path to the snippet cache JSON file.
  * @param {string} configPath - Absolute path to the ContextSpin config JSON file.
+ * @param {string} prevPath - Absolute path to the prev-statusline JSON file.
  * @returns {string} The ESM source of the render script.
  */
-function buildRenderScript(cachePath, configPath) {
+function buildRenderScript(cachePath, configPath, prevPath) {
   const CACHE = JSON.stringify(cachePath);
   const CONFIG = JSON.stringify(configPath);
-  return `// contextspin statusline-render.js (generated) — prints one context snippet.
-// MUST always exit 0 and print nothing on error so the status bar never breaks.
+  const PREV = JSON.stringify(prevPath);
+  return `// contextspin statusline-render.js (generated) — composes any prior
+// statusline with one ContextSpin snippet line. MUST always exit 0 and never
+// lose the prior statusline's output, so the user's status bar never breaks.
 import fs from "node:fs";
+import { spawn } from "node:child_process";
 
 const CACHE_PATH = ${CACHE};
 const CONFIG_PATH = ${CONFIG};
+const PREV_STATUSLINE_PATH = ${PREV};
 
-/** Drain and discard stdin so Claude Code's JSON pipe never gets EPIPE. */
-function drainStdin() {
+/** Buffer ALL of stdin into a Buffer. Resolves on end/close/error/timeout. */
+function readStdin() {
   return new Promise((resolve) => {
+    const chunks = [];
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      resolve(Buffer.concat(chunks));
+    };
     try {
       const stdin = process.stdin;
-      stdin.on("error", () => {});
-      stdin.on("data", () => {});
-      stdin.on("end", () => resolve());
-      stdin.on("close", () => resolve());
+      stdin.on("error", () => finish());
+      stdin.on("data", (chunk) =>
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)))
+      );
+      stdin.on("end", () => finish());
+      stdin.on("close", () => finish());
       stdin.resume();
       // Safety timer: don't hang forever if no EOF arrives.
-      setTimeout(resolve, 250).unref?.();
+      setTimeout(finish, 250).unref?.();
     } catch {
-      resolve();
+      finish();
     }
   });
 }
 
-/** Atomically replace a JSON file (write tmp then rename). */
+/**
+ * Run the recorded prior statusline command, feeding it the buffered stdin, and
+ * resolve with its captured stdout (string). Swallows every failure -> "".
+ */
+function runPrevStatusline(stdinBuf) {
+  return new Promise((resolve) => {
+    let prev;
+    try {
+      const raw = fs.readFileSync(PREV_STATUSLINE_PATH, "utf8");
+      prev = JSON.parse(raw);
+    } catch {
+      resolve("");
+      return;
+    }
+    const command = prev && typeof prev.command === "string" ? prev.command : "";
+    if (!command) {
+      resolve("");
+      return;
+    }
+    let child;
+    try {
+      child = spawn(command, { shell: true });
+    } catch {
+      resolve("");
+      return;
+    }
+    let out = "";
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      resolve(out);
+    };
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        // ignore
+      }
+      finish();
+    }, 2000);
+    if (timer.unref) timer.unref();
+    if (child.stdout) {
+      child.stdout.setEncoding("utf8");
+      child.stdout.on("data", (chunk) => {
+        out += chunk;
+      });
+    }
+    if (child.stderr) child.stderr.on("data", () => {});
+    child.on("error", () => {
+      clearTimeout(timer);
+      finish();
+    });
+    child.on("close", () => {
+      clearTimeout(timer);
+      finish();
+    });
+    try {
+      if (child.stdin) {
+        child.stdin.on("error", () => {});
+        if (stdinBuf && stdinBuf.length) child.stdin.write(stdinBuf);
+        child.stdin.end();
+      }
+    } catch {
+      // ignore: prior command may not read stdin
+    }
+  });
+}
+
+/** Atomically replace a JSON file (write tmp then rename). The temp name is
+// per-process so this render script and the daemon never share one .tmp and
+// tear each other's cache writes. */
 function writeJsonAtomic(filePath, data) {
-  const tmp = filePath + ".tmp";
+  const tmp = filePath + "." + process.pid + ".tmp";
   fs.writeFileSync(tmp, JSON.stringify(data));
   fs.renameSync(tmp, filePath);
 }
 
-async function main() {
-  await drainStdin();
-
-  // Missing cache -> nothing to show.
+/** Compute the ContextSpin snippet line (may be ""); bumps shownCount. */
+function contextSpinLine() {
   let cache;
   try {
     cache = JSON.parse(fs.readFileSync(CACHE_PATH, "utf8"));
   } catch {
-    return; // no output
+    return "";
   }
   const snippets = Array.isArray(cache && cache.snippets) ? cache.snippets : [];
-  if (snippets.length === 0) return;
+  if (snippets.length === 0) return "";
 
   // cooldownAfterShown from config (fallback 3).
   let cooldownAfterShown = 3;
@@ -95,13 +192,11 @@ async function main() {
     // keep fallback
   }
 
-  // Eligible: shownCount < cooldownAfterShown.
   const eligible = snippets.filter(
     (s) => s && typeof s.text === "string" && (s.shownCount || 0) < cooldownAfterShown
   );
-  if (eligible.length === 0) return;
+  if (eligible.length === 0) return "";
 
-  // Pick lowest shownCount, then most recent fetchedAt.
   eligible.sort((a, b) => {
     const ca = a.shownCount || 0;
     const cb = b.shownCount || 0;
@@ -112,7 +207,6 @@ async function main() {
   });
   const chosen = eligible[0];
 
-  // Bump shownCount on the chosen snippet within the original array and persist.
   chosen.shownCount = (chosen.shownCount || 0) + 1;
   try {
     writeJsonAtomic(CACHE_PATH, cache);
@@ -120,13 +214,50 @@ async function main() {
     // If we cannot persist, still show the snippet this time.
   }
 
-  // Single line of output. Await the write callback so the bytes are flushed to
-  // the pipe before process.exit (which does not wait for async stdout writes).
-  await new Promise((resolve) => {
-    process.stdout.write(String(chosen.text).replace(/\\r?\\n/g, " "), resolve);
+  return String(chosen.text).replace(/\\r?\\n/g, " ");
+}
+
+/** Write a string to stdout, awaiting the flush callback. */
+function writeOut(text) {
+  return new Promise((resolve) => {
+    try {
+      process.stdout.write(text, resolve);
+    } catch {
+      resolve();
+    }
   });
 }
 
+async function main() {
+  const stdinBuf = await readStdin();
+
+  // (a) Prior statusline output FIRST (verbatim, possibly multi-line).
+  let prevOut = "";
+  try {
+    prevOut = await runPrevStatusline(stdinBuf);
+  } catch {
+    prevOut = "";
+  }
+
+  // (b) ContextSpin snippet line.
+  let line = "";
+  try {
+    line = contextSpinLine();
+  } catch {
+    line = "";
+  }
+
+  // (c) Compose: prior output, then our line on its own line beneath. We only
+  // insert a separating newline when there is prior output that does not
+  // already end in one, so a lone ContextSpin line stays a single clean line.
+  let composed = prevOut;
+  if (line) {
+    if (composed && !composed.endsWith("\\n")) composed += "\\n";
+    composed += line;
+  }
+  if (composed) await writeOut(composed);
+}
+
 main()
   .then(() => process.exit(0))
   .catch(() => process.exit(0));
@@ -166,17 +297,22 @@ async function writeJsonAtomic(filePath, data) {
  * @property {string} statuslineJs - Path to the generated Node render script.
  * @property {string} settingsPath - Path to the patched Claude settings file.
  * @property {boolean} backedUp - Whether an existing statusLine was backed up.
+ * @property {boolean} composed - Whether we wrapped an existing statusline
+ *   (its output is composed above the ContextSpin line).
  * @property {string|null} warning - Human-readable warning, or null.
  */
 
 /**
- * Install the ContextSpin statusline integration:
+ * Install the ContextSpin statusline integration (NON-DESTRUCTIVE):
  *  - Writes the self-contained render script to STATUSLINE_JS.
  *  - Writes an executable bash wrapper to STATUSLINE_SH that execs the render
  *    script with stderr silenced.
+ *  - If an existing statusLine command (other than ours) is present, RECORDS it
+ *    to PREV_STATUSLINE_PATH (once — idempotent; never captures our own command)
+ *    so the render script can run it and prepend its output. Also backs up
+ *    settings.json to the .contextspin.bak once, as before.
  *  - Patches ~/.claude/settings.json so `statusLine` points at our wrapper, with
- *    `refreshInterval` in SECONDS (from config.injection.refresh). If an existing
- *    statusLine command (other than ours) is present, it is backed up once.
+ *    `refreshInterval` in SECONDS (from config.injection.refresh).
  *
  * @param {object} config - Normalized ContextSpin config (uses injection.refresh).
  * @returns {Promise<InstallStatuslineResult>}
@@ -184,21 +320,15 @@ async function writeJsonAtomic(filePath, data) {
 export async function installStatusline(config) {
   await fsp.mkdir(STATE_DIR, { recursive: true });
 
-  // (1) Render script.
-  const renderSource = buildRenderScript(CACHE_PATH, CONFIG_PATH);
-  await fsp.writeFile(STATUSLINE_JS, renderSource);
-
-  // (2) Bash wrapper. Silence stderr so node warnings never reach the status bar.
-  const shSource = `#!/usr/bin/env bash\nexec node ${JSON.stringify(STATUSLINE_JS)} 2>/dev/null\n`;
-  await fsp.writeFile(STATUSLINE_SH, shSource);
-  await fsp.chmod(STATUSLINE_SH, 0o755);
-
-  // (3) Patch Claude settings.
+  // (1) Patch Claude settings — first detect/record any existing statusline so
+  // the generated render script can compose it. (We read settings before
+  // writing the render script so a re-run never captures our own command.)
   await fsp.mkdir(path.dirname(CLAUDE_SETTINGS_PATH), { recursive: true });
   const settings = await readJsonSafe(CLAUDE_SETTINGS_PATH, {});
   const settingsObj = settings && typeof settings === "object" ? settings : {};
 
   let backedUp = false;
+  let composed = false;
   let warning = null;
 
   const existing = settingsObj.statusLine;
@@ -208,16 +338,47 @@ export async function installStatusline(config) {
     existing.command &&
     existing.command !== STATUSLINE_SH
   ) {
+    // NON-DESTRUCTIVE: record the prior command so we run it and prepend its
+    // output. We're inside the `existing.command !== STATUSLINE_SH` branch, so
+    // this never records our own wrapper. Refresh the record if the prior
+    // command changed out-of-band (otherwise a stale prior would keep running).
+    let recordedPrev = null;
+    try {
+      recordedPrev = JSON.parse(fs.readFileSync(PREV_STATUSLINE_PATH, "utf8"));
+    } catch {
+      recordedPrev = null;
+    }
+    if (!recordedPrev || recordedPrev.command !== String(existing.command)) {
+      await writeJsonAtomic(PREV_STATUSLINE_PATH, {
+        command: String(existing.command),
+        type: existing.type || "command",
+      });
+    }
+    composed = true;
+
     const backupPath = CLAUDE_SETTINGS_PATH + ".contextspin.bak";
     if (!fs.existsSync(backupPath)) {
       await fsp.copyFile(CLAUDE_SETTINGS_PATH, backupPath);
       backedUp = true;
     }
     warning =
-      `Existing statusLine command was overwritten (\`${existing.command}\`). ` +
+      `Existing statusLine command (\`${existing.command}\`) is preserved: ` +
+      `ContextSpin runs it and shows its output above the ContextSpin line. ` +
       `A backup of your settings is at ${backupPath}. Run \`contextspin uninject\` to restore it.`;
+  } else if (existing && typeof existing === "object" && existing.command === STATUSLINE_SH) {
+    // Already ours: a prior command may have been recorded on a previous run.
+    composed = fs.existsSync(PREV_STATUSLINE_PATH);
   }
 
+  // (2) Render script (now knows the prev-statusline path).
+  const renderSource = buildRenderScript(CACHE_PATH, CONFIG_PATH, PREV_STATUSLINE_PATH);
+  await fsp.writeFile(STATUSLINE_JS, renderSource);
+
+  // (3) Bash wrapper. Silence stderr so node warnings never reach the status bar.
+  const shSource = `#!/usr/bin/env bash\nexec node ${JSON.stringify(STATUSLINE_JS)} 2>/dev/null\n`;
+  await fsp.writeFile(STATUSLINE_SH, shSource);
+  await fsp.chmod(STATUSLINE_SH, 0o755);
+
   const refresh =
     config && config.injection && typeof config.injection.refresh === "number"
       ? config.injection.refresh
@@ -237,6 +398,7 @@ export async function installStatusline(config) {
     statuslineJs: STATUSLINE_JS,
     settingsPath: CLAUDE_SETTINGS_PATH,
     backedUp,
+    composed,
     warning,
   };
 }
@@ -249,10 +411,20 @@ export async function installStatusline(config) {
  * @property {string|null} note - Human-readable note, or null.
  */
 
+/** Best-effort removal of the recorded prev-statusline file. */
+async function removePrevStatusline() {
+  try {
+    await fsp.unlink(PREV_STATUSLINE_PATH);
+  } catch {
+    // best effort (may not exist)
+  }
+}
+
 /**
  * Uninstall the ContextSpin statusline integration. If the current
  * `statusLine.command` is ours, restore the `.contextspin.bak` backup when
- * present, otherwise just drop the `statusLine` key.
+ * present (which brings back the prior command), otherwise just drop the
+ * `statusLine` key. Always removes the recorded prev-statusline file.
  *
  * @returns {Promise<UninstallStatuslineResult>}
  */
@@ -290,6 +462,7 @@ export async function uninstallStatusline() {
       } catch {
         // best effort
       }
+      await removePrevStatusline();
       return {
         removed: true,
         restored: true,
@@ -301,6 +474,7 @@ export async function uninstallStatusline() {
 
   delete settings.statusLine;
   await writeJsonAtomic(CLAUDE_SETTINGS_PATH, settings);
+  await removePrevStatusline();
   return {
     removed: true,
     restored: false,