Run squads of AI agents from your terminal — defined in markdown, tracked in git.
Autonomous AI agents for engineering, marketing, finance, and operations. You make the decisions. They do the work.
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
mkdir my-squads && cd my-squads
git init # squads runs on git — it's the state and audit trail
squads init # scaffolds .agents/ with starter squads
squads run demo hello-world # verify your setup end to end
squads run research/analyst # your first real agentClaude Code must be installed and logged in (
claude /login) before the first run —squads doctorchecks both and tells you exactly what's missing.
What squads run demo hello-world looks like — real, unedited output:
squads run Demo
- Running agent: hello-world
Hello from hello-world, squad demo — today is 2026-07-10, and this run
confirms the my-squads squads are installed and ready. 🎉
State file written to `.agents/memory/demo/hello-world/state.md` and
committed locally (`b694270`) — no remote is configured on this repo,
so no push was attempted. Setup is working.
Auto-committed agent work
✔ Agent hello-world completed (Anthropic)
Run completed — demo/hello-world (37.4s)
.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: strategy, goals, learnings, feedback
Before every run, an agent loads a context cascade — company strategy, squad goals, 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, opencode, …), 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 # squad conversation (plan → work → review → verify)
squads run intelligence --task "Scan X" # directed, bounded run
squads inbox # everything waiting on YOUR decision — approve / reject / defer| 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 |
Node.js >= 20, Git, and
Claude Code (default
provider — others optional). squads doctor checks your machine.
Runs locally by default: your machine, your API keys, your data stay
on disk. No account needed for the open-source CLI. The cloud login
(squads login) and --cloud dispatch surface is hidden until the auth
endpoint is configured (SQUADS_AUTH_URL); until then every feature works
locally. Telemetry is
anonymous and install-level only (command names, versions, error
classes — never file contents, paths, or personal data); opt out any
time with DO_NOT_TRACK=1 or SQUADS_TELEMETRY_DISABLED=1.
git clone https://github.com/agents-squads/squads-cli.git
cd squads-cli
npm install
npm run build && npm link
npm testTypeScript (strict mode), Commander.js, Vitest, tsup.
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.