# Agents Squads - Your AI Workforce

> Build AI agent teams that execute, learn, and scale - for the cost of API calls, not salaries. Code-first framework for engineers who want transparent, auditable, and ownable AI automation.

## What is Agents Squads?

Agents Squads is a framework for building **AI agents for engineering teams** and **AI workforce for business** operations. Unlike black-box AI solutions, every agent is defined in markdown, every decision is logged, and your team owns the entire system.

**Core Philosophy**: Transparent AI agents your team can learn, understand, and trust. No vendor lock-in, no opaque reasoning, no surprises.

## Key Differentiators

**Persistent Memory**: Agents maintain state across runs. Your customer research agent remembers previous conversations. Your code review agent learns your team's patterns.

**Cross-Run Learning**: Agents improve over time by analyzing past executions. Mistakes become learnings that prevent future errors.

**Autonomous Scheduling**: Set it and forget it. Agents run on schedules, respond to events, or execute on-demand. Your **AI workforce** operates 24/7.

**Domain-Aligned Architecture**: Organize agents into Squads (Finance, Engineering, Customer, Marketing). Each squad has specialized agents and shared memory - just like human teams.

**Model Agnostic**: Works with Claude, GPT-4, Gemini, or Ollama. Not locked into any vendor's API.

## Use Cases

### For Engineering Teams
- **Automated code review AI**: Review PRs with context from your codebase and team conventions
- **Technical research**: Monitor frameworks, dependencies, and security advisories
- **Documentation maintenance**: Keep docs in sync with code changes
- **Infrastructure monitoring**: Watch costs, performance, and security across cloud platforms

### For Business Operations
- **AI workforce for business**: Replace $1M/year in salaries with API calls
- **Customer operations**: Automated lead research, qualification, and CRM updates
- **Market intelligence**: Continuous competitor monitoring and trend analysis
- **Content generation**: Coordinated content creation across research, writing, and SEO

### For Multi-Agent Orchestration
- **Squad coordination**: Multiple agents working together with shared context
- **Event-driven workflows**: Agents trigger each other based on outcomes
- **Human-in-loop approvals**: Agents escalate decisions to humans when needed
- **Cross-team collaboration**: Finance squad triggers Engineering squad for infrastructure changes

## Documentation

- [Getting Started](https://agents-squads.com/docs/getting-started): 5-minute quickstart
- [Installation](https://agents-squads.com/docs/installation): Install squads-cli on your machine
- [CLI Commands](https://agents-squads.com/docs/commands): Complete command reference
- [Squad Configuration](https://agents-squads.com/docs/squad-md): Define squads with SQUAD.md
- [Examples](https://agents-squads.com/docs/examples): Real-world squad examples

## Quick Start

Install the CLI:

```bash
npm install -g squads-cli
```

Initialize a project:

```bash
squads init my-ai-workforce
cd my-ai-workforce
```

Run your first squad:

```bash
squads run research
```

View the dashboard:

```bash
squads dash
```

## Core Concepts

**Squads**: Domain-aligned teams (Finance, Engineering, Research, Customer). Each squad has specialized agents and shared memory.

**Agents**: Specialized workers defined in markdown. No code required - just purpose, instructions, and tools. Agents can be scheduled, event-triggered, or run on-demand.

**Memory**: Persistent state across sessions. Agents remember context from previous runs, enabling learning and continuity.

**Skills**: Reusable capabilities agents can invoke. Skills encapsulate complex operations like web research, content writing, or data analysis.

**MCP Servers**: Connect to external systems via Model Context Protocol. Access GitHub, databases, Slack, and any MCP-compatible tool.

**Scheduling**: Native support for cron-style schedules, event triggers, and approval workflows.

## Architecture Patterns

### Squad Structure
```
.agents/squads/engineering/
├── SQUAD.md              # Squad goals and coordination
├── code-reviewer.md      # Agent: Automated PR reviews
├── dependency-monitor.md # Agent: Track outdated packages
└── infra-monitor.md      # Agent: Watch cloud costs
```

### Agent Definition (Markdown)
```markdown
---
name: code-reviewer
squad: engineering
role: Review pull requests with team conventions
model: claude-sonnet-4
trigger: github_webhook
---

## Purpose
Review PRs for code quality, security, and team conventions.

## Instructions
1. Fetch PR diff from GitHub
2. Check against team style guide
3. Identify security issues
4. Post review comments
```

### Memory System
```
.agents/memory/engineering/code-reviewer/
├── state.md      # Current agent state
├── learnings.md  # Cross-run learnings
└── executions.md # Execution history
```

## Key Commands

```bash
squads status             # Overview of all squads
squads dash               # Full dashboard with metrics
squads run <squad>        # Execute squad workflow
squads run <squad>/<agent> # Run specific agent
squads memory query       # Search across memories
squads goal set           # Set squad objectives
squads approve            # Human-in-loop approvals
squads escalate           # Agent requests help
```

## Integration

Works with:
- **Claude Code**: Primary runtime for local execution
- **GitHub**: Native integration for issues, PRs, and webhooks
- **Slack**: Human-in-loop approvals and notifications
- **MCP Servers**: Any Model Context Protocol compatible system
- **Supabase**: Optional cloud backend for multi-user deployments

## Enterprise Features

- **Audit Logs**: Every agent execution is logged with inputs, outputs, and decisions
- **Cost Control**: Per-agent budgets (daily, monthly) with automatic throttling
- **Role-Based Access**: Control which teams can run which squads
- **Multi-Tenant**: Isolate data across organizations
- **SOC 2 Ready**: Compliance-friendly architecture with encryption and audit trails

## Why Agents Squads?

**For Engineers**: Code-first, transparent, debuggable. You own the system.

**For Founders**: Replace $1M in salaries with $10K in API costs. Our company runs entirely on AI squads.

**For Teams**: Agents that learn your patterns and improve over time. Not just automation - augmentation.

## Resources

- [GitHub](https://github.com/agents-squads): Open source repositories
- [Discord](https://discord.gg/agents-squads): Community support
- [Email](mailto:hello@agents-squads.com): Contact for enterprise inquiries

## Comparison

**vs. LangChain/LangGraph**: Code-first vs. framework-heavy. We optimize for readability and ownership.

**vs. AutoGPT/BabyAGI**: Production-ready vs. research prototypes. We have memory, scheduling, and cost controls.

**vs. Custom OpenAI Assistants**: Multi-agent orchestration vs. single agents. We handle squad coordination out of the box.

## License

MIT License - use it however you want. No vendor lock-in, no usage restrictions.

---

- Website: https://agents-squads.com
- CLI Product: https://agents-squads.com/cli
- Consulting: https://agents-squads.com/solutions/consulting
- GitHub: https://github.com/agents-squads
- Email: contact@agents-squads.com
- **Get Started**: https://agents-squads.com/docs/getting-started
- **npm**: `npm install -g squads-cli`