swarmdo 1.54.1 → 1.58.6

package/.claude/helpers/statusline.cjs

@@ -105,7 +105,7 @@ function resolveCliBin() {
     ];
     try {
       const binDir = path.dirname(process.execPath);
-      const globalModuleDirs = [path.join(binDir, '..', 'lib', 'node_modules'), path.join(binDir, 'node_modules')];
+      const globalModuleDirs = [path.join(binDir, '..', 'lib', 'node_modules'), path.join(binDir, 'node_modules'), '/opt/homebrew/lib/node_modules', '/usr/local/lib/node_modules'];
       for (const prefix of [process.env.npm_config_prefix, process.env.PREFIX, path.join(home, '.npm-global')]) {
         if (prefix) globalModuleDirs.push(path.join(prefix, 'lib', 'node_modules'));
       }
@@ -148,6 +148,13 @@ function writeCache(data) {
  * and only counted ADRs in v3/implementation/adrs/ (missed v3/docs/adr/).
  */
 function getStatuslineData() {
+  // SWARMDO_STATUSLINE_NO_CLI: skip the CLI-delegation fork and render from local
+  // reads + stdin only. A cold render otherwise forks the hooks-statusline CLI
+  // (now more reachable via the global-node_modules probes below), and that fork
+  // can disturb the stdin cost payload; skipping it keeps renders fast, hermetic,
+  // and subprocess-free. Set by the statusline tests; usable by anyone who wants
+  // a no-fork statusline.
+  if (process.env.SWARMDO_STATUSLINE_NO_CLI) return buildLocalFallback();
   const cached = readCache();
   if (cached) return cached;
 
@@ -324,8 +331,8 @@ function buildLocalFallback() {
     user: { name: 'user', gitBranch: '', modelName: 'Claude Code' },
     v3Progress: { domainsCompleted: 0, totalDomains: 5, dddProgress: 0, patternsLearned: 0, sessionsCompleted: 0 },
     security: { status: 'NONE', critical: 0, high: 0, total: 0 },
-    swarm: { activeAgents: 0, maxAgents: CONFIG.maxAgents, coordinationActive: false },
-    system: { memoryMB: memMB, contextPct: 0, intelligencePct: 0, subAgents: 0 },
+    swarm: { activeSwarms: 0, activeAgents: 0, coordinationActive: false },
+    system: { memoryMB: memMB, contextPct: 0, intelligencePct: 0 },
     lastUpdated: new Date().toISOString(),
   });
 }
@@ -515,7 +522,7 @@ function getCostFromStdin() {
 // misses, the displayed version is meaningful (matches what the user
 // installed), not a stale hard-coded string.
 function getPkgVersion() {
-  let ver = '1.19.0';
+  let ver = '1.58.4';
   try {
     const home = os.homedir();
     const pkgPaths = [
@@ -531,7 +538,7 @@ function getPkgVersion() {
     // (bin/node_modules) layouts.
     try {
       const binDir = path.dirname(process.execPath);
-      const globalModuleDirs = [path.join(binDir, '..', 'lib', 'node_modules'), path.join(binDir, 'node_modules')];
+      const globalModuleDirs = [path.join(binDir, '..', 'lib', 'node_modules'), path.join(binDir, 'node_modules'), '/opt/homebrew/lib/node_modules', '/usr/local/lib/node_modules'];
       // #2221 follow-up: a custom npm prefix (e.g. ~/.npm-global) is decoupled from
       // the node binary location, so the binDir-derived probes above all miss. Also
       // probe the npm prefix from the environment and the common ~/.npm-global default.
@@ -585,12 +592,11 @@ function generateStatusline() {
   const totalDomains = progress.totalDomains || 5;
   const dddProgress = progress.dddProgress || 0;
   const patternsLearned = progress.patternsLearned || 0;
+  const activeSwarms = swarm.activeSwarms || 0;
   const activeAgents = swarm.activeAgents || 0;
-  const maxAgents = swarm.maxAgents || CONFIG.maxAgents;
   const coordinationActive = swarm.coordinationActive || false;
   const intelligencePct = system.intelligencePct || 0;
   const memoryMB = system.memoryMB || 0;
-  const subAgents = system.subAgents || 0;
   const secCritHigh = (security.critical || 0) + (security.high || 0);
   const secStatus = security.status || 'NONE';
   const secLabel = secStatus === 'VULN' ? 'sec ' + secCritHigh + '!' : secStatus === 'CLEAN' ? 'sec ✓' : secStatus === 'STALE' ? 'sec stale' : 'sec —';
@@ -657,16 +663,16 @@ function generateStatusline() {
   );
 
   // Line 2: Swarm + Hooks + CVE + Memory + Intelligence
-  const swarmInd = coordinationActive ? c.brightGreen + '◉' + c.reset : c.dim + '○' + c.reset;
-  const agentsColor = activeAgents > 0 ? c.brightGreen : c.red;
+  const swarmsColor = activeSwarms > 0 ? c.brightGreen : c.dim;
+  const agentsColor = activeAgents > 0 ? c.brightGreen : c.dim;
   const secIcon = secStatus === 'CLEAN' ? '🟢' : secStatus === 'STALE' ? '🟡' : (secStatus === 'NONE' ? '⚪' : '🔴');
   const secColor = secStatus === 'CLEAN' ? c.brightGreen : secStatus === 'STALE' ? c.brightYellow : (secStatus === 'NONE' ? c.dim : c.brightRed);
   const hooksColor = hooksEnabled > 0 ? c.brightGreen : c.dim;
   const intellColor = intelligencePct >= 80 ? c.brightGreen : intelligencePct >= 40 ? c.brightYellow : c.dim;
 
   if (seg('swarm')) lines.push(
-    c.brightYellow + '🤖 Swarm' + c.reset + '  ' + swarmInd + ' [' + agentsColor + String(activeAgents).padStart(2) + c.reset + '/' + c.brightWhite + maxAgents + c.reset + ']  ' +
-    c.brightPurple + '👥 ' + subAgents + c.reset + '    ' +
+    c.brightYellow + '🐝 Swarms' + c.reset + ' ' + swarmsColor + activeSwarms + c.reset + '    ' +
+    c.brightYellow + '🤖 Agents' + c.reset + ' ' + agentsColor + activeAgents + c.reset + '    ' +
     c.brightBlue + '🪝 ' + hooksColor + hooksEnabled + c.reset + '/' + c.brightWhite + hooksTotal + c.reset + '    ' +
     secIcon + ' ' + secColor + secLabel + c.reset + '    ' +
     c.brightCyan + '💾 ' + memoryMB + 'MB' + c.reset + '    ' +

package/README.md

@@ -2,7 +2,7 @@
 
 [![swarmdo](swarmdo/assets/brand/logo-full.svg)](https://swarmdo.com)
 
-[![npm version (swarmdo)](https://img.shields.io/badge/npx%20swarmdo-v1.54.1-cb3837?style=for-the-badge&logo=npm&logoColor=white)](https://github.com/SwarmDo/swarmdo/releases)
+[![npm version (swarmdo)](https://img.shields.io/badge/npx%20swarmdo-v1.58.6-cb3837?style=for-the-badge&logo=npm&logoColor=white)](https://github.com/SwarmDo/swarmdo/releases)
 [![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://github.com/SwarmDo/swarmdo/blob/main/LICENSE)
 [![Website](https://img.shields.io/badge/swarmdo.com-e2a33c?style=for-the-badge&logoColor=black)](https://swarmdo.com)
 [![Star on GitHub](https://img.shields.io/github/stars/SwarmDo/swarmdo?style=for-the-badge&logo=github&color=gold)](https://github.com/SwarmDo/swarmdo)
@@ -271,7 +271,7 @@ The recent release train added a full day-to-day operations layer around the swa
 
 | Command | What it does |
 |---------|-------------|
-| `swarmdo usage` (alias `cost`) | Claude Code **spend analytics** from your local transcripts — `daily`, `weekly`, `monthly` (with a month-end spend projection), `models`, `projects`, `sessions`, live 5-hour `blocks` burn, `errors` (tool-failure analytics), `cache` (prompt-cache efficiency + $ saved), `diff` (period-over-period comparison with per-model movers), `reflect` (a wrapped-style retrospective — busiest day, streak, top models/projects, peak hour, delegation ratio — with a shareable `--html` dashboard), and `limits` (an official-quota **exhaustion forecaster** over Claude Code's `rate_limits`); the standard views take `--csv` for spreadsheet export |
+| `swarmdo usage` (alias `cost`) | Claude Code **spend analytics** from your local transcripts — `daily`, `weekly`, `monthly` (with a month-end spend projection), `models`, `projects`, `sessions`, live 5-hour `blocks` burn, `errors` (tool-failure analytics), `friction` (how often you interrupt Claude + which tool was running + dominant error categories), `cache` (prompt-cache efficiency + $ saved), `diff` (period-over-period comparison with per-model movers), `reflect` (a wrapped-style retrospective — busiest day, streak, top models/projects, peak hour, delegation ratio — with a shareable `--html` dashboard), and `limits` (an official-quota **exhaustion forecaster** over Claude Code's `rate_limits`); the standard views take `--csv` for spreadsheet export |
 | `swarmdo usage guard` | **Budget policy** — limits for the active 5h block / today / month via flags or `SWARMDO_GUARD_*` env → ok / warn / over; `--strict` exits 1, safe for CI gates and Stop hooks |
 | `swarmdo hud` | **One-screen ops HUD** — 5h block burn, task readiness, daemon workers, memory snapshots (`--watch`, `--json`) |
 | `swarmdo repair` (alias `tdd-repair`) | **Test-Driven Repair** — a bounded, budget-capped headless `claude` loop that fixes source until a failing test passes; dry-run unless `--confirm` |
@@ -293,6 +293,7 @@ The recent release train added a full day-to-day operations layer around the swa
 | `swarmdo ownership` | **Who owns each file, and what breaks if they leave** — a per-file knowledge map + bus factor from git history: the dominant author, ownership concentration, and the fewest authors whose churn clears 50% (a lone owner is flagged ⚠ key-person), plus a repo-wide truck factor. `--since`, `--min-churn`, `--top`, `--csv`, `--format json`. code-maat main-dev / CodeScene "Knowledge Map"; also an MCP tool (`ownership`). Deterministic |
 | `swarmdo hidden-coupling` | **Co-change with no import edge** — join the two graphs swarmdo already owns (temporal `coupling` from git + `codegraph`'s import graph) and emit the set difference: file pairs that keep changing together yet nothing in the code links them ("logical minus structural coupling" — a config and its consumers, a schema and its mirror type). The co-edit `affected` can't see. `--since`, `--min-shared`, `--csv`, `--format json`. Grounded in Gall et al. (ICSM 1998). Deterministic |
 | `swarmdo standup` (alias `mine`) | **What did I do?** — your commits since your last working day, grouped by day with a diffstat. **Weekend-aware** (git-standup parity): on Monday it reaches back to Friday, on Sunday to Friday, otherwise to yesterday — one-command recall for a standup or for re-orienting at the start of a session. Defaults to the current git user; `--author <name>`/`--all` for teammates, `--days N` or `--since 2w` to override the window, `--format json`. Pure engine (weekend math + per-day fold) → fixture-tested. Deterministic |
+| `swarmdo commands` (alias `slash`) | **Hot/cold/orphan usage report** for your authored `.claude/` surface — which custom slash-commands (`.claude/commands/**`) and subagents (`.claude/agents/**`) you actually invoke (**hot**, with counts), which are **cold** (defined but never used → prune candidates), and which are **orphan** (invoked but undefined → a typo or a builtin). `config lint` says "are these valid?"; this says "are these used?" — joining the defined files against invocation counts mined from local transcripts (`<command-name>` markers + `subagent_type` fields). `--unused` prints just the prune list, `--unused --strict` is a CI gate (exit 1 if anything's dead), `--all` counts across every project, `--json`. Pure parsers + join → fixture-tested |
 | `swarmdo agent bridge` | **Link Claude Code agents ⇄ Swarmdo** — the fix for "Swarmdo is installed but never actually used." Swarmdo can't call Claude Code's `Agent` tool (only the main loop can), so `agent bridge register -n <name>` binds a real Claude Code agent into Swarmdo's registry (`swarmdo agent list` stops being empty) and **auto-spins-up a swarm from your config, enrolling the agent** — the next bind joins the same swarm. `bridge list` (bound vs native), `bridge sync --live a,b` (reconcile drift), `bridge advise "<prompt>"` (should this warrant a swarm? which roles?). Also MCP tools `agent_bridge_register`/`agent_bridge_list`. Pure engine → 16 tests |
 | `swarmdo testreport` | **JUnit/TAP → failure digest** — turn raw test-result files into the exact failing test names + `file:line` + assertion messages, instead of scanning hundreds of log lines. The front-half of the test→fix loop: feed the failures straight into `repair`. Reads a file, a directory, or stdin; `--ci` exits 1 on any failure, `--format json`. Also an MCP tool (`testreport`). Deterministic |
 | `swarmdo integrations` (alias `integrate`) | **Use swarmdo from Codex CLI, GitHub Copilot CLI, and pi** — one command wires AGENTS.md + each CLI's MCP config (idempotent, dry-run first, never touches your Claude Code setup) |
@@ -301,7 +302,7 @@ The recent release train added a full day-to-day operations layer around the swa
 | `swarmdo mcp doctor` | **MCP config diagnosis** — missing binaries, bad URLs, malformed entries across `.mcp.json` + `~/.claude.json` |
 | `swarmdo config lint` | **Static config validation** — the pure shape layer for `swarmdo.config.json`, the `.claude/settings*.json` hooks block, `.mcp.json`, **`.claude/agents/*.md` subagents** (missing `name`/`description`, a `name` duplicated across files — CC silently loads only one — a bad `model`, malformed frontmatter), and **custom slash commands + skills** (malformed YAML that makes CC load empty metadata, a bad `effort`, an inline `` !`cmd` `` bash-injection that's inert or not covered by `allowed-tools`). `--strict` gates CI |
 | `swarmdo permissions` (alias `perms`) | **Audit your Claude Code permission rules** — static analysis of `permissions.allow`/`deny`/`ask` in `.claude/settings*.json`: flags allow↔deny conflicts (dead rules), over-broad `Bash(*)` grants, shadowed/redundant rules, duplicates, and malformed entries. `--strict` gates CI. Read-only; the static-safety sibling of `config lint` / `mcp doctor` |
-| `swarmdo comms` (alias `mailbox`) | **Cross-session agent mailbox** — one Claude Code session messages another by name (`send -t <session>`, `-t all` broadcasts, `inbox`, `read`, `watch`); sessions on the same repo share `.swarmdo/comms/`. `inbox --hook` surfaces new mail as prompt context without polling. Also MCP tools (`comms_send`/`comms_inbox`) |
+| `swarmdo comms` (alias `mailbox`) | **Cross-session, cross-tool agent mailbox** — one agent session (Claude Code, Codex, Copilot, or pi) messages another by name (`send -t <session>`, `-t all` broadcasts, `inbox`, `read`, `watch`); sessions on the same repo share `.swarmdo/comms/`. Non-Claude agents set `$SWARMDO_AGENT` for a stable identity. `inbox --hook` surfaces new mail as prompt context without polling. Also MCP tools (`comms_send`/`comms_inbox`) |
 | `swarmdo hooks memory-inject` | **Prompt-time semantic memory injection** — embeds each prompt, vector-searches your stored memories, and injects the most relevant under a token budget (recall at the moment of need); wire it with `hooks recipe memory-inject` |
 | `swarmdo hooks notify -d` | **Desktop notifications** — OS-native toast (macOS `osascript`, Linux `notify-send`) |
 | `swarmdo hooks recipe` | **One-command Claude Code hooks** — install `notify-done`/`notify-input` (desktop pings), `memory-inject` (relevant memories each prompt), `comms-inbox` (new mail as context), or `command-guard` (a PreToolUse deny hook that blocks dangerous bash — `rm -rf /`, pipe-to-shell, force-push to main — the net swarmdo needs when running headless); dry-run by default, idempotent merge that never clobbers your settings |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swarmdo",
-  "version": "1.54.1",
+  "version": "1.58.6",
   "description": "Swarmdo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

package/v3/@swarmdo/cli/dist/src/command-usage/usage.d.ts

@@ -0,0 +1,74 @@
+/**
+ * command-usage/usage.ts — a hot/cold/orphan USAGE report for a project's
+ * authored `.claude/` surface. `config lint` validates these files; this answers
+ * the orthogonal "are they actually used?" by joining the DEFINED set
+ * (`.claude/commands/**​/*.md` + `.claude/agents/**​/*.md`) against INVOCATION
+ * counts mined from the local transcripts (`<command-name>` markers +
+ * `"subagent_type"` fields). Three buckets: hot (defined & invoked), cold
+ * (defined, never invoked → prune candidates), orphan (invoked, not defined →
+ * typo / removed / builtin). #101.
+ *
+ * The parsers + join are pure and unit-tested; only collectCommandUsage touches
+ * the filesystem. Reuses defaultClaudeProjectDirs/findTranscriptFiles.
+ */
+export interface UsageItem {
+    name: string;
+    count: number;
+}
+export interface UsageBuckets {
+    /** defined AND invoked (count > 0), desc by count */
+    hot: UsageItem[];
+    /** defined but never invoked — prune candidates, sorted */
+    cold: string[];
+    /** invoked but not defined (typo / removed / builtin), sorted */
+    orphan: string[];
+}
+export interface CommandUsageReport {
+    commands: UsageBuckets;
+    agents: UsageBuckets;
+    filesScanned: number;
+    definedCommands: number;
+    definedAgents: number;
+    scope: 'project' | 'all';
+}
+/**
+ * Count custom slash-command invocations from raw transcript lines. Scoped to
+ * user-role lines (the `<command-name>` marker is injected on the user turn) so
+ * an assistant merely quoting the marker never inflates a count. The captured
+ * name is de-slashed (`/goal` → `goal`) to match the discovered-file key space.
+ * Pure.
+ */
+export declare function parseCommandInvocations(lines: string[]): Map<string, number>;
+/**
+ * Count subagent (Task tool) invocations by `subagent_type` from raw transcript
+ * lines. Not user-scoped — the field lives in an assistant `tool_use` block. Pure.
+ */
+export declare function parseSubagentInvocations(lines: string[]): Map<string, number>;
+/** Merge src counts into dest (dest mutated). */
+export declare function mergeCounts(dest: Map<string, number>, src: Map<string, number>): void;
+/**
+ * Join a DEFINED name list against INVOCATION counts into hot/cold/orphan. Both
+ * sides are compared de-slashed, so a defined `/build` matches a `build` count
+ * (agents carry no slash, so they're unaffected). Pure & deterministic. */
+export declare function joinUsage(defined: string[], counts: Map<string, number> | Record<string, number>): UsageBuckets;
+/**
+ * Discover the authored `.claude/` surface for a project. Command names use
+ * Claude Code's subdir namespacing (`.claude/commands/sDo/x.md` → `sDo:x`, top
+ * level → `x`) to match the `<command-name>` marker; agent names are the file
+ * basename (subagent_type is never namespaced). Pure w.r.t. inputs (reads fs).
+ */
+export declare function discoverAuthored(cwd: string): {
+    commands: string[];
+    agents: string[];
+};
+export interface CollectOptions {
+    cwd?: string;
+    /** scan every project's transcripts (default: only the current project) */
+    all?: boolean;
+}
+/** The encoded transcript-dir name Claude Code uses for a project path. */
+export declare function encodeProjectDir(cwd: string): string;
+/** Build the full report: discover authored files, mine invocation counts from
+ * the (project-scoped, or --all) transcripts, and join. fs-touching wrapper. */
+export declare function collectCommandUsage(opts?: CollectOptions): CommandUsageReport;
+//# sourceMappingURL=usage.d.ts.map

package/v3/@swarmdo/cli/dist/src/command-usage/usage.js

@@ -0,0 +1,161 @@
+/**
+ * command-usage/usage.ts — a hot/cold/orphan USAGE report for a project's
+ * authored `.claude/` surface. `config lint` validates these files; this answers
+ * the orthogonal "are they actually used?" by joining the DEFINED set
+ * (`.claude/commands/**​/*.md` + `.claude/agents/**​/*.md`) against INVOCATION
+ * counts mined from the local transcripts (`<command-name>` markers +
+ * `"subagent_type"` fields). Three buckets: hot (defined & invoked), cold
+ * (defined, never invoked → prune candidates), orphan (invoked, not defined →
+ * typo / removed / builtin). #101.
+ *
+ * The parsers + join are pure and unit-tested; only collectCommandUsage touches
+ * the filesystem. Reuses defaultClaudeProjectDirs/findTranscriptFiles.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { defaultClaudeProjectDirs, findTranscriptFiles } from '../usage/transcript-usage.js';
+const uniqSort = (xs) => [...new Set(xs)].sort((a, b) => a.localeCompare(b));
+/**
+ * Count custom slash-command invocations from raw transcript lines. Scoped to
+ * user-role lines (the `<command-name>` marker is injected on the user turn) so
+ * an assistant merely quoting the marker never inflates a count. The captured
+ * name is de-slashed (`/goal` → `goal`) to match the discovered-file key space.
+ * Pure.
+ */
+export function parseCommandInvocations(lines) {
+    const counts = new Map();
+    for (const line of lines) {
+        if (!/"(?:type|role)"\s*:\s*"user"/.test(line))
+            continue;
+        for (const m of line.matchAll(/<command-name>([^<]+)<\/command-name>/g)) {
+            const name = m[1].trim().replace(/^\/+/, '');
+            if (!name || name === '…')
+                continue;
+            counts.set(name, (counts.get(name) ?? 0) + 1);
+        }
+    }
+    return counts;
+}
+/**
+ * Count subagent (Task tool) invocations by `subagent_type` from raw transcript
+ * lines. Not user-scoped — the field lives in an assistant `tool_use` block. Pure.
+ */
+export function parseSubagentInvocations(lines) {
+    const counts = new Map();
+    for (const line of lines) {
+        for (const m of line.matchAll(/"subagent_type"\s*:\s*"([^"]+)"/g)) {
+            const name = m[1].trim();
+            if (name)
+                counts.set(name, (counts.get(name) ?? 0) + 1);
+        }
+    }
+    return counts;
+}
+/** Merge src counts into dest (dest mutated). */
+export function mergeCounts(dest, src) {
+    for (const [k, v] of src)
+        dest.set(k, (dest.get(k) ?? 0) + v);
+}
+/**
+ * Join a DEFINED name list against INVOCATION counts into hot/cold/orphan. Both
+ * sides are compared de-slashed, so a defined `/build` matches a `build` count
+ * (agents carry no slash, so they're unaffected). Pure & deterministic. */
+export function joinUsage(defined, counts) {
+    const asMap = counts instanceof Map ? counts : new Map(Object.entries(counts));
+    const norm = (n) => n.replace(/^\/+/, '');
+    const get = (n) => asMap.get(norm(n)) ?? 0;
+    const definedNorm = new Set(defined.map(norm));
+    const hot = [];
+    const cold = [];
+    for (const d of defined) {
+        const c = get(d);
+        if (c > 0)
+            hot.push({ name: d, count: c });
+        else
+            cold.push(d);
+    }
+    const orphan = [];
+    for (const [k, v] of asMap) {
+        if (v > 0 && !definedNorm.has(norm(k)))
+            orphan.push(k);
+    }
+    hot.sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+    return { hot, cold: uniqSort(cold), orphan: uniqSort(orphan) };
+}
+/** All `.md` files under `root`, as paths RELATIVE to root (recursive; skips
+ * dotfiles). Mirrors config.ts's walkMd so `config lint` and this command agree
+ * on what counts as "defined". */
+function walkMdRel(root) {
+    const out = [];
+    const rec = (dir, prefix) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith('.'))
+                continue;
+            const rel = prefix ? `${prefix}/${e.name}` : e.name;
+            if (e.isDirectory())
+                rec(path.join(dir, e.name), rel);
+            else if (e.isFile() && e.name.endsWith('.md'))
+                out.push(rel);
+        }
+    };
+    rec(root, '');
+    return out;
+}
+/**
+ * Discover the authored `.claude/` surface for a project. Command names use
+ * Claude Code's subdir namespacing (`.claude/commands/sDo/x.md` → `sDo:x`, top
+ * level → `x`) to match the `<command-name>` marker; agent names are the file
+ * basename (subagent_type is never namespaced). Pure w.r.t. inputs (reads fs).
+ */
+export function discoverAuthored(cwd) {
+    const commands = walkMdRel(path.join(cwd, '.claude', 'commands')).map((rel) => rel.replace(/\.md$/, '').split('/').join(':'));
+    const agents = walkMdRel(path.join(cwd, '.claude', 'agents')).map((rel) => path.basename(rel).replace(/\.md$/, ''));
+    return { commands: uniqSort(commands), agents: uniqSort(agents) };
+}
+/** The encoded transcript-dir name Claude Code uses for a project path. */
+export function encodeProjectDir(cwd) {
+    return cwd.replace(/\//g, '-');
+}
+/** Build the full report: discover authored files, mine invocation counts from
+ * the (project-scoped, or --all) transcripts, and join. fs-touching wrapper. */
+export function collectCommandUsage(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const { commands: definedCommands, agents: definedAgents } = discoverAuthored(cwd);
+    const encoded = encodeProjectDir(cwd);
+    const cmdCounts = new Map();
+    const agentCounts = new Map();
+    let filesScanned = 0;
+    for (const dir of defaultClaudeProjectDirs()) {
+        for (const t of findTranscriptFiles(dir)) {
+            if (!opts.all && t.project !== encoded)
+                continue;
+            filesScanned++;
+            let content;
+            try {
+                content = fs.readFileSync(t.file, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const fileLines = content.split('\n');
+            mergeCounts(cmdCounts, parseCommandInvocations(fileLines));
+            mergeCounts(agentCounts, parseSubagentInvocations(fileLines));
+        }
+    }
+    return {
+        commands: joinUsage(definedCommands, cmdCounts),
+        agents: joinUsage(definedAgents, agentCounts),
+        filesScanned,
+        definedCommands: definedCommands.length,
+        definedAgents: definedAgents.length,
+        scope: opts.all ? 'all' : 'project',
+    };
+}
+//# sourceMappingURL=usage.js.map

package/v3/@swarmdo/cli/dist/src/commands/commands.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `swarmdo commands` (alias `slash`) — a hot/cold/orphan USAGE report for the
+ * project's authored `.claude/` slash-commands + subagents. `config lint` says
+ * "are these valid?"; this says "are these used?" by joining defined files
+ * against invocation counts mined from the local transcripts. #101.
+ *
+ *   swarmdo commands                # this project's authored surface
+ *   swarmdo commands --all          # count invocations across every project
+ *   swarmdo commands --unused       # only the cold (never-invoked) items
+ *   swarmdo commands --unused --strict   # exit 1 if anything is unused (CI gate)
+ *   swarmdo commands --json         # machine-readable
+ *
+ * Engine (../command-usage/usage.ts) is pure + fixture-tested; this thin layer
+ * renders and applies the --unused/--strict policy.
+ */
+import type { Command } from '../types.js';
+export declare const commandsCommand: Command;
+export default commandsCommand;
+//# sourceMappingURL=commands.d.ts.map

package/v3/@swarmdo/cli/dist/src/commands/commands.js

@@ -0,0 +1,107 @@
+/**
+ * `swarmdo commands` (alias `slash`) — a hot/cold/orphan USAGE report for the
+ * project's authored `.claude/` slash-commands + subagents. `config lint` says
+ * "are these valid?"; this says "are these used?" by joining defined files
+ * against invocation counts mined from the local transcripts. #101.
+ *
+ *   swarmdo commands                # this project's authored surface
+ *   swarmdo commands --all          # count invocations across every project
+ *   swarmdo commands --unused       # only the cold (never-invoked) items
+ *   swarmdo commands --unused --strict   # exit 1 if anything is unused (CI gate)
+ *   swarmdo commands --json         # machine-readable
+ *
+ * Engine (../command-usage/usage.ts) is pure + fixture-tested; this thin layer
+ * renders and applies the --unused/--strict policy.
+ */
+import { output } from '../output.js';
+import { collectCommandUsage } from '../command-usage/usage.js';
+/** Render one domain's hot/cold/orphan buckets. `slash` prefixes command names. */
+function renderBuckets(label, defined, b, slash) {
+    const nm = (n) => (slash ? `/${n}` : n);
+    output.writeln('');
+    output.writeln(output.bold(`${label}`) + output.dim(`  (${defined} defined · ${b.hot.length} hot · ${b.cold.length} cold · ${b.orphan.length} orphan)`));
+    if (b.hot.length > 0) {
+        output.printTable({
+            columns: [
+                { key: 'name', header: 'Hot (used)', width: 34 },
+                { key: 'count', header: 'Invocations', width: 12, align: 'right' },
+            ],
+            data: b.hot.map((h) => ({ name: nm(h.name), count: h.count.toLocaleString('en-US') })),
+        });
+    }
+    if (b.cold.length > 0) {
+        output.writeln(output.warning(`  cold (never invoked — prune candidates): `) + b.cold.map(nm).join('  '));
+    }
+    if (b.orphan.length > 0) {
+        output.writeln(output.dim(`  orphan (invoked, not defined — builtin or typo): `) + b.orphan.map(nm).join('  '));
+    }
+    if (b.hot.length === 0 && b.cold.length === 0 && b.orphan.length === 0) {
+        output.writeln(output.dim('  (none)'));
+    }
+}
+/** Print only the cold (unused) items — the prune list. Returns the cold count. */
+function renderUnused(report) {
+    const coldCmds = report.commands.cold;
+    const coldAgents = report.agents.cold;
+    const total = coldCmds.length + coldAgents.length;
+    output.writeln(output.bold('Unused (cold) authored items') + output.dim(`  (${report.scope} scope · ${report.filesScanned} transcript files)`));
+    if (total === 0) {
+        output.writeln(output.info('  none — every authored command and agent has been invoked 🎉'));
+        return 0;
+    }
+    if (coldCmds.length > 0)
+        output.writeln(`  commands: ${coldCmds.map((c) => `/${c}`).join('  ')}`);
+    if (coldAgents.length > 0)
+        output.writeln(`  agents:   ${coldAgents.join('  ')}`);
+    return total;
+}
+async function run(ctx) {
+    const cwd = ctx.cwd || process.cwd();
+    const all = ctx.flags.all === true;
+    const report = collectCommandUsage({ cwd, all });
+    if (ctx.flags.json === true) {
+        output.writeln(JSON.stringify(report, null, 2));
+        return { success: true, exitCode: 0 };
+    }
+    if (report.definedCommands === 0 && report.definedAgents === 0) {
+        output.writeln(output.info('nothing authored — no .claude/commands or .claude/agents in this project'));
+        return { success: true, exitCode: 0 };
+    }
+    if (ctx.flags.unused === true) {
+        const coldCount = renderUnused(report);
+        const strict = ctx.flags.strict === true;
+        const exitCode = strict && coldCount > 0 ? 1 : 0;
+        if (exitCode === 1)
+            output.writeln(output.dim(`exit 1 (--strict + ${coldCount} unused)`));
+        return { success: exitCode === 0, exitCode };
+    }
+    output.writeln(output.bold('Authored .claude/ surface — usage') + output.dim(`  (${report.scope} scope · ${report.filesScanned} transcript files)`));
+    renderBuckets('Commands', report.definedCommands, report.commands, true);
+    renderBuckets('Agents', report.definedAgents, report.agents, false);
+    const totalCold = report.commands.cold.length + report.agents.cold.length;
+    if (totalCold > 0) {
+        output.writeln('');
+        output.writeln(output.dim(`${totalCold} unused — see \`swarmdo commands --unused\` (add --strict for a CI gate)`));
+    }
+    return { success: true, exitCode: 0 };
+}
+export const commandsCommand = {
+    name: 'commands',
+    aliases: ['slash'],
+    description: "Usage report (hot/cold/orphan) for the project's authored .claude/ slash-commands & subagents",
+    options: [
+        { name: 'all', description: 'count invocations across every project (default: current project only)', type: 'boolean', default: false },
+        { name: 'unused', description: 'print only the cold (never-invoked) items — the prune list', type: 'boolean', default: false },
+        { name: 'strict', description: 'with --unused, exit 1 if anything is unused (CI gate)', type: 'boolean', default: false },
+        { name: 'json', description: 'machine-readable output', type: 'boolean', default: false },
+    ],
+    examples: [
+        { command: 'swarmdo commands', description: 'Hot/cold/orphan report for your authored .claude/ surface' },
+        { command: 'swarmdo commands --unused', description: 'List slash-commands & agents you defined but never invoke' },
+        { command: 'swarmdo commands --unused --strict', description: 'CI gate: fail if any authored command/agent is unused' },
+        { command: 'swarmdo slash --all --json', description: 'Cross-project invocation counts as JSON (alias)' },
+    ],
+    action: run,
+};
+export default commandsCommand;
+//# sourceMappingURL=commands.js.map

package/v3/@swarmdo/cli/dist/src/commands/hooks.d.ts

@@ -3,6 +3,32 @@
  * Self-learning hooks system for intelligent workflow automation
  */
 import type { Command } from '../types.js';
+/**
+ * Live swarm + agent counts for the statusline (`🐝 Swarms N   🤖 Agents M`).
+ * These are two distinct numbers, read from two canonical registries:
+ *   - agents: `.swarmdo/agents/store.json` + the hive `.swarmdo/agents.json`
+ *     (what `agent_spawn`, `swarm_init`, `agent bridge register`, and hive-mind
+ *     workers write) — every non-terminated agent is counted.
+ *   - swarms: `.swarmdo/swarm/swarm-state.json` — every `status: 'running'`
+ *     swarm whose host process is still alive; dead-pid / >24h-stale orphans are
+ *     skipped read-only (mirrors reconcileOrphanSwarms without persisting).
+ *
+ * The agent count replaces the old `ps aux | grep -c agentic-flow` heuristic,
+ * which (a) was blind to in-process agents — Claude Code Task-tool subagents and
+ * bridged agents never appear as a separate `agentic-flow` OS process — so the
+ * count never moved when a swarm spun up, and (b) false-positived on any process
+ * whose args merely mention "agentic-flow" (a grep, an open editor buffer, the
+ * ONNX embedder), showing phantom agents when none were running.
+ *
+ * No `maxAgents` denominator is reported: swarm size is never enforced at spawn
+ * time (the config value is an advisory hint feeding an internal [1,50]
+ * backstop), so a `[N/max]` gauge would imply a live cap that does not exist.
+ */
+export declare function computeSwarmStatus(cwd?: string): {
+    activeSwarms: number;
+    activeAgents: number;
+    coordinationActive: boolean;
+};
 export declare const hooksCommand: Command;
 export default hooksCommand;
 //# sourceMappingURL=hooks.d.ts.map