TL;DR — Agent squads are domain-organized teams of autonomous AI agents with persistent memory, goal tracking, and pipeline coordination. Squads CLI lets you define agents in markdown, orchestrate them from the terminal, and scale from a single researcher to a full multi-agent organization.
What Are AI Agent Squads?
Agent squads are teams of autonomous AI agents organized around domains—like engineering, marketing, or research. Each squad has specialized agents that execute tasks, maintain memory, and coordinate to achieve goals.
The Squads CLI (squads) orchestrates these agents on top of Claude Code, providing:
- Squad organization: Group agents by domain
- Persistent memory: Agents remember across sessions
- Goal tracking: Connect work to business objectives
- Execution management: Run agents manually or on schedule
- Status dashboards: See what your agents are doing
Let’s build your first agent squad.
Key Takeaway — Squads aren’t chatbots. They’re autonomous teams that execute tasks, remember across sessions, and coordinate toward business goals.
Quick Start: Your First Squad
Install the Squads CLI
npm install -g @anthropic/squads-cliInitialize Your Project
cd your-project
squads initThis creates the agent infrastructure:
.agents/
├── squads/
│ └── demo/
│ ├── SQUAD.md # Squad definition
│ ├── researcher.md # Agent definition
│ └── reporter.md # Agent definition
├── memory/ # Persistent memory
├── outputs/ # Agent outputs
└── config/
└── provider.yaml # AI provider configCheck Your Status
squads statussquads status
● 1 squad active
┌────────────────────────────────────────────┐
│ SQUAD AGENTS GOALS ACTIVITY │
├────────────────────────────────────────────┤
│ demo 2 0/1 just now │
└────────────────────────────────────────────┘Run Your First Agent
squads run demo --agent researcher --executeThe researcher agent will:
- Search for information about AI agent frameworks
- Save findings to
.agents/outputs/demo/research-notes.md - Update its memory with what it learned
Understanding Squad Architecture
The Squad Definition (SQUAD.md)
Every squad has a SQUAD.md file that defines its mission, agents, and goals:
---
name: research
mission: Gather competitive intelligence and market insights
repo: your-org/research
---
# Squad: Research
## Slack Channel
`#squad-research` - Research findings, competitor alerts, market updates
## Agents
| Agent | Role | Trigger |
|-------|------|---------|
| scout | Discovers new information | Daily |
| analyst | Analyzes and synthesizes | On demand |
| reporter | Creates reports | Weekly |
## Pipeline
`scout` → `analyst` → `reporter`
## Goals
- [ ] Weekly competitor brief published
- [ ] 3 market trends identified per month
- [ ] Research requests completed within 24hAgent Definitions
Each agent has its own markdown file with instructions:
# Scout Agent
## Purpose
Discover new competitive intelligence and market signals.
## Model
worker
## Tools
- WebSearch
- WebFetch
- Write
## Instructions
1. Search for news about our competitors:
- Company A: funding, product launches, hiring
- Company B: partnerships, pricing changes
- Company C: technical blog posts, open source
2. For each finding:
- Summarize in 2-3 sentences
- Rate importance (high/medium/low)
- Note the source URL
3. Save to `.agents/outputs/research/scout-findings.md`
4. If anything is HIGH importance, also save to
`.agents/outputs/research/alerts.md`
## Output
Findings saved to .agents/outputs/research/Working with Memory
Agents need memory to be effective. The Squads CLI provides persistent memory that survives across sessions.
Save Learnings
When an agent discovers something useful:
squads learn "Competitor X always announces pricing changes on Tuesdays"This saves to .agents/memory/general/shared/learnings.md and is available to all agents.
Query Memory
Search across all agent memory:
squads memory query "competitor pricing"Found 3 results:
1. [research/scout] 2026-01-15
Competitor X pricing page updated - 15% increase on enterprise tier
2. [research/analyst] 2026-01-10
Pricing analysis: market moving toward usage-based models
3. [shared] 2026-01-08
Competitor X always announces pricing changes on TuesdaysMemory Structure
.agents/memory/
├── research/ # Squad-specific memory
│ ├── scout/
│ │ ├── state.md # Current working state
│ │ ├── learnings.md # What the agent learned
│ │ └── executions.md # Execution history
│ └── analyst/
│ └── ...
└── general/
└── shared/
└── learnings.md # Cross-squad learningsImportant — Memory is what separates useful agents from demos. Without persistent context, every session starts from scratch and agents repeat the same mistakes.
Goal-Driven Execution
Agents should work toward goals, not just execute tasks. The Squads CLI tracks goals and connects agent work to outcomes.
Set Goals
squads goal set research "Publish weekly competitor brief"List Goals
squads goal listResearch Squad Goals:
● [P1] Publish weekly competitor brief
└ Due: Every Monday
└ Agent: reporter
└ Status: On track (last: 2026-01-22)
○ [P2] Identify 3 market trends monthly
└ Due: End of month
└ Agent: analyst
└ Status: 1/3 completeTrack Progress
squads goal progress research/1Shows execution history, outputs, and metrics for a goal.
Running Agents
Manual Execution
Run a specific agent:
squads run research --agent scout --executeRun the entire squad (all agents in pipeline order):
squads run research --executeScheduled Execution
Define schedules in agent frontmatter:
---
trigger: scheduled
schedule: "0 9 * * *" # Daily at 9am
---Sync schedules:
squads cron syncView scheduled agents:
squads cron listAutonomous Mode
For continuous operation:
squads autonomous start researchAgents run on their schedules, respond to triggers, and pursue goals autonomously.
Multi-Agent Coordination
Pipelines
Define agent pipelines in SQUAD.md:
## Pipeline
`scout` → `analyst` → `reporter`Run the pipeline:
squads run research --executeAgents execute in order, each using the previous agent’s output.
Triggers Between Agents
Agent A can trigger Agent B:
# Scout Agent
## Instructions
...
When you find HIGH importance items:
1. Save to alerts.md
2. Trigger the analyst: Write "ANALYZE: <topic>" to `.agents/tasks/analyst.md`Cross-Squad Coordination
Squads can share information:
# Intelligence squad discovers something relevant to marketing
squads learn --squad marketing "New competitor launched - see intelligence/alerts.md"The Dashboard
Get a complete view of your agent organization:
squads dashboard╭──────────────────────────────────────────────────────────────╮
│ AGENTS SQUADS DASHBOARD │
╰──────────────────────────────────────────────────────────────╯
SQUADS (4 active)
research 3 agents 2/3 goals ● running
engineering 5 agents 1/2 goals ○ idle
marketing 2 agents 0/1 goals ○ idle
customer 4 agents 1/1 goals ✓ complete
RECENT EXECUTIONS
10:32 research/scout ✓ Found 3 competitor updates
09:15 engineering/critic ✓ Reviewed PR #234
08:00 marketing/writer ✓ Published blog post
GOALS
[P1] research: Weekly competitor brief ● On track
[P1] engineering: Zero P1 bugs ○ 2 remaining
[P2] marketing: 3 blog posts this month ○ 1/3 complete
MEMORY
Total learnings: 47
Last sync: 2 hours agoExample: Building a Research Squad
Let’s build a complete research squad from scratch.
1. Create the Squad
mkdir -p .agents/squads/research2. Define SQUAD.md
---
name: research
mission: Gather and analyze competitive intelligence
repo: your-org/research
---
# Squad: Research
## Slack Channel
`#squad-research` - Intel alerts, research findings, weekly briefs
## Agents
| Agent | Role | Trigger |
|-------|------|---------|
| scout | Discover competitor news | Daily 9am |
| analyst | Analyze findings | After scout |
| reporter | Write weekly brief | Monday 10am |
## Pipeline
`scout` → `analyst` → `reporter`
## Goals
- [ ] Weekly competitor brief published every Monday
- [ ] Alert on major competitor moves within 4 hours
- [ ] Maintain competitor profiles with current data3. Create the Scout Agent
.agents/squads/research/scout.md:
---
trigger: scheduled
schedule: "0 9 * * *"
---
# Scout Agent
## Purpose
Discover new competitive intelligence daily.
## Tools
- WebSearch
- WebFetch
- Write
- Read
## Instructions
### Morning Scan
1. Read the competitor list from `.agents/memory/research/competitors.md`
2. For each competitor, search for:
- News in the last 24 hours
- New blog posts or documentation
- Social media announcements
- Job postings (signals growth/focus areas)
3. For each finding, create an entry:[Company] - [Date]
Type: news/product/hiring/funding Importance: high/medium/low Summary: 2-3 sentences Source: URL Action: What should we do about this?
4. Save findings to `.agents/outputs/research/scout/YYYY-MM-DD.md`
5. If HIGH importance:
- Also append to `.agents/outputs/research/alerts.md`
- The analyst will be triggered automatically
### Memory Update
After each scan, update `.agents/memory/research/scout/state.md`:
- Last scan time
- Companies scanned
- Findings count
- Any errors or gaps
## Output
Daily findings in .agents/outputs/research/scout/4. Create the Analyst Agent
.agents/squads/research/analyst.md:
# Analyst Agent
## Purpose
Analyze scout findings and extract strategic insights.
## Tools
- Read
- Write
## Instructions
### Analysis Process
1. Read today's scout findings from `.agents/outputs/research/scout/`
2. Read historical context from `.agents/memory/research/analyst/`
3. For each HIGH importance finding:
- What does this mean for us?
- How does it change the competitive landscape?
- What should we consider doing?
4. Identify patterns across findings:
- Are multiple competitors doing similar things?
- Is there a market trend emerging?
- Are we missing something they all have?
5. Write analysis to `.agents/outputs/research/analyst/YYYY-MM-DD.md`
6. Update learnings in `.agents/memory/research/analyst/learnings.md`
## Output
Daily analysis in .agents/outputs/research/analyst/5. Create the Reporter Agent
.agents/squads/research/reporter.md:
---
trigger: scheduled
schedule: "0 10 * * 1" # Monday 10am
---
# Reporter Agent
## Purpose
Write the weekly competitive intelligence brief.
## Tools
- Read
- Write
## Instructions
### Weekly Brief
1. Read all scout findings from the past week
2. Read all analyst insights from the past week
3. Read the previous brief for continuity
4. Write a brief with this structure:
```markdown
# Competitive Intelligence Brief
## Week of [Date]
### Executive Summary
- 3 bullet points max
- Most important things leadership should know
### Major Moves
For each significant competitor action:
- What happened
- Why it matters
- Recommended response
### Emerging Trends
Patterns we're seeing across the market
### Watch List
Things to monitor closely this week
### Appendix
Links to detailed findings- Save to
.agents/outputs/research/briefs/week-of-YYYY-MM-DD.md
Output
Weekly brief in .agents/outputs/research/briefs/
### 6. Run It
```bash
# Check status
squads status research
# Run the full pipeline
squads run research --execute
# Or start autonomous mode
squads autonomous start researchKey Takeaway — Define agents in markdown with purpose, tools, and instructions. No code required for basic agents — the definition file IS the agent.
Best Practices
1. Start Small
Begin with one agent doing one thing well. Add complexity as you learn what works.
2. Use Memory Liberally
The more context agents have, the better they perform. Save learnings aggressively.
3. Define Clear Outputs
Agents should write to specific locations. Other agents (and humans) should know exactly where to find their work.
4. Connect to Goals
Every agent execution should connect to a goal. If it doesn’t move a goal forward, question whether it should run.
5. Review and Iterate
Check agent outputs regularly. Update instructions based on what’s working and what isn’t.
Next Steps
You now know how to:
- Initialize a squads project
- Define squads and agents
- Use persistent memory
- Track goals
- Run agents manually and on schedule
- Coordinate multiple agents
Resources
Get Help
squads --help
squads run --help
squads memory --helpBuilding AI systems you can learn, understand, and trust. That’s Agents Squads.
