squads-cli 0.4.10 → 0.4.13

package/README.md

@@ -1,13 +1,22 @@
 # squads-cli
 
 [![npm version](https://img.shields.io/npm/v/squads-cli)](https://www.npmjs.com/package/squads-cli)
+[![npm downloads](https://img.shields.io/npm/dw/squads-cli)](https://www.npmjs.com/package/squads-cli)
+[![GitHub stars](https://img.shields.io/github/stars/agents-squads/squads-cli?style=social)](https://github.com/agents-squads/squads-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 
-**Organize, run, and track autonomous AI agents.** Built for Claude Code.
+**Open source CLI for AI agent coordination.** Organize agents into domain-aligned squads with persistent memory, goal tracking, and coordinated execution.
+
+```bash
+npm install -g squads-cli && squads init
+```
+
+> **Why squads?** AI agents are powerful alone, but real work needs coordination. Squads organizes agents by business domain, gives them persistent memory, tracks goals, and delivers outcomes—not just answers. Works with any AI coding assistant.
 
 ![squads dashboard](./assets/dashboard.png)
 
+⭐ **If you find this useful, [star the repo](https://github.com/agents-squads/squads-cli)** — it helps others discover it!
+
 ```
 $ squads status
 
@@ -29,13 +38,24 @@ $ squads status
 
 ## Why squads-cli?
 
-AI agents are powerful individually. But real work requires coordination.
+| Other Frameworks | squads-cli |
+|------------------|------------|
+| Framework lock-in | Markdown files you own |
+| Complex setup | `npm install -g` and go |
+| No memory | Persistent state across sessions |
+| Single agent focus | Domain-aligned teams |
+| Code-heavy | CLI-first, zero code to start |
+
+**Works with:** Claude Code, Cursor, Aider, Gemini, GitHub Copilot, and more.
+
+## Key Features
 
 - **Squads** — Group agents by domain (engineering, research, marketing)
 - **Memory** — Persistent state that survives across sessions
 - **Goals** — Track objectives and measure progress
 - **Sessions** — Real-time detection of running AI assistants
-- **Stack** — Local infrastructure for telemetry and memory
+- **Hooks** — Inject context at session start, sync memory at session end
+- **Stack** — Optional local infrastructure for telemetry and cost tracking
 
 No complex infrastructure. Just markdown files and a CLI.
 
@@ -285,6 +305,36 @@ squads memory show engineering
 squads memory query "performance"
 ```
 
+### Learning Loop
+
+Capture insights that persist across sessions:
+
+```bash
+# After fixing a bug
+squads learn "PostgreSQL connection pool exhaustion was caused by unclosed transactions"
+
+# With metadata
+squads learn "Always check memory before researching" --squad engineering --category pattern
+
+# View learnings
+squads learnings show engineering
+squads learnings search "postgres"
+```
+
+Learnings are stored in `.agents/memory/<squad>/shared/learnings.md` and sync with `squads memory sync`.
+
+**Categories:**
+- `success` — What worked well
+- `failure` — What didn't work (learn from mistakes)
+- `pattern` — Reusable approach
+- `tip` — General advice
+
+**The learning loop:**
+1. Session starts → hooks inject squad status + memory
+2. Work happens → you solve problems, discover things
+3. Session ends → Stop hook prompts "Capture learnings: squads learn..."
+4. Next session → Previous learnings compound via memory queries
+
 ### Goals with Metrics
 
 Goals can include optional metric annotations for tracking KPIs:
@@ -436,6 +486,19 @@ squads feedback show research -n 10                   # Show more entries
 squads feedback stats                                 # Summary across all squads
 ```
 
+### Learnings
+
+```bash
+squads learn "Insight here"                           # Capture a learning
+squads learn "Pattern" -s engineering -c pattern      # With squad and category
+squads learn "Tip" -t "cli,perf"                      # With tags
+squads learnings show engineering                     # View squad learnings
+squads learnings show engineering -n 5                # Limit results
+squads learnings show engineering --category pattern  # Filter by category
+squads learnings show engineering --tag perf          # Filter by tag
+squads learnings search "postgres"                    # Search all learnings
+```
+
 ### Session Management
 
 ```bash
@@ -729,6 +792,18 @@ squads feedback show <squad>         View history
   -n, --limit <n>                    Entries to show (default: 5)
 squads feedback stats                Summary across squads
 
+squads learn <insight>               Capture a learning
+  -s, --squad <squad>                Associate with squad (default: general)
+  -c, --category <category>          Category: success, failure, pattern, tip
+  -t, --tags <tags>                  Comma-separated tags
+  --context <context>                Additional context
+squads learnings show <squad>        View squad learnings
+  -n, --limit <n>                    Entries to show (default: 10)
+  --category <category>              Filter by category
+  --tag <tag>                        Filter by tag
+squads learnings search <query>      Search all learnings
+  -n, --limit <n>                    Results to show (default: 10)
+
 squads sessions                      List active sessions
   -v, --verbose                      Session details
   -j, --json                         JSON output
@@ -869,7 +944,7 @@ squads whoami                        Show user
 
 ## Claude Code Integration
 
-### Option 1: Session Hook (Recommended)
+### Option 1: Session Hooks (Recommended)
 
 Add to `.claude/settings.json`:
 
@@ -882,12 +957,21 @@ Add to `.claude/settings.json`:
         "command": "squads status",
         "timeout": 10
       }]
+    }],
+    "Stop": [{
+      "hooks": [{
+        "type": "command",
+        "command": "squads memory sync && echo \"\\n💡 Capture learnings: squads learn \\\"<insight>\\\"\\n\"",
+        "timeout": 15
+      }]
     }]
   }
 }
 ```
 
-Now every Claude Code session starts with squad context.
+Now every Claude Code session:
+- **Starts** with squad status injected
+- **Ends** with memory synced and a prompt to capture learnings
 
 ### Option 2: CLAUDE.md Instructions
 

package/dist/chunk-3TSY2K7R.js

@@ -0,0 +1,473 @@
+#!/usr/bin/env node
+
+// src/lib/squad-parser.ts
+import { readFileSync as readFileSync2, existsSync as existsSync2, readdirSync, writeFileSync as writeFileSync2 } from "fs";
+import { join as join2, basename } from "path";
+import matter from "gray-matter";
+
+// src/lib/mcp-config.ts
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "fs";
+import { join, dirname } from "path";
+var SERVER_REGISTRY = {};
+function getHome() {
+  return process.env.HOME || process.env.USERPROFILE || "";
+}
+function getContextsDir() {
+  return join(getHome(), ".claude", "contexts");
+}
+function getMcpConfigsDir() {
+  return join(getHome(), ".claude", "mcp-configs");
+}
+function generateMcpConfig(mcpServers) {
+  const config = { mcpServers: {} };
+  for (const server of mcpServers) {
+    const def = SERVER_REGISTRY[server];
+    if (def) {
+      config.mcpServers[server] = def;
+    }
+  }
+  return config;
+}
+function writeMcpConfig(config, path) {
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(path, JSON.stringify(config, null, 2));
+}
+function readMcpConfig(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const content = readFileSync(path, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+function resolveMcpConfig(squadName, mcpServers, forceRegenerate = false) {
+  const home = getHome();
+  const userOverride = join(getMcpConfigsDir(), `${squadName}.json`);
+  if (existsSync(userOverride)) {
+    const config = readMcpConfig(userOverride);
+    return {
+      path: userOverride,
+      source: "user-override",
+      servers: config ? Object.keys(config.mcpServers) : void 0
+    };
+  }
+  if (mcpServers && mcpServers.length > 0) {
+    const generatedPath = join(getContextsDir(), `${squadName}.mcp.json`);
+    const shouldGenerate = forceRegenerate || !existsSync(generatedPath);
+    if (shouldGenerate) {
+      const config2 = generateMcpConfig(mcpServers);
+      writeMcpConfig(config2, generatedPath);
+      return {
+        path: generatedPath,
+        source: "generated",
+        servers: Object.keys(config2.mcpServers),
+        generated: true
+      };
+    }
+    const config = readMcpConfig(generatedPath);
+    return {
+      path: generatedPath,
+      source: "generated",
+      servers: config ? Object.keys(config.mcpServers) : mcpServers,
+      generated: false
+    };
+  }
+  return {
+    path: join(home, ".claude.json"),
+    source: "fallback"
+  };
+}
+function resolveMcpConfigPath(squadName, mcpServers) {
+  return resolveMcpConfig(squadName, mcpServers).path;
+}
+
+// src/lib/squad-parser.ts
+function findSquadsDir() {
+  let dir = process.cwd();
+  for (let i = 0; i < 5; i++) {
+    const squadsPath = join2(dir, ".agents", "squads");
+    if (existsSync2(squadsPath)) {
+      return squadsPath;
+    }
+    const parent = join2(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+function findProjectRoot() {
+  const squadsDir = findSquadsDir();
+  if (!squadsDir) return null;
+  return join2(squadsDir, "..", "..");
+}
+function hasLocalInfraConfig() {
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) return false;
+  const envPath = join2(projectRoot, ".env");
+  if (!existsSync2(envPath)) return false;
+  const content = readFileSync2(envPath, "utf-8");
+  const infraKeys = ["LANGFUSE_", "SQUADS_BRIDGE", "SQUADS_POSTGRES", "SQUADS_REDIS"];
+  return infraKeys.some((key) => content.includes(key));
+}
+function listSquads(squadsDir) {
+  const squads = [];
+  const entries = readdirSync(squadsDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && !entry.name.startsWith("_")) {
+      const squadFile = join2(squadsDir, entry.name, "SQUAD.md");
+      if (existsSync2(squadFile)) {
+        squads.push(entry.name);
+      }
+    }
+  }
+  return squads;
+}
+function listAgents(squadsDir, squadName) {
+  const agents = [];
+  const dirs = squadName ? [squadName] : readdirSync(squadsDir, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith("_")).map((e) => e.name);
+  for (const dir of dirs) {
+    const squadPath = join2(squadsDir, dir);
+    if (!existsSync2(squadPath)) continue;
+    const files = readdirSync(squadPath);
+    for (const file of files) {
+      if (file.endsWith(".md") && file !== "SQUAD.md") {
+        const agentName = file.replace(".md", "");
+        agents.push({
+          name: agentName,
+          role: `Agent in ${dir}`,
+          trigger: "manual",
+          filePath: join2(squadPath, file)
+        });
+      }
+    }
+  }
+  return agents;
+}
+function parseSquadFile(filePath) {
+  const rawContent = readFileSync2(filePath, "utf-8");
+  const { data: frontmatter, content: bodyContent } = matter(rawContent);
+  const fm = frontmatter;
+  const lines = bodyContent.split("\n");
+  const squad = {
+    name: fm.name || basename(filePath).replace(".md", ""),
+    mission: fm.mission || "",
+    agents: [],
+    pipelines: [],
+    triggers: { scheduled: [], event: [], manual: [] },
+    routines: [],
+    dependencies: [],
+    outputPath: "",
+    goals: [],
+    // Apply frontmatter fields
+    effort: fm.effort,
+    context: fm.context,
+    repo: fm.repo,
+    stack: fm.stack,
+    providers: fm.providers,
+    // Preserve raw frontmatter for KPIs and other custom fields
+    frontmatter
+  };
+  let currentSection = "";
+  let inTable = false;
+  let tableHeaders = [];
+  for (const line of lines) {
+    if (line.startsWith("# Squad:")) {
+      squad.name = line.replace("# Squad:", "").trim().toLowerCase();
+      continue;
+    }
+    if (line.startsWith("## ")) {
+      currentSection = line.replace("## ", "").trim().toLowerCase();
+      inTable = false;
+      continue;
+    }
+    if (currentSection === "mission" && line.trim() && !line.startsWith("#")) {
+      if (!squad.mission) {
+        squad.mission = line.trim();
+      }
+    }
+    const effortMatch = line.match(/^effort:\s*(high|medium|low)/i);
+    if (effortMatch && !squad.effort) {
+      squad.effort = effortMatch[1].toLowerCase();
+    }
+    if (currentSection.includes("agent") || currentSection.includes("orchestrator") || currentSection.includes("evaluator") || currentSection.includes("builder") || currentSection.includes("priority")) {
+      if (line.includes("|") && line.includes("Agent")) {
+        inTable = true;
+        tableHeaders = line.split("|").map((h) => h.trim().toLowerCase());
+        continue;
+      }
+      if (inTable && line.includes("|") && !line.includes("---")) {
+        const cells = line.split("|").map((c) => c.trim().replace(/`/g, ""));
+        const agentIdx = tableHeaders.findIndex((h) => h === "agent");
+        const roleIdx = tableHeaders.findIndex((h) => h === "role");
+        const triggerIdx = tableHeaders.findIndex((h) => h === "trigger");
+        const statusIdx = tableHeaders.findIndex((h) => h === "status");
+        const effortIdx = tableHeaders.findIndex((h) => h === "effort");
+        if (agentIdx >= 0 && cells[agentIdx]) {
+          const effortValue = effortIdx >= 0 ? cells[effortIdx]?.toLowerCase() : void 0;
+          const effort = ["high", "medium", "low"].includes(effortValue || "") ? effortValue : void 0;
+          squad.agents.push({
+            name: cells[agentIdx],
+            role: roleIdx >= 0 ? cells[roleIdx] : "",
+            trigger: triggerIdx >= 0 ? cells[triggerIdx] : "manual",
+            status: statusIdx >= 0 ? cells[statusIdx] : "active",
+            effort
+          });
+        }
+      }
+    }
+    if (line.includes("\u2192") && line.includes("`")) {
+      const pipelineMatch = line.match(/`([^`]+)`\s*→\s*`([^`]+)`/g);
+      if (pipelineMatch) {
+        const agentNames = line.match(/`([^`]+)`/g)?.map((m) => m.replace(/`/g, "")) || [];
+        if (agentNames.length >= 2) {
+          squad.pipelines.push({
+            name: "default",
+            agents: agentNames
+          });
+        }
+      }
+    }
+    if (line.toLowerCase().includes("pipeline:")) {
+      const pipelineContent = line.split(":")[1];
+      if (pipelineContent && pipelineContent.includes("\u2192")) {
+        const agentNames = pipelineContent.match(/`([^`]+)`/g)?.map((m) => m.replace(/`/g, "")) || [];
+        if (agentNames.length >= 2) {
+          squad.pipelines.push({
+            name: "default",
+            agents: agentNames
+          });
+        }
+      }
+    }
+    if (line.toLowerCase().includes("primary") && line.includes("`")) {
+      const match = line.match(/`([^`]+)`/);
+      if (match) {
+        squad.outputPath = match[1].replace(/\/$/, "");
+      }
+    }
+    if (currentSection === "goals") {
+      const goalMatch = line.match(/^-\s*\[([ x])\]\s*(.+)$/);
+      if (goalMatch) {
+        const completed = goalMatch[1] === "x";
+        let description = goalMatch[2].trim();
+        let progress;
+        const progressMatch = description.match(/\(progress:\s*([^)]+)\)/i);
+        if (progressMatch) {
+          progress = progressMatch[1];
+          description = description.replace(progressMatch[0], "").trim();
+        }
+        squad.goals.push({
+          description,
+          completed,
+          progress
+        });
+      }
+    }
+  }
+  return squad;
+}
+function loadSquad(squadName) {
+  const squadsDir = findSquadsDir();
+  if (!squadsDir) return null;
+  const squadFile = join2(squadsDir, squadName, "SQUAD.md");
+  if (!existsSync2(squadFile)) return null;
+  return parseSquadFile(squadFile);
+}
+function loadAgentDefinition(agentPath) {
+  if (!existsSync2(agentPath)) return "";
+  return readFileSync2(agentPath, "utf-8");
+}
+function parseAgentProvider(agentPath) {
+  if (!existsSync2(agentPath)) return void 0;
+  const content = readFileSync2(agentPath, "utf-8");
+  try {
+    const { data: frontmatter } = matter(content);
+    if (frontmatter?.provider && typeof frontmatter.provider === "string") {
+      return frontmatter.provider.toLowerCase();
+    }
+  } catch {
+  }
+  const providerHeaderMatch = content.match(/##\s*Provider\s*\n+([a-zA-Z0-9_-]+)/i);
+  if (providerHeaderMatch) {
+    return providerHeaderMatch[1].toLowerCase();
+  }
+  return void 0;
+}
+function addGoalToSquad(squadName, goal) {
+  const squadsDir = findSquadsDir();
+  if (!squadsDir) return false;
+  const squadFile = join2(squadsDir, squadName, "SQUAD.md");
+  if (!existsSync2(squadFile)) return false;
+  let content = readFileSync2(squadFile, "utf-8");
+  if (!content.includes("## Goals")) {
+    const insertPoint = content.indexOf("## Dependencies");
+    if (insertPoint > 0) {
+      content = content.slice(0, insertPoint) + `## Goals
+
+- [ ] ${goal}
+
+` + content.slice(insertPoint);
+    } else {
+      content += `
+## Goals
+
+- [ ] ${goal}
+`;
+    }
+  } else {
+    const goalsIdx = content.indexOf("## Goals");
+    const nextSectionIdx = content.indexOf("\n## ", goalsIdx + 1);
+    const endIdx = nextSectionIdx > 0 ? nextSectionIdx : content.length;
+    const goalsSection = content.slice(goalsIdx, endIdx);
+    const lastGoalMatch = goalsSection.match(/^-\s*\[[ x]\].+$/gm);
+    if (lastGoalMatch) {
+      const lastGoal = lastGoalMatch[lastGoalMatch.length - 1];
+      const lastGoalIdx = content.lastIndexOf(lastGoal, endIdx);
+      const insertPos = lastGoalIdx + lastGoal.length;
+      content = content.slice(0, insertPos) + `
+- [ ] ${goal}` + content.slice(insertPos);
+    } else {
+      const headerEnd = goalsIdx + "## Goals".length;
+      content = content.slice(0, headerEnd) + `
+
+- [ ] ${goal}` + content.slice(headerEnd);
+    }
+  }
+  writeFileSync2(squadFile, content);
+  return true;
+}
+function updateGoalInSquad(squadName, goalIndex, updates) {
+  const squadsDir = findSquadsDir();
+  if (!squadsDir) return false;
+  const squadFile = join2(squadsDir, squadName, "SQUAD.md");
+  if (!existsSync2(squadFile)) return false;
+  const content = readFileSync2(squadFile, "utf-8");
+  const lines = content.split("\n");
+  let currentSection = "";
+  let goalCount = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith("## ")) {
+      currentSection = line.replace("## ", "").trim().toLowerCase();
+      continue;
+    }
+    if (currentSection === "goals") {
+      const goalMatch = line.match(/^-\s*\[([ x])\]\s*(.+)$/);
+      if (goalMatch) {
+        if (goalCount === goalIndex) {
+          let newLine = "- [" + (updates.completed ? "x" : " ") + "] " + goalMatch[2];
+          if (updates.progress !== void 0) {
+            newLine = newLine.replace(/\s*\(progress:\s*[^)]+\)/i, "");
+            if (updates.progress) {
+              newLine += ` (progress: ${updates.progress})`;
+            }
+          }
+          lines[i] = newLine;
+          writeFileSync2(squadFile, lines.join("\n"));
+          return true;
+        }
+        goalCount++;
+      }
+    }
+  }
+  return false;
+}
+function findSkillsDir() {
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) return null;
+  const skillsDir = join2(projectRoot, ".claude", "skills");
+  return existsSync2(skillsDir) ? skillsDir : null;
+}
+function findMemoryDir() {
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) return null;
+  const memoryDir = join2(projectRoot, ".agents", "memory");
+  return existsSync2(memoryDir) ? memoryDir : null;
+}
+function resolveSkillPath(skillName) {
+  const skillsDir = findSkillsDir();
+  if (!skillsDir) return null;
+  const skillPath = join2(skillsDir, skillName);
+  return existsSync2(skillPath) ? skillPath : null;
+}
+function resolveMemoryPaths(patterns) {
+  const memoryDir = findMemoryDir();
+  if (!memoryDir) return [];
+  const resolved = [];
+  for (const pattern of patterns) {
+    if (pattern.endsWith("/*")) {
+      const subdir = pattern.slice(0, -2);
+      const subdirPath = join2(memoryDir, subdir);
+      if (existsSync2(subdirPath)) {
+        try {
+          const files = readdirSync(subdirPath);
+          for (const file of files) {
+            if (file.endsWith(".md")) {
+              resolved.push(join2(subdirPath, file));
+            }
+          }
+        } catch {
+        }
+      }
+    } else {
+      const fullPath = join2(memoryDir, pattern);
+      if (existsSync2(fullPath)) {
+        resolved.push(fullPath);
+      }
+    }
+  }
+  return resolved;
+}
+function resolveExecutionContext(squad, forceRegenerate = false) {
+  const ctx = squad.context || {};
+  const mcpResolution = resolveMcpConfig(
+    squad.name,
+    ctx.mcp,
+    forceRegenerate
+  );
+  const skillPaths = [];
+  if (ctx.skills) {
+    for (const skill of ctx.skills) {
+      const path = resolveSkillPath(skill);
+      if (path) {
+        skillPaths.push(path);
+      }
+    }
+  }
+  const memoryPaths = ctx.memory?.load ? resolveMemoryPaths(ctx.memory.load) : [];
+  return {
+    // Copy all SquadContext fields
+    ...ctx,
+    // Add squad name
+    squadName: squad.name,
+    // Add resolved paths
+    resolved: {
+      mcpConfigPath: mcpResolution.path,
+      mcpSource: mcpResolution.source,
+      mcpServers: mcpResolution.servers || [],
+      skillPaths,
+      memoryPaths
+    }
+  };
+}
+
+export {
+  resolveMcpConfigPath,
+  findSquadsDir,
+  findProjectRoot,
+  hasLocalInfraConfig,
+  listSquads,
+  listAgents,
+  parseSquadFile,
+  loadSquad,
+  loadAgentDefinition,
+  parseAgentProvider,
+  addGoalToSquad,
+  updateGoalInSquad,
+  resolveExecutionContext
+};
+//# sourceMappingURL=chunk-3TSY2K7R.js.map