Claude Squad

Your AI-powered dev team in one command. Build software faster with coordinated AI agents that actually work together.

What is this?

claude-squad turns Claude Code into a full development team. Instead of one AI doing everything, you get specialized agents (Backend Dev, Frontend Dev, QA, DevOps) that coordinate like a real squad.

npx claude-squad init

That's it. Your project now has a complete AI team ready to build.

The Problem

Claude Code is powerful, but building complex software alone is overwhelming. You need:

• A backend developer who thinks about APIs and databases
• A frontend developer who cares about UX and performance
• A QA engineer who catches bugs before production
• A DevOps engineer who handles deployments
• A product manager who keeps everything aligned

And they all need to work together without stepping on each other's toes.

The Solution

# Install the squad
npx claude-squad init

# Start Claude Code
claude

# Create a new feature with the full team
/squad:feature payment-system

What happens next:

1. Product Manager analyzes requirements
2. Architect designs the system
3. Backend Dev creates the API worktree
4. Frontend Dev creates the UI worktree
5. QA Dev sets up tests
6. DevOps Dev configures deployment
7. Everyone works in parallel on isolated branches

One feature. Six specialists. Zero conflicts.

Features

• Multi-Agent Coordination - Backend, Frontend, QA, DevOps agents work together automatically
• Git Worktree Management - Parallel development without branch conflicts
• Works with Any Project - Drop it into existing codebases or start fresh
• Slash Commands - Natural interface: /squad:feature, /squad:status, /squad:agent
• Custom Agents - Create domain-specific experts (ML Engineer, Security Auditor, etc.)
• Quality Gates - Automated testing, linting, security scans before merge
• Provider Agnostic - Built for Claude Code, works with any Claude model

Quick Start

1. Install

npx claude-squad init

This copies agent definitions and slash commands into your project's .claude/ directory.

2. Initialize Your Project

claude  # Start Claude Code

Then type:

/squad:init

Answer a few questions about your project (monorepo vs multi-repo, integrations, etc.).

3. Build Something

/squad:feature user-authentication

Describe what you want. The squad figures out:

• Which repositories need changes
• Which agents should work on what
• How to coordinate the work
• When it's ready to merge

Slash Commands

| Command | What It Does | |---------|--------------| | /squad:init | Initialize project with AI squad | | /squad:feature | Start new feature with full team | | /squad:status | See what everyone is working on | | /squad:worktree | Manage parallel development branches | | /squad:agent | Create custom specialist agents |

Or just talk naturally:

• "I need to add payment processing"
• "Show me the project status"
• "Create a security expert agent"

How It Works

Traditional Claude Code

You → Claude → Everything

One AI tries to be developer, tester, designer, and DevOps.

With claude-squad

You → Orchestrator → Assigns Work
                  |
        +---------+---------+---------+
        |         |         |         |
        v         v         v         v
    Backend    Frontend     QA     DevOps
      Dev        Dev       Dev      Dev
        |         |         |         |
        v         v         v         v
    Isolated  Isolated  Isolated  Isolated
    Worktree  Worktree  Worktree  Worktree
        |         |         |         |
        +---------+---------+---------+
                      |
                      v
                    Merge

Each agent has deep expertise in their domain. The Orchestrator coordinates them.

Pre-Built Agents

Your squad comes with expert agents out of the box:

| Agent | Expertise | |-------|-----------| | Prime Orchestrator | Coordinates all agents, manages workflows | | Senior Backend Engineer | APIs, databases, distributed systems (10+ years) | | Senior Frontend Engineer | React/Vue, UI/UX, performance (10+ years) | | Solution Architect | System design, cloud architecture, microservices | | Product Manager | Requirements, PRDs, user stories, roadmaps | | QA Engineer | Test automation, quality assurance, bug prevention | | DevOps Engineer | CI/CD, infrastructure, deployments |

Each agent has "war stories" from real projects—they think like experienced developers, not generic chatbots.

Creating Custom Agents

Need a specialized expert?

/squad:agent

Example:

Role: Blockchain Security Expert
Responsibilities: Smart contract audits, vulnerability analysis
Experience: Senior - 10 years
Expertise: Solidity, Ethereum, DeFi protocols

✓ Agent created: .claude/agents/security/blockchain-security-expert.md

Now you can assign blockchain work to someone who understands reentrancy attacks and gas optimization.

Real-World Example

Building a SaaS app with authentication, payments, and admin dashboard:

# Initialize the squad
npx claude-squad init
claude
/squad:init

# Answer: Monorepo, GitHub integration, Stripe payments

Create features in parallel:

/squad:feature auth-system
/squad:feature payment-integration
/squad:feature admin-dashboard

What happens:

1. Auth System

   • Backend Dev: JWT tokens, password hashing, session management
   • Frontend Dev: Login/signup forms, auth guards
   • QA Dev: Security tests, edge cases
   • DevOps Dev: Auth service deployment

2. Payment Integration

   • Backend Dev: Stripe webhook handlers, subscription logic
   • Frontend Dev: Payment forms, subscription UI
   • QA Dev: Payment flow tests, fraud scenarios
   • DevOps Dev: PCI compliance, secure key management

3. Admin Dashboard

   • Backend Dev: Admin API endpoints, permissions
   • Frontend Dev: Dashboard UI, analytics charts
   • QA Dev: Permission tests, data validation
   • DevOps Dev: Admin service isolation

All three features developed simultaneously. No merge conflicts. Each agent works in isolated worktrees.

