squads-cli 0.4.0 → 0.4.4

package/README.md

@@ -761,6 +761,86 @@ your-project/
 └── CLAUDE.md                # Project instructions
 ```
 
+## Analytics
+
+Track token usage, costs, and API calls across your squads.
+
+### Setup
+
+1. **Configure your Claude plan:**
+   ```bash
+   export SQUADS_PLAN_TYPE=max    # $200/mo flat rate
+   # or
+   export SQUADS_PLAN_TYPE=usage  # pay-per-token
+   ```
+
+2. **Connect to telemetry (optional):**
+   ```bash
+   # Self-hosted via Docker
+   cd docker && docker-compose up -d
+
+   # Or configure external services
+   export LANGFUSE_HOST=https://your-langfuse.com
+   export LANGFUSE_PUBLIC_KEY=pk-...
+   export LANGFUSE_SECRET_KEY=sk-...
+   ```
+
+3. **View in dashboard:**
+   ```bash
+   squads dash
+   ```
+
+### Metrics Tracked
+
+- Token usage (input/output/cache)
+- API costs per squad/agent
+- Rate limit status
+- Generation counts
+
+## Infrastructure
+
+Optional services that enhance squad capabilities.
+
+### Services
+
+| Service | Purpose |
+|---------|---------|
+| postgres | Session storage, trigger conditions |
+| redis | Caching, rate limiting |
+| otel | OpenTelemetry metrics pipeline |
+| langfuse | Telemetry dashboard |
+| bridge | Conversation capture API |
+
+### Self-Hosted Setup
+
+```bash
+# Clone the infrastructure
+git clone https://github.com/agents-squads/squads-infra
+cd squads-infra
+
+# Start services
+docker-compose up -d
+
+# Configure CLI
+squads stack env >> ~/.zshrc
+source ~/.zshrc
+
+# Verify
+squads stack health
+```
+
+### Minimal Setup (Postgres only)
+
+```bash
+# Just need triggers and session storage
+docker run -d --name squads-postgres \
+  -e POSTGRES_PASSWORD=squads \
+  -p 5432:5432 \
+  postgres:16
+
+export SQUADS_POSTGRES_URL=postgres://postgres:squads@localhost:5432/squads
+```
+
 ## Development
 
 ```bash

package/dist/cli.js

