A squad is a team of AI agents — different models, different roles — working toward a shared goal with persistent memory. A lead briefs the team, workers execute, a verifier checks the output, and feedback from each cycle is injected into the next. Everything is a markdown file in a git repo: no database, no server, no DSL.

npm install -g squads-cli
squads init      # creates .agents/ with 4 starter squads
squads status
squads run research/analyst

How it works

.agents/
├── BUSINESS_BRIEF.md      # Your business context — every agent reads it
├── config/SYSTEM.md       # Immutable rules shared by all agents
├── squads/                # Identity: SQUAD.md + one .md file per agent
│   ├── intelligence/
│   ├── research/
│   ├── product/
│   └── company/           # Evaluates outputs, closes the feedback loop
└── memory/                # State: learnings, priorities, feedback

Before every run, an agent loads a context cascade — squad identity, current priorities, feedback from the last cycle, active work across the team — tuned by role so scanners stay lightweight and leads get the full picture. Agents that know what's been done don't duplicate work; agents that see their own feedback stop producing noise.

Squads shells out to native AI CLIs (claude, gemini, aider, …), so mixed-model teams work out of the box: a cheap model scans, a deep reasoning model builds, a mid-tier model verifies.

squads run research --parallel                  # squad conversation
squads run intelligence --task "Scan X"         # directed run
squads autopilot --interval 30 --budget 50      # autonomous dispatch

Documentation

Philosophy	Why squads, why CLI-first, skills + tools
Architecture	Context cascade, roles, phases, the feedback loop
Configuration	Starter squads, building your own, secrets
Running Agents	Execution modes, local limits, scaling
Commands	Reference for humans and for agents
Providers	Claude, Gemini, DeepSeek, and per-agent routing

Requirements

Node.js >= 20, Git, and Claude Code (default provider — others optional). squads doctor checks your machine.

Everything runs locally: your machine, your API keys, your data. No login, no cloud, no telemetry surprises.

Development

git clone https://github.com/agents-squads/squads-cli.git
cd squads-cli
npm install
npm run build && npm link
npm test

TypeScript (strict mode), Commander.js, Vitest, tsup.

Contributing

Contributions welcome — open an issue first to discuss changes. See CONTRIBUTING.md for guidelines, and GitHub Discussions for questions and ideas. We'd love to see what you build — share your squads and skills.

License

MIT