Agents Squads

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 agent

Claude Code must be installed and logged in (claude /login) before the first run — squads doctor checks 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)

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: 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

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.

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.

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