contextspin 0.6.0 → 0.6.3

package/README.md

@@ -1,6 +1,10 @@
 # ContextSpin
 
-Replace the Claude Code spinner / status bar text with live org context — meetings, Slack mentions, CI failures, incidents, review queues — pulled from tools you already run.
+Live context in your Claude Code **status bar** — weather, the top Hacker News story, PRs awaiting your review, CI failures, incidents, meetings — pulled from tools you already run. Install in one line; the bar is never empty.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/mannutech/contextspin/main/install.sh | bash
+```
 
 ## Key principle: ContextSpin does NOT fetch data
 
@@ -33,15 +37,14 @@ ContextSpin polls those sources on a schedule, formats whatever they return into
                               │  read cache
                               ▼
   ┌─────────────────────────────────────────────────────────┐
-  │  INJECTOR                                                 │
+  │  INJECTOR  (statusline — non-destructive, composed)       │
   │   statusline  ──►  ~/.contextspin/statusline.sh           │
-  │                    patches ~/.claude/settings.json        │
-  │   patcher     ──►  rewrites spinner words in the binary   │
-  │                    (EXPERIMENTAL)                          │
+  │                    composed into ~/.claude/settings.json   │
+  │   patcher     ──►  rewrites spinner words (EXPERIMENTAL)   │
   └───────────────────────────┬─────────────────────────────┘
                               │
                               ▼
-        Claude Code spinner / status bar shows one snippet
+            Claude Code status bar shows one snippet
 ```
 
 The daemon and the injector are decoupled by the cache file: the daemon writes snippets, the injector reads them. Each runs on its own clock.