@@ -37,12 +37,15 @@ import {
 import { config } from "dotenv";
 import { existsSync as existsSync17 } from "fs";
 import { join as join17 } from "path";
-import { homedir as homedir6 } from "os";
+import { homedir as homedir5 } from "os";
 import { Command } from "commander";
 import chalk4 from "chalk";
 
 // src/version.ts
-var version = "0.3.0";
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+var pkg = require2("../package.json");
+var version = pkg.version;
 
 // src/commands/init.ts
 import chalk from "chalk";
@@ -830,6 +833,10 @@ async function initCommand(options) {
 
 Demonstrates squads functionality with safe, educational examples.
 
+## Goals
+
+- [ ] Run the demo agents and explore the dashboard
+
 ## Agents
 
 | Agent | Purpose |
@@ -965,44 +972,83 @@ Markdown report saved to .agents/outputs/demo/project-analysis.md
         claudeMdPath,
         `# Project Instructions
 
-## Squads CLI
+## What is Squads?
 
-This project uses AI agent squads for automation.
+Squads is a framework for building AI agent teams that automate real work.
+Each **squad** is a team of **agents** (markdown prompts) that execute via Claude.
 
-### Quick Start
+## For Claude (READ THIS)
 
-\`\`\`bash
-squads status          # Overview
-squads dash            # Full dashboard
-squads run demo        # Try the demo squad
-squads run <squad>     # Execute a squad
-\`\`\`
-
-### Memory
-
-Squads have persistent memory across sessions:
+When helping users with squad-related tasks:
 
+### Check Context First
 \`\`\`bash
-squads memory query "<topic>"   # Search memory
-squads memory show <squad>      # View squad memory
+squads status              # What squads exist?
+squads memory query "X"    # What do we know about X?
 \`\`\`
 
 ### Creating Agents
-
-Agents are markdown files in \`.agents/squads/<squad>/\`:
+Agents live in \`.agents/squads/<squad-name>/<agent-name>.md\`:
 
 \`\`\`markdown
-# My Agent
+# Agent Name
 
 ## Purpose
-What this agent does.
+One sentence: what this agent does.
 
 ## Instructions
-1. Step one
-2. Step two
+1. Specific step
+2. Another step
+3. Output location
 
 ## Output
-What it produces.
+What it produces and where it goes.
+\`\`\`
+
+### Running Agents
+\`\`\`bash
+squads run <squad>           # Run all agents in squad
+squads run <squad>/<agent>   # Run specific agent
+\`\`\`
+
+### Tracking Progress
+\`\`\`bash
+squads dash                  # Full dashboard with goals
+squads goal list             # View all goals
+squads goal set <squad> "X"  # Add a goal
+\`\`\`
+
+### Common User Requests
+
+| User says | You should |
+|-----------|------------|
+| "Create an agent to..." | Create \`.agents/squads/<squad>/<name>.md\` |
+| "Automate X" | Create agent, then \`squads run\` |
+| "What's the status?" | Run \`squads dash\` or \`squads status\` |
+| "Run the X agent" | \`squads run <squad>/x\` |
+| "Check memory" | \`squads memory query "<topic>"\` |
+
+## Quick Reference
+
+\`\`\`bash
+squads status          # Overview
+squads dash            # Full dashboard
+squads run demo        # Try demo squad
+squads list            # All agents
+squads memory query X  # Search memory
+squads goal list       # View goals
+\`\`\`
+
+## Project Structure
+
+\`\`\`
+.agents/
+\u251C\u2500\u2500 squads/           # Agent teams
+\u2502   \u2514\u2500\u2500 <squad>/
+\u2502       \u251C\u2500\u2500 SQUAD.md  # Squad definition
+\u2502       \u2514\u2500\u2500 *.md      # Agent files
+\u251C\u2500\u2500 memory/           # Persistent context
+\u2514\u2500\u2500 outputs/          # Agent outputs
 \`\`\`
 `
       );
@@ -1076,6 +1122,20 @@ function findSquadsDir() {
   }
   return null;
 }
+function findProjectRoot() {
+  const squadsDir = findSquadsDir();
+  if (!squadsDir) return null;
+  return join3(squadsDir, "..", "..");
+}
+function hasLocalInfraConfig() {
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) return false;
+  const envPath = join3(projectRoot, ".env");
+  if (!existsSync3(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 });
@@ -1749,7 +1809,7 @@ async function executeWithClaude(prompt2, verbose, _timeoutMinutes = 30, foregro
     writeLine(`  ${colors.dim}Session: ${sessionName}${RESET}`);
     writeLine(`  ${colors.dim}Auth: ${useApi ? "API credits" : "subscription"}${RESET}`);
   }