/squad:status

See progress across all features. Merge when ready.

Why claude-squad?

Without claude-squad

• One AI context switches between roles constantly
• Generic responses lacking domain expertise
• Hard to work on multiple features in parallel
• No separation between concerns
• "General knowledge" about everything, expert in nothing

With claude-squad

• Specialized agents with deep expertise in their domain
• Backend dev thinks about scalability, frontend dev thinks about UX
• Multiple features developed simultaneously without conflicts
• Clear separation: APIs vs UI vs Infrastructure vs Testing
• Each agent has 10+ years of "experience" (via war stories and patterns)

Requirements

• Claude Code CLI (required)
• Node.js >= 18.0.0
• Git (for worktree management)

Installation

# Using npx (recommended)
npx claude-squad init

# Or install globally
npm install -g claude-squad
claude-squad init

What Gets Installed

your-project/
├── .claude/
│   ├── agents/           # AI team member definitions
│   ├── commands/         # Slash commands (/squad:*)
│   ├── settings.json     # Quality gates, hooks, workflows
│   └── skills/           # Shared expertise modules
├── PROJECT.md            # Your project configuration (created on /squad:init)
└── PROJECT_STATUS.md     # Current work tracking (created on /squad:init)

No changes to your code. Just adds AI orchestration.

Configuration

After /squad:init, customize in .claude/settings.json:

{
  "qualityGates": {
    "testCoverage": 80,
    "lintingRequired": true,
    "securityScanRequired": true
  },
  "workflowEnforcement": {
    "requireReviewBeforeMerge": true,
    "minimumReviewers": 2,
    "blockDirectPushToMain": true
  }
}

Workflows

The squad follows proven development workflows:

• Project Initialization - Set up new projects with proper structure
• Feature Development - End-to-end lifecycle from requirements to deployment
• PRD Creation - Product requirements with task breakdowns
• Sprint Management - Agile ceremonies (planning, standups, retros)
• Deployment - Release automation and rollback strategies

Each workflow is documented step-by-step in docs/workflows/.

Git Worktree Management

The squad uses git worktrees for parallel development:

/squad:worktree list

Example output:

Active Worktrees:
├─ backend/
│  ├─ feature-auth (3 days old, 12 commits ahead)
│  └─ feature-payments (1 day old, 5 commits ahead)
├─ frontend/
   ├─ feature-auth (3 days old, 8 commits ahead)
   └─ feature-payments (1 day old, 3 commits ahead)

Benefits:

• No branch switching = no context loss
• Multiple features in progress simultaneously
• Each agent works in isolated environment
• Clean merges when features complete

Integrations

The squad connects with your existing tools:

• GitHub - Issue tracking, PR management, CI/CD
• GitLab - Same as GitHub
• Jira - Sprint planning, task tracking
• Slack - Notifications, status updates
• Vercel/Netlify - Deployment automation
• Supabase/PlanetScale - Database management
• Stripe - Payment webhooks

Configuration: Answer questions during /squad:init or configure manually in PROJECT.md.

Advanced Usage

Custom Workflows

Create project-specific workflows in docs/workflows/:

---
name: mobile-app-release
description: iOS + Android release workflow
---

Stage 1: Version Bump
Stage 2: Build iOS + Android
Stage 3: TestFlight + Play Store Beta
Stage 4: Production Release
Stage 5: Monitoring

The Orchestrator follows your custom workflows.

Quality Automation

Set up pre-commit hooks in .claude/settings.json:

{
  "hooks": {
    "preToolUse": ["run-tests", "check-coverage"],
    "postToolUse": ["update-status"],
    "userPromptSubmit": ["check-quality-gates"]
  }
}

Agents can't commit until tests pass and coverage is 80%+.

Multi-Repository Projects

The squad handles monorepos and multi-repos:

/squad:feature cross-repo-search

Orchestrator detects:

• Feature needs changes in api-service, web-app, mobile-app
• Creates worktrees in all three repos
• Assigns appropriate agents to each repo
• Coordinates integration between repos

Troubleshooting

"PROJECT.md not found"

• Run /squad:init first to initialize your project

"Worktree already exists"

• Use /squad:worktree list to see existing worktrees
• Remove with /squad:worktree remove [name]

"Quality gates failing"

• Check test coverage (must be 80%+)
• Run linter and fix errors
• Complete security scan

"Agent not responding"

• Verify agent exists in .claude/agents/
• Check agent has required tools assigned

Need help? Open an issue: github.com/mtmsuhail/claude-squad/issues

Documentation

• Agent Guidelines - How to create custom agents
• Hooks Guide - Automation with hooks
• Integrations - Connect external tools
• Workflows - Step-by-step process guides

Philosophy

Good AI tools don't replace developers. They multiply them.

claude-squad is based on three principles:

1. Specialization > Generalization - Deep expertise beats shallow knowledge
2. Coordination > Isolation - Agents working together beats one AI doing everything
3. Workflow > Ad-Hoc - Proven processes beat improvisation

Your job isn't to write every line of code. It's to orchestrate the squad that does.

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Ways to contribute:

• Create new agent templates
• Add workflow guides
• Improve documentation
• Report bugs and suggest features

License

MIT © mtmsuhail

What's Next?

1. Install: npx claude-squad init
2. Initialize: Start Claude Code and run /squad:init
3. Build: Try /squad:feature your-first-feature
4. Customize: Create agents for your domain with /squad:agent

Welcome to the squad. Your AI dev team is ready.