@@ -170,7 +173,7 @@ ContextSpin reads one JSON file: `~/.contextspin.json` (override with the `CONTE
 
 | Field | Type | Format / values | Default | Meaning |
 |-------|------|-----------------|---------|---------|
-| `sources` | array | non-empty | — | List of sources to poll. Required. |
+| `sources` | array | — | `[]` | Sources to poll. May be empty (the bar then shows the built-in defaults). |
 | `sources[].type` | string | `mcp` \| `cli` \| `http` | — | Source kind. Required. |
 | `sources[].tool` | string | tool name or `mcp__server__tool` | — | Required for `mcp`. |
 | `sources[].command` | string | shell command | — | Required for `cli`. |
@@ -183,6 +186,7 @@ ContextSpin reads one JSON file: `~/.contextspin.json` (override with the `CONTE
 | `injection.mode` | string | `statusline` \| `patcher` \| `both` | `statusline` | How snippets reach the UI. |
 | `injection.refresh` | number | seconds | `30` | Daemon poll interval and status-line refresh interval (seconds). |
 | `injection.maxVisible` | number | count | `5` | Global cap on snippets held in the cache. |
+| `injection.style` | boolean | — | `true` | Render the line in a styled box (cyan bars + italic). Set `false` for plain text. |
 | `snippets.deduplication` | boolean | — | `true` | Drop snippets with duplicate text when merging. |
 | `snippets.cooldownAfterShown` | number | count | `3` | A snippet stops being eligible once shown this many times. |
 | `snippets.priorityOrder` | string[] | source labels | `[]` | Earlier labels sort first (case-insensitive); unlisted sort last. |
@@ -207,9 +211,9 @@ This is the supported path. It uses Claude Code's official [status line](https:/
 
 1. Write `~/.contextspin/statusline-render.js` — a self-contained script that drains stdin (so Claude Code's piped JSON can't cause `EPIPE`), reads the cache, picks the eligible snippet with the lowest `shownCount` (then most recent), increments its count, writes the cache back, and prints that one line. Any error exits cleanly with no output, so it can never break your status bar.
 2. Write `~/.contextspin/statusline.sh` — a `0755` bash wrapper that `exec`s the render script.
-3. Patch `~/.claude/settings.json` to set `statusLine` to `{ type: "command", command: "<statusline.sh>", padding: 0, refreshInterval: <refresh> }` (refresh is in **seconds**). If you already had a different status line, it is backed up to `~/.claude/settings.json.contextspin.bak` first.
+3. Point `statusLine` at that wrapper (refresh in **seconds**), **non-destructively**: any status line you already had is preserved and *composed* — the render script runs your prior command and prints its output **above** the ContextSpin line. Scope-aware: in a project (when `CLAUDE_PROJECT_DIR` is set) it writes the gitignored `<project>/.claude/settings.local.json`, which outranks a repo's tracked `settings.json`, so a project's own status line can't shadow ContextSpin.
 
-Reverse it with `contextspin uninject` (restores your previous status line if a backup exists).
+Reverse it with `contextspin uninject` (this scope) or `contextspin uninstall` (every scope it ever wired, plus the hook and daemon).
 
 ### `patcher` (EXPERIMENTAL — binary patching)
 
@@ -258,13 +262,16 @@ Restore the originals with `contextspin uninject --mode patcher` (or `inject --m
 
 | Command | What it does |
 |---------|--------------|
-| `contextspin setup [--yes]` | Create `~/.contextspin.json` (interactive, or from the bundled example with `--yes` / non-TTY). |
+| `contextspin install` | **One-shot install:** wire a self-healing SessionStart hook, create the config, wire the statusline, and start the daemon. (This is what the curl script runs.) |
+| `contextspin uninstall` | **Full teardown:** remove the hook, restore your prior statusline in **every** scope it wired, and stop the daemon. |
+| `contextspin setup [--yes]` | Create `~/.contextspin.json` (interactive, or a detected config with `--yes` / non-TTY). |
 | `contextspin start` | Start the detached polling daemon. |
 | `contextspin stop` | Stop the daemon. |
 | `contextspin restart` | Stop then start. |
 | `contextspin status` | Show daemon state and the current cached snippets (source, age, shown count). |
-| `contextspin inject [--mode <m>]` | Install the injector. `<m>` overrides `injection.mode` (`statusline` / `patcher` / `both`). |
-| `contextspin uninject [--mode <m>]` | Reverse the injector. |
+| `contextspin ensure` | Idempotent: create config + wire statusline + start daemon (run by the SessionStart hook each session). |
+| `contextspin inject [--mode <m>]` | Install just the injector. `<m>` overrides `injection.mode` (`statusline` / `patcher` / `both`). |
+| `contextspin uninject [--mode <m>]` | Reverse just the injector. |
 | `contextspin` *(no subcommand)* | `setup` if unconfigured, otherwise `start` then `inject`. |
 
 ## High-impact snippets
@@ -306,16 +313,18 @@ Three tiers, by how time-sensitive they are.
 
 ## Limitations
 
-- **MCP support is stdio-only.** ContextSpin discovers MCP servers from `~/.claude.json` (user and per-project scopes) and `.mcp.json`, and connects only to **stdio** servers (those with a `command`). HTTP / SSE / WebSocket MCP transports are not supported in Stage 1 — use a `cli` or `http` source instead. Plugin / managed scopes are ignored.
+- **MCP support is stdio-only.** ContextSpin discovers MCP servers from `~/.claude.json` (user and per-project scopes) and `.mcp.json`, and connects only to **stdio** servers (those with a `command`). HTTP / SSE / WebSocket MCP transports are not supported — use a `cli` or `http` source instead. Plugin / managed scopes are ignored.
 - **OAuth-based claude.ai connectors are not reachable.** App-connected connectors (Slack, Notion, etc. linked through claude.ai) authenticate via OAuth tokens stored in the OS keychain. A standalone background daemon has no access to those tokens, so it cannot drive those connectors. Use the corresponding CLI (`gh`, `slack` CLI…) or HTTP endpoint, or a locally-configured stdio MCP server, instead.
 - **The status line shows one rotating snippet** at a time, honoring `cooldownAfterShown` so the same item doesn't repeat indefinitely.
 - **The patcher is experimental** and is **overwritten by every Claude Code update**. Treat it as best-effort; the statusline mode is the supported path.
 
-## Roadmap
+## Zero-config defaults (never an empty bar)
+
+A fresh install needs no setup:
 
-- **Stage 1 (now):** stdio MCP / CLI / HTTP sources, polling daemon + cache, statusline injection, experimental binary patcher, the CLI above.
-- **Stage 2 (polish):** quality-of-life improvements — better source discovery, richer setup wizard, more diagnostics.
-- **Stage 3 (`.plugin`):** package ContextSpin as a first-class Claude Code plugin.
+- The config is seeded with a **no-credentials starter pack** — local weather, a dad joke, and the top Hacker News story — so real snippets appear within seconds.
+- When the cache is empty or every snippet is exhausted, the renderer falls back to **built-in defaults** (jokes + "ask `/contextspin`…" tips) that rotate, so the bar is never blank — even offline or before the first poll.
+- A Claude Code **plugin** is also available (the [`mannutech` marketplace](https://github.com/mannutech/claude-plugins)) for those who prefer installing that way — it wraps this same package.
 
 ## References
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contextspin",
-  "version": "0.6.0",
+  "version": "0.6.3",
   "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

@@ -25,7 +25,11 @@ import {
   isDaemonRunning,
   readCache,
 } from './daemon.js';
-import { installStatusline, uninstallStatusline } from './inject/statusline.js';
+import {
+  installStatusline,
+  uninstallStatusline,
+  uninstallAllStatuslines,
+} from './inject/statusline.js';
 import { installPatcher, restorePatcher } from './inject/patcher.js';
 import { detectSources } from './detect.js';
 
@@ -475,11 +479,17 @@ async function runUninject(opts = {}) {
 /**
  * The SessionStart hook command the `install` flow wires into the user settings
  * so ContextSpin self-heals every session (the curl install replicates what the
- * Claude Code plugin's hook does, without the marketplace). Runs from a neutral
- * dir so npx never resolves a confused local package (Exit 127).
+ * Claude Code plugin's hook does, without the marketplace).
+ *
+ * The hook is pinned to the EXACT version doing the install (never `@latest` or a
+ * range), so a future release never runs on the user's machine without them
+ * deliberately re-installing. Runs from a neutral dir so npx never resolves a
+ * confused local package (Exit 127).
+ * @returns {string}
  */
-const SESSIONSTART_HOOK_CMD =
-  'cd /tmp && npx --yes contextspin ensure >/dev/null 2>&1; exit 0';
+function sessionStartHookCmd() {
+  return `cd /tmp && npx --yes contextspin@${readVersion()} ensure >/dev/null 2>&1; exit 0`;
+}
 
 /**
  * Read+parse a JSON file, returning a fallback on any read/parse error.
@@ -522,12 +532,24 @@ function addSessionStartHook() {
   const obj = settings && typeof settings === 'object' ? settings : {};
   obj.hooks = obj.hooks && typeof obj.hooks === 'object' ? obj.hooks : {};
   const arr = Array.isArray(obj.hooks.SessionStart) ? obj.hooks.SessionStart : [];
-  if (arr.some(entryRunsContextspin)) return false;
-  arr.push({
+
+  const desired = sessionStartHookCmd();
+  const existing = arr.find(entryRunsContextspin);
+  const alreadyCurrent =
+    existing &&
+    Array.isArray(existing.hooks) &&
+    existing.hooks.some((h) => h && h.command === desired);
+  // Already exactly this command (same pinned version) — nothing to do.
+  if (alreadyCurrent) return false;
+
+  // Upsert: drop any prior ContextSpin entry (e.g. an older pinned version) and
+  // add the current one, so re-installing a newer version re-pins cleanly.
+  const others = arr.filter((e) => !entryRunsContextspin(e));
+  others.push({
     matcher: '',
-    hooks: [{ type: 'command', command: SESSIONSTART_HOOK_CMD, timeout: 15 }],
+    hooks: [{ type: 'command', command: desired, timeout: 15 }],
   });
-  obj.hooks.SessionStart = arr;
+  obj.hooks.SessionStart = others;
   fs.writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(obj, null, 2));
   return true;
 }
@@ -580,13 +602,21 @@ async function runInstall() {
  */
 async function runUninstall() {
   const removedHook = removeSessionStartHook();
-  await uninstallStatusline({});
+  // Tear down EVERY scope we wired (user + each project the hook touched), not
+  // just the user scope — otherwise project-scoped wirings keep rendering.
+  const results = await uninstallAllStatuslines();
+  const removed = results.filter((r) => r && r.removed);
   await stopDaemon();
   console.log(
-    removedHook
-      ? 'ContextSpin uninstalled (hook removed, statusline restored, daemon stopped).'
-      : 'ContextSpin hook not found; statusline restored and daemon stopped.',
+    `ContextSpin uninstalled: removed the statusline from ${removed.length} ` +
+      `scope${removed.length === 1 ? '' : 's'}, ` +
+      `${removedHook ? 'dropped the SessionStart hook, ' : ''}stopped the daemon.`,
   );
+  const projectScopes = removed.filter((r) => r.scope === 'project');
+  if (projectScopes.length > 0) {
+    console.log('Cleaned project statuslines:');
+    for (const r of projectScopes) console.log(`  ${r.settingsPath}`);
+  }
 }
 
 /**

package/src/config.js

@@ -47,6 +47,16 @@ export const STATUSLINE_JS = path.join(STATE_DIR, "statusline-render.js");
  */
 export const PREV_STATUSLINE_PATH = path.join(STATE_DIR, "prev-statusline.json");
 
+/**
+ * Path to the registry of every settings file ContextSpin has wired its
+ * statusLine into. A JSON array of scope KEYS ("" for the user scope, else an
+ * absolute realpath'd project dir). `installStatusline` appends to it; a full
+ * `uninstall` walks it so EVERY scope is torn down — not just the user scope.
+ * Without this, project-scoped wirings (written by the SessionStart hook per
+ * CLAUDE_PROJECT_DIR) would linger after uninstall.
+ */
+export const WIRED_STATUSLINES_PATH = path.join(STATE_DIR, "wired-statuslines.json");
+
 /** Path to Claude Code's settings file (patched by the statusline injector). */
 export const CLAUDE_SETTINGS_PATH = path.join(HOME, ".claude", "settings.json");
 

package/src/daemon.js

@@ -5,7 +5,7 @@ import fsp from "node:fs/promises";
 import process from "node:process";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { CACHE_PATH, STATE_DIR, PID_PATH, LOG_PATH, loadConfig } from "./config.js";
+import { CACHE_PATH, STATE_DIR, PID_PATH, LOG_PATH, loadConfig, configExists } from "./config.js";
 import { runSource } from "./runner.js";
 
 /**
@@ -187,6 +187,15 @@ export async function runDaemonLoop(opts = {}) {
   const runtime = { lastRun: {}, buckets: {}, snippets: [] };
   // eslint-disable-next-line no-constant-condition
   while (true) {
+    // Self-exit if the config has been deleted (e.g. the user ran
+    // `contextspin uninstall` or removed ~/.contextspin.json by hand). Without
+    // this the daemon would keep polling stale sources and writing the cache
+    // forever, so the statusline would still show text after a teardown.
+    if (!configExists(opts.configPath)) {
+      console.log("contextspin config removed — daemon shutting down.");
+      shutdown();
+      return;
+    }
     try {
       const snippets = await pollOnce(config, runtime);
       await writeCache({ updatedAt: nowISO(), snippets });

package/src/inject/statusline.js

@@ -33,6 +33,7 @@ import {
   CONFIG_PATH,
   CLAUDE_SETTINGS_PATH,
   DEFAULT_SNIPPETS,
+  WIRED_STATUSLINES_PATH,
 } from "../config.js";
 
 /**
@@ -460,6 +461,29 @@ async function writePrevMap(map) {
   await writeJsonAtomic(PREV_STATUSLINE_PATH, map);
 }
 
+/**
+ * Read the wired-statuslines registry: an array of scope KEYS ("" for user
+ * scope, else an absolute project dir). Tolerates a missing/bad file (-> []).
+ * @returns {string[]}
+ */
+function readWiredList() {
+  const raw = readJsonSafeSync(WIRED_STATUSLINES_PATH, null);
+  return Array.isArray(raw) ? raw.filter((k) => typeof k === "string") : [];
+}
+
+/**
+ * Record a scope KEY in the wired-statuslines registry (idempotent).
+ * @param {string} key - "" for user scope, else an absolute project dir.
+ * @returns {Promise<void>}
+ */
+async function addWired(key) {
+  const list = readWiredList();
+  if (!list.includes(key)) {
+    list.push(key);
+    await writeJsonAtomic(WIRED_STATUSLINES_PATH, list);
+  }
+}
+
 /**
  * Resolve the statusLine command currently configured in a settings file (if
  * any), ignoring our own wrapper. Returns null when the file has no usable
@@ -625,6 +649,10 @@ export async function installStatusline(config, opts = {}) {
 
   await writeJsonAtomic(targetPath, settingsObj);
 
+  // Record this scope in the wired registry so a later `uninstall` can tear down
+  // EVERY scope we touched (not just the user scope).
+  await addWired(key);
+
   if (composed) {
     const priorCmd = prior ? prior.command : (map[key] && map[key].command);
     warning =
@@ -772,3 +800,42 @@ export async function uninstallStatusline(opts = {}) {
     note: "Removed the ContextSpin statusLine entry.",
   };
 }
+
+/**
+ * Tear down EVERY statusline scope ContextSpin has wired, by walking the wired
+ * registry (plus the user scope, always). This is what a full `uninstall` should
+ * call: project-scoped wirings written by the SessionStart hook (one per
+ * CLAUDE_PROJECT_DIR) are otherwise invisible to a user-scope-only uninstall and
+ * would keep rendering the ContextSpin line after removal.
+ *
+ * Clears the registry when done. Never throws — a failure for one scope is
+ * captured in that scope's result and the walk continues.
+ *
+ * @returns {Promise<UninstallStatuslineResult[]>}
+ */
+export async function uninstallAllStatuslines() {
+  // Always include the user scope (""), plus every recorded project key.
+  const keys = Array.from(new Set(["", ...readWiredList()]));
+  const results = [];
+  for (const key of keys) {
+    const projectDir = key === "" ? undefined : key;
+    try {
+      results.push(await uninstallStatusline({ projectDir }));
+    } catch (err) {
+      results.push({
+        removed: false,
+        restored: false,
+        settingsPath: key,
+        scope: projectDir ? "project" : "user",
+        note: `failed: ${err && err.message ? err.message : String(err)}`,
+      });
+    }
+  }
+  // Registry is consumed — drop it.
+  try {
+    await fsp.unlink(WIRED_STATUSLINES_PATH);
+  } catch {
+    // best effort
+  }
+  return results;
+}