-  const claudeCmd = `cd '${projectRoot}' && claude --dangerously-skip-permissions --mcp-config '${userConfigPath}' -- '${escapedPrompt}'`;
+  const claudeCmd = `cd '${projectRoot}' && claude --dangerously-skip-permissions --mcp-config '${userConfigPath}' -- '${escapedPrompt}'; tmux kill-session -t ${sessionName} 2>/dev/null`;
   const tmux = spawn2("tmux", [
     "new-session",
     "-d",
@@ -1854,8 +1914,8 @@ function getPackageVersion() {
     ];
     for (const pkgPath of possiblePaths) {
       if (existsSync5(pkgPath)) {
-        const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
-        return pkg.version || "0.0.0";
+        const pkg2 = JSON.parse(readFileSync4(pkgPath, "utf-8"));
+        return pkg2.version || "0.0.0";
       }
     }
   } catch {
@@ -3533,6 +3593,7 @@ async function goalListCommand(squadName, options = {}) {
   const squadsDir = findSquadsDir();
   if (!squadsDir) {
     writeLine(`  ${colors.red}No .agents/squads directory found${RESET}`);
+    writeLine(`  ${colors.dim}Run \`squads init\` to create one.${RESET}`);
     return;
   }
   const squadsToCheck = squadName ? [squadName] : listSquads(squadsDir);
@@ -3844,7 +3905,6 @@ async function feedbackStatsCommand() {
 // src/commands/dashboard.ts
 import { readdirSync as readdirSync4, existsSync as existsSync10, statSync as statSync2 } from "fs";
 import { join as join10 } from "path";
-import { homedir as homedir4 } from "os";
 
 // src/lib/providers.ts
 var PROVIDERS = {
@@ -4155,7 +4215,7 @@ function detectPlan() {
   if (tier >= 1 && tier <= 2) {
     return { plan: "usage", confidence: "inferred", reason: `Tier ${tier} (new user)` };
   }
-  return { plan: "max", confidence: "inferred", reason: "Default (no config)" };
+  return { plan: "unknown", confidence: "inferred", reason: "Not configured" };
 }
 function getPlanType() {
   return detectPlan().plan;
@@ -4547,7 +4607,7 @@ async function fetchInsights(period = "week") {
     };
   }
 }
-async function fetchNpmStats(packageName = "squads-cli") {
+async function fetchNpmStats(packageName = process.env.SQUADS_NPM_PACKAGE || "squads-cli") {
   try {
     const [dayRes, weekRes, monthRes] = await Promise.all([
       fetch(`https://api.npmjs.org/downloads/point/last-day/${packageName}`),
@@ -4577,9 +4637,9 @@ async function fetchNpmStats(packageName = "squads-cli") {
 }
 
 // src/lib/db.ts
-import { createRequire } from "module";
-var require2 = createRequire(import.meta.url);
-var pg = require2("pg");
+import { createRequire as createRequire2 } from "module";
+var require3 = createRequire2(import.meta.url);
+var pg = require3("pg");
 var { Pool } = pg;
 var DATABASE_URL = process.env.SQUADS_DATABASE_URL || "postgresql://squads:squads_local_dev@localhost:5433/squads";
 var pool = null;
@@ -4735,6 +4795,7 @@ async function dashboardCommand(options = {}) {
   const squadsDir = findSquadsDir();
   if (!squadsDir) {
     writeLine(`${colors.red}No .agents/squads directory found${RESET}`);
+    writeLine(`${colors.dim}Run \`squads init\` to create one.${RESET}`);
     return;
   }
   if (options.ceo) {
@@ -4877,12 +4938,12 @@ async function dashboardCommand(options = {}) {
     const prs = gh?.prsMerged || 0;
     const issuesClosed = gh?.issuesClosed || 0;
     const issuesOpen = gh?.issuesOpen || 0;
-    const activeCount = squad.goals.filter((g) => !g.completed).length;
+    const completedCount = squad.goals.filter((g) => g.completed).length;
     const totalCount = squad.goals.length;
     const commitColor = commits > 10 ? colors.green : commits > 0 ? colors.cyan : colors.dim;
     const prColor = prs > 0 ? colors.green : colors.dim;
     const issueColor = issuesClosed > 0 ? colors.green : colors.dim;
-    writeLine(`  ${colors.purple}${box.vertical}${RESET} ${colors.cyan}${padEnd(squad.name, w.name)}${RESET}${commitColor}${padEnd(String(commits), w.commits)}${RESET}${prColor}${padEnd(String(prs), w.prs)}${RESET}${issueColor}${padEnd(`${issuesClosed}/${issuesOpen}`, w.issues)}${RESET}${padEnd(`${activeCount}/${totalCount}`, w.goals)}${progressBar(squad.goalProgress, 8)} ${colors.purple}${box.vertical}${RESET}`);
+    writeLine(`  ${colors.purple}${box.vertical}${RESET} ${colors.cyan}${padEnd(squad.name, w.name)}${RESET}${commitColor}${padEnd(String(commits), w.commits)}${RESET}${prColor}${padEnd(String(prs), w.prs)}${RESET}${issueColor}${padEnd(`${issuesClosed}/${issuesOpen}`, w.issues)}${RESET}${padEnd(`${completedCount}/${totalCount}`, w.goals)}${progressBar(squad.goalProgress, 8)} ${colors.purple}${box.vertical}${RESET}`);
   }
   writeLine(`  ${colors.purple}${box.bottomLeft}${colors.dim}${box.horizontal.repeat(tableWidth)}${colors.purple}${box.bottomRight}${RESET}`);
   writeLine();
@@ -4924,14 +4985,12 @@ async function dashboardCommand(options = {}) {
   await closeDatabase();
 }
 function findAgentsSquadsDir() {
-  const candidates = [
-    join10(process.cwd(), ".."),
-    join10(homedir4(), "agents-squads")
-  ];
-  for (const dir of candidates) {
-    if (existsSync10(join10(dir, "hq"))) {
-      return dir;
-    }
+  const parentDir = join10(process.cwd(), "..");
+  if (existsSync10(join10(parentDir, "hq"))) {
+    return parentDir;
+  }
+  if (existsSync10(join10(process.cwd(), ".git"))) {
+    return process.cwd();
   }
   return null;
 }
@@ -4983,19 +5042,36 @@ function renderGitPerformanceCached(cache) {
 function renderTokenEconomicsCached(cache, goalCount) {
   const costs = cache.costs;
   const stats = cache.bridgeStats;
-  if (!costs && !stats) {
-    writeLine(`  ${bold}Token Economics${RESET} ${colors.dim}(no data)${RESET}`);
-    writeLine(`  ${colors.dim}Set LANGFUSE_PUBLIC_KEY & LANGFUSE_SECRET_KEY for tracking${RESET}`);
+  const hasInfra = hasLocalInfraConfig();
+  const hasData = costs || stats;
+  writeLine(`  ${bold}Token Economics${RESET}`);
+  writeLine();
+  const planType = getPlanType();
+  const tier = parseInt(process.env.ANTHROPIC_TIER || "0", 10);
+  if (planType === "unknown") {
+    writeLine(`  ${colors.dim}\u25CB${RESET} ${bold}Plan${RESET} ${colors.yellow}not configured${RESET}`);
+    writeLine();
+    writeLine(`  ${colors.dim}Set your Claude plan:${RESET}`);
+    writeLine(`  ${colors.dim}$${RESET} export SQUADS_PLAN_TYPE=max   ${colors.dim}# $200/mo flat${RESET}`);
+    writeLine(`  ${colors.dim}$${RESET} export SQUADS_PLAN_TYPE=usage ${colors.dim}# pay-per-token${RESET}`);
+    writeLine();
+  } else {
+    const maxPlan = planType === "max";
+    const planIcon = maxPlan ? `${colors.purple}\u25C6${RESET}` : `${colors.dim}\u25CB${RESET}`;
+    const planLabel = maxPlan ? "Claude Max" : "Claude Pro";
+    const planCost = maxPlan ? "$200/mo flat" : "pay-per-token";
+    const tierDisplay = tier > 0 ? `  ${colors.dim}Tier ${tier}${RESET}` : "";
+    writeLine(`  ${planIcon} ${bold}${planLabel}${RESET} ${colors.dim}${planCost}${RESET}${tierDisplay}`);
+    writeLine();
+  }
+  if (!hasInfra || !hasData) {
+    writeLine(`  ${colors.dim}\u25CB${RESET} Track costs, tokens, and API usage`);
+    writeLine(`  ${colors.dim}\u25CB${RESET} Monitor rate limits and budgets`);
+    writeLine();
+    writeLine(`  ${colors.dim}Setup:${RESET} github.com/agents-squads/squads-cli#analytics`);
     writeLine();
     return;
   }
-  writeLine(`  ${bold}Token Economics${RESET}`);
-  writeLine();
-  const maxPlan = isMaxPlan();
-  const tier = parseInt(process.env.ANTHROPIC_TIER || "4", 10);
-  const planIcon = maxPlan ? `${colors.purple}\u25C6${RESET}` : `${colors.dim}\u25CB${RESET}`;
-  writeLine(`  ${planIcon} ${bold}Claude Max${RESET} ${colors.dim}$200/mo flat${RESET}  ${colors.dim}Tier ${tier}${RESET}`);
-  writeLine();
   const todayTokens = stats ? stats.today.inputTokens + stats.today.outputTokens : 0;
   const todayCalls = stats?.today.generations || costs?.totalCalls || 0;
   const todayCost = stats?.today.costUsd || costs?.totalCost || 0;
@@ -5041,12 +5117,13 @@ function renderTokenEconomicsCached(cache, goalCount) {
 }
 function renderInfrastructureCached(cache) {
   const stats = cache.bridgeStats;
-  if (!stats) {
-    writeLine(`  ${bold}Infrastructure${RESET} ${colors.dim}(bridge offline)${RESET}`);
+  const hasInfra = hasLocalInfraConfig();
+  if (!hasInfra || !stats) {
+    writeLine(`  ${bold}Infrastructure${RESET} ${colors.dim}(not connected)${RESET}`);
     writeLine();
-    writeLine(`  ${colors.dim}Start with:${RESET} cd docker && docker-compose up -d`);
-    writeLine(`  ${colors.dim}Docs:${RESET} https://agents-squads.com/docs/setup`);
-    writeLine(`  ${colors.yellow}Need help?${RESET} ${colors.dim}jorge@agents-squads.com${RESET}`);
+    writeLine(`  ${colors.dim}\u25CB${RESET} postgres  ${colors.dim}\u25CB${RESET} redis  ${colors.dim}\u25CB${RESET} otel`);
+    writeLine();
+    writeLine(`  ${colors.dim}Setup:${RESET} github.com/agents-squads/squads-cli#infrastructure`);
     writeLine();
     return;
   }
@@ -5081,6 +5158,10 @@ function renderInfrastructureCached(cache) {
   writeLine();
 }
 function renderAcquisitionCached(cache) {
+  const npmPackage = process.env.SQUADS_NPM_PACKAGE;
+  if (!npmPackage) {
+    return;
+  }
   const npm = cache.npmStats;
   if (!npm) {
     return;
@@ -5092,8 +5173,6 @@ function renderAcquisitionCached(cache) {
   writeLine(`  ${colors.cyan}${npm.downloads.lastWeek}${RESET} installs/week  ${trendIcon} ${trendColor}${Math.abs(npm.weekOverWeek)}%${RESET} ${colors.dim}wow${RESET}`);
   writeLine(`  ${colors.dim}Today${RESET} ${npm.downloads.lastDay}  ${colors.dim}\u2502${RESET}  ${colors.dim}Month${RESET} ${npm.downloads.lastMonth}`);
   writeLine();
-  writeLine(`  ${colors.dim}GitHub \u2192 npm install \u2192 squads dash \u2192 ?${RESET}`);
-  writeLine();
 }
 async function saveSnapshotCached(squadData, cache, _baseDir) {
   if (!cache.dbAvailable) return;
@@ -5564,6 +5643,7 @@ async function openIssuesCommand(options = {}) {
   const squadsDir = findSquadsDir();
   if (!squadsDir) {
     writeLine(`  ${colors.red}No .agents/squads directory found${RESET}`);
+    writeLine(`  ${colors.dim}Run \`squads init\` to create one.${RESET}`);
     return;
   }
   const evalAgents = findEvalAgents(squadsDir, options.squad);
@@ -5729,7 +5809,7 @@ import open from "open";
 import { createClient } from "@supabase/supabase-js";
 import { existsSync as existsSync11, readFileSync as readFileSync8, writeFileSync as writeFileSync8, mkdirSync as mkdirSync7 } from "fs";
 import { join as join12 } from "path";
-import { homedir as homedir5 } from "os";
+import { homedir as homedir4 } from "os";
 import "open";
 import http from "http";
 var PERSONAL_DOMAINS = [
@@ -5758,7 +5838,7 @@ var PERSONAL_DOMAINS = [
   "tutanota.com",
   "hey.com"
 ];
-var AUTH_DIR = join12(homedir5(), ".squads-cli");
+var AUTH_DIR = join12(homedir4(), ".squads-cli");
 var AUTH_PATH = join12(AUTH_DIR, "auth.json");
 function isPersonalEmail(email) {
   const domain = email.split("@")[1]?.toLowerCase();
@@ -6306,6 +6386,7 @@ async function resultsCommand(options = {}) {
   const squadsDir = findSquadsDir();
   if (!squadsDir) {
     writeLine(`${colors.red}No .agents/squads directory found${RESET}`);
+    writeLine(`${colors.dim}Run \`squads init\` to create one.${RESET}`);
     return;
   }
   const days = parseInt(options.days || "7", 10);
@@ -8160,7 +8241,7 @@ if (!process.stdout.isTTY) {
 var envPaths = [
   join17(process.cwd(), ".env"),
   join17(process.cwd(), "..", "hq", ".env"),
-  join17(homedir6(), "agents-squads", "hq", ".env")
+  join17(homedir5(), "agents-squads", "hq", ".env")
 ];
 for (const envPath of envPaths) {
   if (existsSync17(envPath)) {