squads-cli 0.6.1 → 0.7.0

package/README.md

@@ -1,1096 +1,168 @@
-# squads-cli
+<div align="center">
 
-[![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)
-[![Docs](https://img.shields.io/badge/docs-agents--squads.com-purple)](https://agents-squads.com/docs)
-
-**Build your AI workforce.** Finance, marketing, engineering, operations — AI agents organized into domain-aligned squads that actually run your business.
-
-📖 **[Documentation](https://agents-squads.com/docs)** · 🚀 **[Getting Started](https://agents-squads.com/onboarding)** · 💡 **[Architecture Guide](https://agents-squads.com/engineering/squads-architecture)**
-
-```bash
-npm install -g squads-cli && squads init
-```
-
-> **Why squads?** A full business team costs $1M+/year. An AI workforce costs API calls. Squads organizes AI agents by business domain — giving them persistent memory, goals, and coordinated execution. Your agents, your data, no lock-in. Works with Claude, GPT-4, Gemini, and more.
-
-![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
-
-  squads status
-  ● 7 active sessions across 1 squad (claude 7)
-
-  10/10 squads  │  memory: enabled
-
-  ┌────────────────────────────────────────────────────────┐
-  │ SQUAD           AGENTS  MEMORY        ACTIVITY         │
-  ├────────────────────────────────────────────────────────┤
-  │ cli             7       1 entry       today            │
-  │ engineering     6       1 entry       today            │
-  │ intelligence    17      1 entry       4d ago           │
-  │ marketing       4       2 entries     today            │
-  │ website         10      1 entry       5d ago           │
-  └────────────────────────────────────────────────────────┘
-```
-
-## Traditional Hiring vs AI Workforce
-
-| | Traditional Team | AI Workforce (squads-cli) |
-|---|---|---|
-| **Cost** | $1M+/year for a small team | API calls ($50-500/month) |
-| **Availability** | 8 hours/day, 5 days/week | 24/7, including weekends |
-| **Scale** | Hire, train, onboard (months) | Add a markdown file (minutes) |
-| **Ownership** | Vendor contracts, platforms | Your agents, your data, your system |
-| **Memory** | Tribal knowledge, Notion docs | Persistent state across sessions |
+# squads
 
-## Why squads-cli?
+**Your AI workforce**
 
-| 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 |
+One person + AI teammates = a real business.
 
-**Works with:** Claude Code, Cursor, Aider, Gemini, GitHub Copilot, and more.
+[![npm version](https://img.shields.io/npm/v/squads-cli.svg)](https://www.npmjs.com/package/squads-cli)
+[![npm downloads](https://img.shields.io/npm/dw/squads-cli.svg)](https://www.npmjs.com/package/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.svg)](https://nodejs.org)
+[![GitHub stars](https://img.shields.io/github/stars/agents-squads/squads-cli?style=social)](https://github.com/agents-squads/squads-cli)
 
-## Key Features
+[Documentation](https://agents-squads.com/docs) · [Getting Started](https://agents-squads.com/onboarding) · [Architecture](https://agents-squads.com/engineering/squads-architecture)
 
-- **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
-- **Hooks** — Inject context at session start, sync memory at session end
-- **Stack** — Optional local infrastructure for telemetry and cost tracking
+</div>
 
-No complex infrastructure. Just markdown files and a CLI.
+---
 
-## Installation
+Squads organizes AI agents into domain-aligned teams -- marketing, engineering, finance, operations -- that coordinate work, remember what they learn, and track goals over time. Agents are plain markdown files. No framework lock-in, no proprietary formats. Works with any LLM provider.
 
-```bash
-npm install -g squads-cli
-```
+![squads dashboard](./assets/dashboard.png)
 
 ## Quick Start
 
 ```bash
-# Initialize in your project
+npm install -g squads-cli
 squads init
-
-# See what you have
-squads status
-
-# Full dashboard with goals and metrics
-squads dash
-
-# Run a squad
-squads run engineering
-
-# Search memory
-squads memory query "authentication"
-
-# Set a goal
-squads goal set engineering "Ship v2.0 by Friday"
-```
-
-**Expected output after `squads init`:**
-
 ```
-  squads init
-
-  ✓ Created .agents/squads/ directory
-  ✓ Created example squad: engineering
-  ✓ Created .agents/memory/ directory
-
-  Next steps:
-  $ squads status     See your new squad
-  $ squads dash       Full dashboard view
-```
-
-## Features
-
-### Dashboard
-
-View comprehensive metrics across all squads:
-
-```
-$ squads dash
-
-  squads dashboard
-  ● 7 active sessions across 1 squad (claude 7)
-
-  8/10 squads  │  404 commits  │  use -f for PRs/issues
-
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 35% goal progress
-
-  ┌──────────────────────────────────────────────────────────┐
-  │ SQUAD        COMMITS PRs ISSUES GOALS  PROGRESS          │
-  ├──────────────────────────────────────────────────────────┤
-  │ marketing    203     0   0/0    9/12   ━━━━━━━━          │
-  │ website      203     0   0/0    0/1    ━━━━━━━━          │
-  │ engineering  139     0   0/0    0/1    ━━━━━━━━          │
-  │ cli          48      0   0/0    2/3    ━━━━━━━━          │
-  └──────────────────────────────────────────────────────────┘
-
-  Git Activity (30d)
-  Last 14d: ▁▁▁▁▁▁▁▄▆▄▆▅█▂
-  404 commits  │  13.5/day  │  21 active days
-```
-
-**CEO Mode** provides an executive summary:
-
-```
-$ squads dash --ceo
-
-  squads CEO Report
-  2026-01-05
-
-  ┌─────────────────────────────────────┐
-  │ METRIC              VALUE           │
-  ├─────────────────────────────────────┤
-  │ Active Squads       8/10            │
-  │ P0 Goals            3               │
-  │ P1 Goals            5               │
-  │ Blockers            2               │
-  │ Daily Spend         $12.50 / $50    │
-  └─────────────────────────────────────┘
-
-  P0 Priorities (revenue/launch critical)
-  ✗ customer Generate first consulting revenue
-  ✗ website Launch public website
-```
-
-### Memory Search
-
-```
-$ squads memory query "telemetry"
-
-  squads memory query "telemetry"
-
-  5 results found
-
-  ┌──────────────────────────────────────────────────┐
-  │ LOCATION                    TYPE      SCORE     │
-  ├──────────────────────────────────────────────────┤
-  │ cli/cli-lead                state     7.2       │
-  │ engineering/eng-lead        state     7.2       │
-  │ marketing/marketing-lead    state     7.2       │
-  └──────────────────────────────────────────────────┘
-
-  Matches
-  ◇ Telemetry pipeline COMPLETE. Dashboard showing real-time...
-    └ cli/cli-lead
-```
-
-### Session Detection
-
-Real-time detection of running AI coding assistants:
 
 ```
 $ squads status
 
-  ● 7 active sessions across 1 squad (claude 7)
-```
-
-Supports multiple tools:
-- Claude Code
-- Cursor
-- Aider
-- Gemini
-- GitHub Copilot
-- Sourcegraph Cody
-- Continue
-
-### Stack Management
-
-Local Docker infrastructure for telemetry and memory:
-
-```
-$ squads stack health
-
-  squads stack health
-
-  ✓ postgres   healthy
-  ✓ redis      healthy
-  ✓ neo4j      healthy
-  ✓ bridge     healthy
-  ✓ langfuse   healthy
-  ✓ mem0       healthy
-  ✓ engram     healthy
-
-  ● 8/8 services healthy
-```
-
-**Valid services for `squads stack logs`:**
-- `postgres` - PostgreSQL database
-- `redis` - Redis cache
-- `neo4j` - Graph database
-- `bridge` - Conversation capture API
-- `langfuse` - Telemetry dashboard
-- `mem0` - Memory extraction
-- `engram` - Memory MCP server
-- `otel` - OpenTelemetry collector
-
-### Auto-Update
-
-```
-$ squads status
-
-  ⬆ Update available: 0.1.2 → 0.2.0 (run `squads update`)
-
-$ squads update
-  Checking npm registry...
-  ⬆ Update available: 0.1.2 → 0.2.0
-  Update now? [y/N]: y
-  Installing update...
-  ● Updated to 0.2.0
-```
-
-### Agent History
-
-Track and review agent execution history with costs and performance metrics:
-
-```
-$ squads history
-
-  squads history
-
-  Last 7 days of agent executions
-
-  ┌────────────────────────────────────────────────────────────┐
-  │ TIMESTAMP          SQUAD        AGENT       COST    STATUS │
-  ├────────────────────────────────────────────────────────────┤
-  │ 2026-01-06 10:30   engineering  ci-lead     $0.45  ✓      │
-  │ 2026-01-06 09:15   website      seo-critic  $0.23  ✓      │
-  │ 2026-01-05 16:20   customer     lead        $0.89  ✓      │
-  └────────────────────────────────────────────────────────────┘
-
-  Total cost: $1.57  │  3 executions
-```
-
-Filter by squad and get detailed metrics:
-
-```bash
-squads history -s engineering -v    # Verbose with token details
-squads history -d 30 -j             # Last 30 days, JSON output
-```
-
-### Context Feed
-
-Get curated context for agents based on goals, memory, and recent activity:
-
-```bash
-# Human-readable summary
-squads context -s engineering
-
-# JSON for agent consumption
-squads context -s engineering --json
-
-# Search memory for specific topic
-squads context -t "authentication" -s website
-```
-
-Perfect for injecting relevant context into agent prompts or hooks.
-
-### Live Monitoring
-
-**Watch Mode** — Refresh any command in real-time:
-
-```bash
-squads watch status              # Refresh every 2 seconds
-squads watch "dash --ceo" -n 5   # Custom interval
-```
-
-**Live Dashboard** — Interactive TUI like htop:
-
-```bash
-squads live                      # Full dashboard
-```
-
-**Process Table** — Real-time process monitoring:
-
-```bash
-squads top                       # Live process table
-```
-
-### Infrastructure Health
-
-Quick health check across all services without verbose Docker output:
-
-```
-$ squads health
-
-  squads health
-
-  ✓ postgres   healthy
-  ✓ redis      healthy
-  ✓ bridge     healthy
-  ✓ langfuse   healthy
-
-  ● 4/4 core services healthy
-```
-
-Use `-v` to see logs for failing services.
-
-## Core Concepts
-
-### Squads = Domain-Aligned Teams
-
-```
-.agents/squads/
-├── engineering/
-│   ├── SQUAD.md           # Squad config + goals
-│   └── ci-optimizer.md    # Agent definition
-├── research/
-│   ├── SQUAD.md
-│   └── market-analyst.md
-└── intelligence/
-    └── ...
-```
-
-### Agents = Markdown Prompts
-
-```markdown
-# CI Optimizer
-
-## Purpose
-Reduce build times and optimize CI/CD pipelines.
-
-## Model
-claude-sonnet-4
-
-## Tools
-- Bash(gh:*, git:*)
-- Read
-- Edit
-
-## Instructions
-1. Analyze current build configuration
-2. Identify slow steps
-3. Implement caching strategies
-4. Verify improvements
-```
-
-### Memory = Cross-Session State
-
-Memory files are stored at `.agents/memory/<squad>/<agent>/<type>.md`:
-
-```
-.agents/memory/
-├── engineering/
-│   └── eng-lead/
-│       ├── state.md       # Current state
-│       ├── learnings.md   # Accumulated insights
-│       └── feedback.md    # Execution feedback
-└── research/
-    └── analyst/
-        └── state.md
-```
-
-```bash
-# Agents accumulate knowledge
-squads memory show engineering
-# → "Switched to pnpm for faster installs"
-# → "Build cache reduced CI time by 40%"
-
-# Search across all squads
-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:
-
-```bash
-# Set a goal with metrics
-squads goal set finance "Reduce monthly costs by 20%" --metric "cost_usd" --metric "savings_pct"
-
-# View goals with progress
-squads goal list
-
-  finance
-  ● [1] Reduce monthly costs by 20%
-    └ Current: $450/mo, target: $400/mo
-```
-
-### Learning Extraction
-
-Extract learnings from recent conversations and store in Engram:
-
-```bash
-# Extract memories from last 24 hours
-squads memory extract
-
-# Preview without storing
-squads memory extract --dry-run
-
-# Extract from specific time window
-squads memory extract --hours 48
-```
-
-## Commands
-
-### Initialization
-
-```bash
-squads init                   # Initialize project with default template
-squads init -t minimal        # Use minimal template
-```
-
-### Status & Dashboard
-
-```bash
-squads status                 # All squads overview
-squads status engineering     # Single squad details
-squads status -v              # Verbose with agent list
-
-squads dash                   # Full dashboard with goals (fast mode)
-squads dash -f                # Include GitHub PR/issue stats (~30s slower)
-squads dash --ceo             # Executive summary with priorities and blockers
-squads dash -v                # Additional details
-```
-
-### Running Agents
-
-```bash
-squads run engineering                # Run the whole squad
-squads run engineering/ci-optimizer   # Run specific agent (slash notation)
-squads run engineering -a ci-optimizer # Run specific agent (flag notation)
-squads run engineering --dry-run      # Preview what would run
-squads run engineering --execute      # Execute via Claude CLI
-squads run engineering --parallel     # Run all agents in parallel
-squads run engineering --lead         # Lead mode: single orchestrator with Task agents
-squads run engineering --foreground   # Run in foreground (no tmux)
-squads run engineering --timeout 60   # Set timeout in minutes (default: 30)
-```
-
-### Memory Management
-
-```bash
-# Query (semantic search across markdown files)
-squads memory query "deployment"       # Search all memory
-squads memory query "auth" -s website  # Filter by squad
-squads memory query "cache" -a lead    # Filter by agent
-
-# View
-squads memory show research            # View squad memory
-squads memory list                     # List all entries
-
-# Update
-squads memory update cli "Fixed telemetry bug"           # Add to learnings
-squads memory update cli "State: ready" -t state         # Update state
-squads memory update cli "Good" -a cli-lead -t feedback  # Add feedback
-
-# Sync (git-based)
-squads memory sync                     # Pull remote, process commits
-squads memory sync -v                  # Verbose output
-squads memory sync -p                  # Push local changes after sync
-squads memory sync --no-pull           # Skip pulling from remote
-
-# Search (postgres via squads-bridge)
-squads memory search "authentication"         # Search stored conversations
-squads memory search "error" -l 20            # Limit results
-squads memory search "api" -r user            # Filter by role (user/assistant/thinking)
-squads memory search "bug" -i high            # Filter by importance (low/normal/high)
-
-# Extract (conversations → Engram memories)
-squads memory extract                  # Extract from last 24h
-squads memory extract -h 48            # Extract from last 48h
-squads memory extract -s abc123        # Extract specific session
-squads memory extract -d               # Dry run (preview only)
-```
-
-### Execution History
-
-View and analyze past agent executions:
-
-```bash
-$ squads exec list
+  squads status
+  ● 3 active sessions across 2 squads (claude 2, gemini 1)
 
-  squads exec list
+  4/4 squads  |  memory: enabled
 
-  ┌────────────────────────────────────────────────────────────────────────────────────┐
-  │ AGENT                 STATUS      DURATION  TIME          ID                       │
-  ├────────────────────────────────────────────────────────────────────────────────────┤
-  │ cli/code-eval         ● completed 5m 30s    2h ago        exec_abc123_xyz          │
-  │ website/web-lead      ◆ running   —         3h ago        exec_def456_abc          │
-  └────────────────────────────────────────────────────────────────────────────────────┘
+  SQUAD           AGENTS  MEMORY        ACTIVITY
+  engineering     3       4 entries     today
+  marketing       2       2 entries     today
+  research        5       1 entry       yesterday
+  operations      2       --            3d ago
 ```
 
 ```bash
-squads exec list                     # Recent executions
-squads exec list --squad cli         # Filter by squad
-squads exec list --status completed  # Filter by status
-squads exec show <id>                # Execution details
-squads exec stats                    # Statistics across all executions
-squads exec --json                   # JSON output for programmatic access
-```
+# Run a specific agent
+squads run engineering/code-review
 
-### Goal Tracking
+# Run an entire squad in parallel
+squads run engineering --parallel
 
-```bash
-squads goal set finance "Cut costs 20%"              # Set goal
-squads goal set finance "Track API usage" -m "api_calls" -m "cost_usd"  # With metrics
-squads goal list                                      # View all active goals
-squads goal list -a                                   # Include completed goals
-squads goal list finance                              # View goals for one squad
-squads goal progress finance 1 "Reduced to $400/mo"   # Update progress (index, text)
-squads goal complete finance 1                        # Mark done (by index)
-```
+# Search across all agent memory
+squads memory query "authentication patterns"
 
-### Feedback Loop
-
-```bash
-squads feedback add research 4 "Good analysis"        # Rate 1-5 with comment
-squads feedback add cli 5 "Excellent" -l "Cache key insight"  # With learning
-squads feedback show research                         # View history
-squads feedback show research -n 10                   # Show more entries
-squads feedback stats                                 # Summary across all squads
+# Set and track goals
+squads goal set engineering "Ship v2.0 by Friday"
+squads dash
 ```
 
-### Learnings
+## Why Squads
 
-```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
-```
+**Agents are markdown files.** No DSLs, no YAML pipelines, no SDKs. A squad is a directory. An agent is a `.md` file with a role, model preference, and instructions. You own everything -- version it, edit it, fork it.
 
-### Session Management
+**Multi-provider by default.** Route agents to the right model for the job. Claude for deep reasoning, Gemini for speed, GPT-4o for breadth, Ollama for local execution. Switch providers per agent or per run with a single flag.
 
-```bash
-# List sessions
-squads sessions                        # Show active sessions
-squads sessions -v                     # With session details
-squads sessions -j                     # JSON output
-
-# History
-squads sessions history                # Last 7 days
-squads sessions history -d 30          # Last 30 days
-squads sessions history -s website     # Filter by squad
-squads sessions history -j             # JSON output
-
-# Summary
-squads sessions summary                # Auto-detect current session
-squads sessions summary -f data.json   # From JSON file
-squads sessions summary -j             # Output as JSON
-
-# Lifecycle (for hooks/automation)
-squads session start                   # Register new session
-squads session start -s engineering    # Override squad detection
-squads session start -q                # Quiet mode
-squads session stop                    # End current session
-squads session stop -q                 # Quiet mode
-squads session heartbeat               # Update session activity
-squads session heartbeat -q            # Quiet mode
-
-# Detection
-squads detect-squad                    # Detect current squad from cwd
-```
+**Memory that persists.** Agents accumulate knowledge across sessions. Learnings survive restarts, context carries forward, and any agent can search the collective memory of the organization.
 
-### Progress Tracking
+**Goals, not just tasks.** Set objectives at the squad level, track progress through KPIs, and get executive summaries. Squads is a business operating system, not a script runner.
 
-```bash
-squads progress                        # Show active/completed tasks
-squads progress -v                     # More activity details
-squads progress start engineering "Fixing CI"   # Register task
-squads progress complete abc123        # Mark task completed
-squads progress complete abc123 -f     # Mark as failed
-```
+## Supported Providers
 
-### Results & KPIs
+| Provider | CLI | Models |
+|----------|-----|--------|
+| Anthropic | `claude` | Opus, Sonnet, Haiku |
+| Google | `gemini` | Gemini 2.5 Flash, Pro |
+| OpenAI | `codex` | GPT-4o, o1, o3 |
+| Mistral | `vibe` | Large, Medium |
+| xAI | `grok` | Grok |
+| Aider | `aider` | Multi-model |
+| Ollama | `ollama` | Any local model |
 
 ```bash
-squads results                         # All squads, last 7 days
-squads results engineering             # Single squad
-squads results -d 30                   # Last 30 days
-squads results -v                      # Detailed KPIs per goal
-```
+# Use a specific provider for a run
+squads run research --provider=google --model=gemini-2.5-flash
 
-### Workers
-
-```bash
-squads workers                         # Show Claude sessions, tasks, dev servers
-squads workers -v                      # More details
-squads workers -k 12345                # Kill process by PID
+# Check which providers are available
+squads providers
 ```
 
-### Issues Management
+## Features
 
-```bash
-# View issues
-squads issues                          # Show GitHub issues
-squads issues -o my-org                # Different organization
-squads issues -r repo1,repo2           # Specific repos
-
-# Solve issues (create PRs)
-squads solve-issues                    # Solve ready-to-fix issues
-squads solve-issues -r hq              # Target specific repo
-squads solve-issues -i 123             # Solve specific issue
-squads solve-issues -d                 # Dry run
-squads solve-issues -e                 # Execute with Claude CLI
-
-# Open issues (run evaluators)
-squads open-issues                     # Find new issues via evaluators
-squads open-issues -s website          # Target squad
-squads open-issues -a seo-critic       # Specific evaluator
-squads open-issues -d                  # Dry run
-squads open-issues -e                  # Execute with Claude CLI
-```
+### Dashboard
 
-### Stack Management
+Full visibility into squad activity, goal progress, and git contribution metrics.
 
-```bash
-# Setup
-squads stack init                      # Interactive setup wizard
-
-# Status
-squads stack status                    # Container health overview
-squads stack health                    # Comprehensive diagnostics
-squads stack health -v                 # Show logs for unhealthy services
-squads stack env                       # Print export commands
-
-# Control
-squads stack up                        # Start Docker containers
-squads stack down                      # Stop Docker containers
-squads stack logs bridge               # View container logs
-squads stack logs postgres -n 100      # Last 100 lines
 ```
+$ squads dash
 
-### Tonight Mode (Autonomous Execution)
-
-Run agents autonomously overnight with safety guardrails:
-
-```bash
-# Run intelligence squad overnight
-squads tonight intelligence
-
-# Multiple targets with cost cap
-squads tonight intelligence customer/outreach --cost-cap 25
-
-# Preview what would run
-squads tonight engineering --dry-run
-
-# Check status while running
-squads tonight status
+  squads dashboard
+  ● 7 active sessions across 3 squads
 
-# Stop all overnight agents
-squads tonight stop
+  8/10 squads  |  404 commits  |  use -f for PRs/issues
 
-# View the morning report
-squads tonight report
-```
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 35% goal progress
 
-**Example output:**
+  SQUAD        COMMITS PRs ISSUES GOALS  PROGRESS
+  marketing    203     0   0/0    9/12   ━━━━━━━━
+  engineering  139     0   0/0    0/1    ━━━━━━━━
+  cli          48      0   0/0    2/3    ━━━━━━━━
 
+  Git Activity (30d)
+  Last 14d: ▁▁▁▁▁▁▁▄▆▄▆▅█▂
+  404 commits  |  13.5/day  |  21 active days
 ```
-$ squads tonight intelligence customer/outreach
-
-  squads tonight
-
-  Config:
-    Cost cap:    $50
-    Stop at:     07:00
-    Max retries: 3
-    Targets:     intelligence, customer/outreach
 
-  ✓ Launched 2 agent(s)
+The `--ceo` flag produces an executive summary with P0/P1 priorities and spend tracking.
 
-  ✓ Tonight mode active
+### Memory System
 
-  Monitor:
-    squads tonight status  - Check progress
-    squads tonight stop    - Kill all agents
-    tmux ls | grep tonight - List sessions
-
-  Logs: .agents/outputs/tonight/
-```
-
-**Safety features:**
-- **Cost cap** — Automatically stops when spending limit reached (default: $50)
-- **Time limit** — Stops at specified time (default: 7:00 AM)
-- **Max retries** — Limits restart attempts for crashed agents (default: 3)
-- **Session isolation** — Each agent runs in isolated tmux session
-- **Logging** — All output captured to `.agents/outputs/tonight/`
-- **Morning report** — Summary generated on completion
-
-**Monitoring commands:**
+Agents write learnings as they work. The memory system makes that knowledge searchable and shareable across the organization.
 
 ```bash
-# Check current status
-squads tonight status
-
-# Attach to a running session
-tmux attach -t squads-tonight-intelligence-...
+# Capture a learning from the command line
+squads memory write engineering "Redis connection pooling requires min 5 connections for our load"
 
-# View live logs
-tail -f .agents/outputs/tonight/*.log
+# Search all agent memory
+squads memory query "deployment"
 
-# Stop everything immediately
-squads tonight stop
+# View a specific squad's accumulated knowledge
+squads memory read engineering
 ```
 
-> **Warning**: Tonight mode uses `--dangerously-skip-permissions` which bypasses
-> Claude's safety confirmations. Only use with trusted agent definitions. Review
-> your agent prompts and ensure they have appropriate scope limits before running
-> autonomously.
-
-### Smart Triggers
-
-Triggers execute agents based on conditions in PostgreSQL:
+### Session Detection
 
-```bash
-squads trigger list                    # View all triggers
-squads trigger list engineering        # Filter by squad
-squads trigger sync                    # Sync SQUAD.md → Postgres
-squads trigger fire cost-alert         # Manually fire a trigger
-squads trigger enable cost-alert       # Enable a trigger
-squads trigger disable cost-alert      # Disable a trigger
-squads trigger status                  # Scheduler health & stats
-```
+Automatically detects running AI coding sessions across your machine and maps them to squads based on working directory.
 
-**Trigger definition in SQUAD.md:**
-
-```yaml
-triggers:
-  - name: cost-alert
-    agent: cost-tracker
-    condition: |
-      SELECT value > 100
-      FROM latest_metrics
-      WHERE name = 'daily_cost_usd'
-    cooldown: 6 hours
-    priority: 3
 ```
+$ squads sessions
 
-### List & Discovery
-
-```bash
-squads list                            # List all squads and agents
-squads list -s                         # Squads only
-squads list -a                         # Agents only
+  ● 4 active sessions
+  claude  engineering/backend    ~/projects/api         12m
+  claude  engineering/frontend   ~/projects/web         3m
+  gemini  research/analyst       ~/projects/research    45m
+  cursor  marketing/content      ~/projects/site        8m
 ```
 
-### Authentication (Pro & Enterprise)
+Supports: Claude Code, Cursor, Aider, Gemini, GitHub Copilot, Sourcegraph Cody, Continue.
 
-```bash
-squads login                           # Log in to Squads cloud
-squads logout                          # Log out
-squads whoami                          # Show current user
-```
+### Autonomous Execution
 
-### Updates
+Schedule agents to run on their own with the local daemon.
 
 ```bash
-squads update                          # Interactive update
-squads update -y                       # Auto-confirm
-squads update -c                       # Check only, don't install
-```
-
-## Command Reference
+# Start the autonomous scheduler
+squads autonomous start
 
+# Check what's running
+squads autonomous status
 ```
-squads init                          Initialize project
-  -t, --template <template>          Project template (default)
-
-squads status [squad]                Show squad status
-  -v, --verbose                      Include agent details
-
-squads dash                          Full dashboard with goals
-  -v, --verbose                      Show additional details
-  -c, --ceo                          Executive summary with priorities
-  -f, --full                         Include GitHub PR/issue stats (~30s)
-
-squads run <target>                  Run squad or agent
-  -v, --verbose                      Verbose output
-  -d, --dry-run                      Preview only
-  -e, --execute                      Execute via Claude CLI
-  -a, --agent <agent>                Run specific agent within squad
-  -t, --timeout <minutes>            Execution timeout (default: 30)
-  -p, --parallel                     Run all agents in parallel
-  -l, --lead                         Lead mode: single orchestrator using Task tool
-  -f, --foreground                   Run in foreground (no tmux)
-
-squads list                          List all squads/agents
-  -s, --squads                       Squads only
-  -a, --agents                       Agents only
-
-squads memory query <query>          Search memory
-  -s, --squad <squad>                Filter by squad
-  -a, --agent <agent>                Filter by agent
-squads memory show <squad>           View squad memory
-squads memory update <squad> <text>  Add to memory
-  -a, --agent <agent>                Specific agent (default: squad-lead)
-  -t, --type <type>                  Memory type: state, learnings, feedback
-squads memory list                   List all entries
-squads memory sync                   Sync from git
-  -v, --verbose                      Detailed output
-  -p, --push                         Push after sync
-  --no-pull                          Skip pulling
-squads memory search <query>         Search postgres conversations
-  -l, --limit <n>                    Number of results (default: 10)
-  -r, --role <role>                  Filter: user, assistant, thinking
-  -i, --importance <level>           Filter: low, normal, high
-squads memory extract                Extract memories to Engram
-  -s, --session <id>                 Specific session
-  -h, --hours <n>                    Hours to look back (default: 24)
-  -d, --dry-run                      Preview only
-
-squads goal set <squad> <goal>       Set a goal
-  -m, --metric <metrics...>          Metrics to track
-squads goal list [squad]             List goals
-  -a, --all                          Include completed
-squads goal progress <squad> <idx> <text>  Update progress
-squads goal complete <squad> <idx>   Mark completed
-
-squads feedback add <squad> <1-5> <text>  Rate execution
-  -l, --learning <learnings...>      Extract learnings
-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
-squads sessions history              Session history
-  -d, --days <n>                     Days of history (default: 7)
-  -s, --squad <squad>                Filter by squad
-  -j, --json                         JSON output
-squads sessions summary              Pretty session summary
-  -d, --data <json>                  JSON data
-  -f, --file <path>                  JSON file path
-  -j, --json                         JSON output
-
-squads session start                 Register session
-  -s, --squad <squad>                Override detection
-  -q, --quiet                        Suppress output
-squads session stop                  End session
-  -q, --quiet                        Suppress output
-squads session heartbeat             Update activity
-  -q, --quiet                        Suppress output
-
-squads detect-squad                  Detect squad from cwd
-
-squads progress                      Show task progress
-  -v, --verbose                      More details
-squads progress start <squad> <desc> Register task
-squads progress complete <id>        Mark completed
-  -f, --failed                       Mark as failed
-
-squads results [squad]               KPI goals vs actuals
-  -d, --days <n>                     Days to look back (default: 7)
-  -v, --verbose                      Detailed KPIs
-
-squads workers                       Show active workers
-  -v, --verbose                      More details
-  -k, --kill <pid>                   Kill process
-
-squads context                       Business context for alignment
-  -s, --squad <squad>                Focus on specific squad
-  -t, --topic <topic>                Search memory for relevant context
-  -v, --verbose                      Show additional details
-  --json                             JSON output
-
-squads history                       Recent agent execution history
-  -d, --days <n>                     Days to look back (default: 7)
-  -s, --squad <squad>                Filter by squad
-  -v, --verbose                      Show cost and token details
-  -j, --json                         JSON output
-
-squads health                        Quick infrastructure health check
-  -v, --verbose                      Show logs for failures
-  --json                             JSON output
-
-squads watch <command> [args]        Live refresh any command (like Unix watch)
-  -n, --interval <seconds>           Refresh interval (default: 2)
-
-squads live                          Live TUI dashboard (like htop)
-  -r, --refresh <ms>                 Refresh rate (default: 1000)
-
-squads top                           Live process table (like Unix top)
-
-squads version                       Show version information
-
-squads env show <squad>              Squad execution environment (MCP, model, budget)
-  --json                             JSON output
-squads env list                      List all squad environments
-  --json                             JSON output
-
-squads cost                          Cost summary (today, week, by squad)
-  -s, --squad <squad>                Filter to specific squad
-  --json                             JSON output
-
-squads budget <squad>                Check budget status for a squad
-  --json                             JSON output
-
-squads issues                        GitHub issues
-  -o, --org <org>                    Organization (default: agents-squads)
-  -r, --repos <repos>                Comma-separated repos
-
-squads solve-issues                  Solve issues with PRs
-  -r, --repo <repo>                  Target repo
-  -i, --issue <number>               Specific issue
-  -d, --dry-run                      Preview only
-  -e, --execute                      Execute with Claude
-
-squads open-issues                   Find new issues
-  -s, --squad <squad>                Target squad
-  -a, --agent <agent>                Evaluator agent
-  -d, --dry-run                      Preview only
-  -e, --execute                      Execute with Claude
-
-squads stack init                    Setup wizard
-squads stack status                  Container health
-squads stack health                  Full diagnostics
-  -v, --verbose                      Show logs for failures
-squads stack env                     Print exports
-squads stack up                      Start containers
-squads stack down                    Stop containers
-squads stack logs <service>          View logs
-  -n, --tail <lines>                 Lines to show (default: 50)
-
-squads trigger list [squad]          List triggers
-squads trigger sync                  Sync to scheduler
-squads trigger fire <name>           Fire trigger
-squads trigger enable <name>         Enable trigger
-squads trigger disable <name>        Disable trigger
-squads trigger status                Scheduler stats
-
-squads exec list                     List recent executions
-  -s, --squad <squad>                Filter by squad
-  -a, --agent <agent>                Filter by agent
-  --status <status>                  Filter: running, completed, failed
-  -n, --limit <n>                    Results to show (default: 20)
-  --json                             JSON output
-squads exec show <id>                Execution details
-  --json                             JSON output
-squads exec stats                    Execution statistics
-  -s, --squad <squad>                Filter by squad
-  --json                             JSON output
-
-squads tonight <targets...>          Autonomous overnight execution
-  --cost-cap <usd>                   Max spend (default: $50)
-  --stop-at <time>                   Stop time HH:MM (default: 07:00)
-  --max-retries <n>                  Restart limit (default: 3)
-  -d, --dry-run                      Preview only
-  -v, --verbose                      Verbose output
-squads tonight status                Check progress
-squads tonight stop                  Kill all agents
-squads tonight report                View morning report
-
-squads cron sync                     Sync agent schedules to launchd (macOS)
-squads cron list [squad]             List scheduled agents
-squads cron status                   Show launchd status and next runs
-squads cron enable <agent>           Enable an agent's schedule
-squads cron disable <agent>          Disable an agent's schedule
-squads cron logs [agent]             Show execution logs
-
-squads approval send <type>          Send approval request to Slack
-squads approval list                 List pending approvals
-squads approval check <id>           Check approval status
-squads approval cancel <id>          Cancel pending approval
-
-squads orchestrate <squad>           Run squad with lead agent orchestration
-  -f, --foreground                   Run in foreground (no tmux)
-
-squads skill list                    List uploaded skills
-squads skill upload <path>           Upload skill directory to Anthropic API
-squads skill delete <id>             Delete a skill
-squads skill show <id>               Show skill details
-squads skill convert <agent>         Convert agent.md to SKILL.md format
-
-squads permissions show <squad>      Show permission context for a squad
-squads permissions check <squad>     Validate permissions before execution
-  -a, --agent <agent>                Specify agent for context
-
-squads slack sync                    Sync squad channels with Slack
-squads slack channels                List Slack channels
-squads slack test                    Test Slack connection
-
-squads providers                     Show available LLM CLI providers
-  --json                             JSON output
-
-squads autonomy                      Show autonomy score and confidence metrics
-  -s, --squad <squad>                Filter by squad
-  -p, --period <period>              Period: today, week, month
-  --json                             JSON output
-
-squads kpi show <squad>              Show KPI status for a squad
-squads kpi record <squad> <kpi> <value>  Record KPI value
-squads kpi trend <squad> <kpi>       Show KPI trend over time
-squads kpi insights <squad>          Generate AI insights from KPIs
-  --json                             JSON output
-
-squads update                        Interactive update
-  -y, --yes                          Auto-confirm
-  -c, --check                        Check only
-
-squads login                         Log in (Pro)
-squads logout                        Log out
-squads whoami                        Show user
-```
-
-## Claude Code Integration
 
-For comprehensive documentation on hooks and skills, see the **[Hooks and Skills Guide](https://agents-squads.com/engineering/hooks-and-skills)**.
+### Claude Code Integration
 
-### Option 1: Session Hooks (Recommended)
-
-Add to `.claude/settings.json`:
+Add hooks to `.claude/settings.json` so every Claude Code session starts with squad context:
 
 ```json
 {
@@ -1098,185 +170,153 @@ Add to `.claude/settings.json`:
     "SessionStart": [{
       "hooks": [{
         "type": "command",
-        "command": "squads status",
+        "command": "squads session start",
         "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 status injected
-- **Ends** with memory synced and a prompt to capture learnings
-
-### Option 2: CLAUDE.md Instructions
-
-```markdown
-## Squads Workflow
+## Commands
 
-Before starting work:
-1. Run `squads status` to see current state
-2. Run `squads memory query "<topic>"` to check existing knowledge
-3. After completing work, update memory via state files
-```
+| Command | Description |
+|---------|-------------|
+| `squads init` | Initialize squads in your project |
+| `squads status [squad]` | Overview of all squads and active sessions |
+| `squads run <target>` | Run a squad or specific agent |
+| `squads dash [name]` | Dashboard with goals, metrics, and git activity |
+| `squads env show <squad>` | View squad execution environment |
+| `squads env prompt <squad> -a <agent>` | Generate agent execution prompt |
+| `squads memory query <q>` | Search across all agent memory |
+| `squads memory write <squad> <insight>` | Persist a learning |
+| `squads memory read <squad>` | View squad memory |
+| `squads goal set <squad> <goal>` | Set a squad objective |
+| `squads goal list` | View all goals and progress |
+| `squads exec list` | View recent execution history |
+| `squads sessions` | Show active AI coding sessions |
+| `squads autonomous start` | Start the local execution daemon |
+| `squads providers` | List available LLM providers |
+| `squads eval <target>` | Evaluate agent readiness |
+| `squads cost` | Cost summary by squad and time period |
+| `squads kpi show <squad>` | Track squad KPIs |
+| `squads sync` | Synchronize memory state |
+| `squads health` | Infrastructure health check |
+| `squads update` | Check for and install updates |
+
+Run `squads --help` for the full command reference, or `squads <command> --help` for detailed options.
 
 ## Project Structure
 
+After `squads init`, your project gets a `.agents/` directory:
+
 ```
 your-project/
 ├── .agents/
-│   ├── squads/              # Squad definitions
+│   ├── squads/                  # Squad definitions
 │   │   ├── engineering/
-│   │   │   ├── SQUAD.md     # Config + goals
-│   │   │   └── *.md         # Agent definitions
-│   │   └── research/
-│   ├── memory/              # Persistent state
+│   │   │   ├── SQUAD.md         # Squad config, goals, KPIs
+│   │   │   ├── code-review.md   # Agent: role, model, instructions
+│   │   │   └── backend.md       # Agent: another team member
+│   │   └── marketing/
+│   │       ├── SQUAD.md
+│   │       └── content.md
+│   ├── memory/                  # Persistent state (auto-managed)
 │   │   ├── engineering/
-│   │   │   └── eng-lead/
-│   │   │       ├── state.md
-│   │   │       ├── learnings.md
-│   │   │       └── feedback.md
-│   │   └── research/
-│   ├── outputs/             # Agent outputs
-│   └── sessions/
-│       └── history.jsonl    # Session event log
-├── .claude/
-│   └── settings.json        # Hooks config
-└── CLAUDE.md                # Project instructions
+│   │   └── marketing/
+│   └── outputs/                 # Agent work products
+└── CLAUDE.md                    # Optional: project-level AI context
 ```
 
-## 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
+Everything is plain text. Version it with git, review it in PRs, edit it in any editor.
 
-   # Or configure external services
-   export LANGFUSE_HOST=https://your-langfuse.com
-   export LANGFUSE_PUBLIC_KEY=pk-...
-   export LANGFUSE_SECRET_KEY=sk-...
-   ```
+## Configuration
 
-3. **View in dashboard:**
-   ```bash
-   squads dash
-   ```
+### Agent Definition
 
-### Metrics Tracked
+Each agent is a markdown file with YAML frontmatter:
 
-- Token usage (input/output/cache)
-- API costs per squad/agent
-- Rate limit status
-- Generation counts
-
-## Infrastructure
-
-Optional services that enhance squad capabilities.
-
-### Services
+```markdown
+---
+model: sonnet
+provider: anthropic
+effort: high
+timeout: 30
+---
 
-| Service | Purpose |
-|---------|---------|
-| postgres | Session storage, trigger conditions |
-| redis | Caching, rate limiting |
-| otel | OpenTelemetry metrics pipeline |
-| langfuse | Telemetry dashboard |
-| bridge | Conversation capture API |
+# Code Review Agent
 
-### Self-Hosted Setup
+You review pull requests for correctness, security, and style.
 
-```bash
-# Clone the infrastructure
-git clone https://github.com/agents-squads/squads-infra
-cd squads-infra
+## Instructions
+- Check for common vulnerability patterns
+- Verify test coverage for new code paths
+- Flag any breaking API changes
+```
 
-# Start services
-docker-compose up -d
+### Squad Definition
 
-# Configure CLI
-squads stack env >> ~/.zshrc
-source ~/.zshrc
+`SQUAD.md` configures the team:
 
-# Verify
-squads stack health
-```
+```markdown
+---
+agents:
+  - code-review
+  - backend
+  - frontend
+model: sonnet
+provider: anthropic
+---
 
-### Minimal Setup (Postgres only)
+# Engineering Squad
 
-```bash
-# Just need triggers and session storage
-docker run -d --name squads-postgres \
-  -e POSTGRES_PASSWORD=squads \
-  -p 5432:5432 \
-  postgres:16
+Owns the codebase. Ships features, fixes bugs, maintains quality.
 
-export SQUADS_POSTGRES_URL=postgres://postgres:squads@localhost:5432/squads
+## Goals
+- P0: Ship v2.0 release
+- P1: Reduce CI build time below 3 minutes
 ```
 
 ## Development
 
 ```bash
-git clone https://github.com/agents-squads/squads-cli
+git clone https://github.com/agents-squads/squads-cli.git
 cd squads-cli
 npm install
 npm run build
-npm link  # Test globally
+npm link           # Makes 'squads' available globally
+npm test
 ```
 
-### Testing
+### Tech Stack
 
-```bash
-npm test              # Run tests
-npm run test:watch    # Watch mode
-npm run test:coverage # Coverage report
-```
+- **TypeScript** (strict mode) with **Commander.js** for CLI parsing
+- **Vitest** for testing
+- **tsup** for bundling
+- Built on the [Anthropic SDK](https://github.com/anthropics/anthropic-sdk-node) with multi-provider abstraction
 
-### Scripts
+## Contributing
 
-```bash
-npm run build         # Build with tsup
-npm run dev           # Watch mode
-npm run lint          # ESLint
-npm run typecheck     # TypeScript check
-```
+Contributions are welcome. Please open an issue first to discuss what you'd like to change.
 
-## Documentation & Resources
+1. Fork the repository
+2. Create your branch (`git checkout -b feature/my-feature`)
+3. Commit your changes (`git commit -m 'Add my feature'`)
+4. Push to the branch (`git push origin feature/my-feature`)
+5. Open a Pull Request
 
-**Official Documentation:**
-- 📖 [Documentation](https://agents-squads.com/docs) — Complete CLI reference and tutorials
-- 🚀 [Getting Started](https://agents-squads.com/onboarding) — Quick setup guide
-- 🏗️ [Architecture Guide](https://agents-squads.com/engineering/squads-architecture) — How squads work under the hood
-- ⚡ [Hooks and Skills](https://agents-squads.com/engineering/hooks-and-skills) — Claude Code integration patterns
-- 💰 [Cost Management](https://agents-squads.com/engineering/cost-management) — Budget tracking and optimization
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 
-**Related Repositories:**
-- [agents-squads](https://github.com/agents-squads/agents-squads) — Full framework with infrastructure
-- [engram](https://github.com/agents-squads/engram) — Persistent memory for AI agents
-- [squads-infra](https://github.com/agents-squads/squads-infra) — Docker infrastructure stack
+## Community
 
-**Research & Intelligence:**
-- [AI Agent Research](https://agents-squads.com/research) — Latest AI agent analysis
-- [Enterprise AI Report](https://agents-squads.com/intelligence/enterprise-ai-agents-2025) — Market intelligence
+- [GitHub Issues](https://github.com/agents-squads/squads-cli/issues) -- Bug reports and feature requests
+- [GitHub Discussions](https://github.com/agents-squads/squads-cli/discussions) -- Questions and ideas
+- [Documentation](https://agents-squads.com/docs) -- Guides, tutorials, and API reference
+
+## Related Projects
+
+- [agents-squads](https://github.com/agents-squads/agents-squads) -- The full framework
+- [engram](https://github.com/agents-squads/engram) -- Persistent memory for AI agents (MCP server)
 
 ## License
 
@@ -1284,4 +324,8 @@ npm run typecheck     # TypeScript check
 
 ---
 
-Built by [Agents Squads](https://agents-squads.com) — your AI workforce.
+<div align="center">
+
+Built by [Agents Squads](https://agents-squads.com)
+
+</div>