Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bradygaster/squad/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through everything you need to get Squad running: install the CLI globally, initialize a team inside a git repo, authenticate with GitHub, and open your first conversation with agents through GitHub Copilot. By the end, your .squad/ folder will exist, your agents will have names, and your team will be ready to work.
1

Create your project

Squad lives inside a git repository. Start by creating a new directory and initializing git:
mkdir my-project && cd my-project
git init
Validate: Run git status. You should see On branch main (or master) with the message “No commits yet”. If git is not installed, download it here.
2

Install Squad

Install the Squad CLI globally from npm, then run squad init inside your project:
npm install -g @bradygaster/squad-cli
squad init
The default squad init runs an interactive setup wizard that walks you through configuring your team step by step — ideal when you want to build and customize your squad deliberately.If you’d rather skip the wizard and get a fully-configured team instantly, use the --preset default flag:
squad init --preset default
This applies the built-in default preset, which includes pre-configured team members, charters, and routing rules — ready to go in under a second.Validate: Check that .squad/team.md was created in your project directory.
cat .squad/team.md
3

Authenticate with GitHub

Squad uses the GitHub CLI for issue triage, PR management, and Ralph’s automated watch mode. Authenticate now so those features work when you need them:
gh auth login
Follow the interactive prompts to complete the OAuth flow in your browser.Validate: Run gh auth status. You should see Logged in to github.com as <your-username>.
The gh CLI is a separate tool from Squad. If it’s not installed, download it here. GitHub authentication is required for squad triage, watch mode (Ralph), squad copilot, and any command that reads or writes GitHub Issues or pull requests.
4

Open Copilot and start talking

Launch GitHub Copilot with the Squad agent:
copilot --agent squad --yolo
The --yolo flag tells Copilot to auto-approve tool calls without prompting you for each one. Squad makes many tool calls in a typical session — reading files, writing agent state, recording decisions — so --yolo keeps the flow uninterrupted.In VS Code: Open the Copilot Chat panel, click the agent selector, and choose Squad.Once Squad is running, introduce your project:
I'm starting a new project. Set up the team.
Here's what I'm building: a recipe sharing app with React and Node.
Squad will respond with team member proposals, each named from a persistent thematic cast. Type yes to confirm — your team is ready to work.
After squad init completes, your .squad/ folder contains everything Squad needs to run your team. These files are meant to be committed to git — anyone who clones your repo inherits the complete team with all accumulated knowledge.
Here’s the full directory structure that gets created: 
.squad/
├── team.md              # Roster — who's on the team
├── routing.md           # Routing — who handles what
├── decisions.md         # Shared brain — team decisions
├── ceremonies.md        # Sprint ceremonies config
├── casting/
│   ├── policy.json      # Casting configuration
│   ├── registry.json    # Persistent name registry
│   └── history.json     # Universe usage history
├── agents/
│   ├── {name}/
│   │   ├── charter.md   # Identity, expertise, voice
│   │   └── history.md   # What they know about YOUR project
│   └── scribe/
│       └── charter.md   # Silent memory manager
├── skills/              # Compressed learnings from work
├── identity/
│   ├── now.md           # Current team focus
│   └── wisdom.md        # Reusable patterns
└── log/                 # Session history (searchable archive)

​
Upgrading

When a new version of Squad is released, upgrading is a two-step process. Step 1: Update the CLI binary 
npm install -g @bradygaster/squad-cli@latest
Step 2: Update Squad-owned files in your project 
squad upgrade
squad upgrade refreshes squad.agent.md, templates, and GitHub workflow files to match the latest release. It never touches your .squad/ team state — your agents, decisions, history, and cast names are always preserved. Use --force to re-apply updates even when your installed version already matches the latest.
Run squad doctor at any time to diagnose setup issues. It checks your Node.js version, Squad configuration, GitHub authentication, and .squad/ directory health, then prints a categorized report with recommended fixes.

Build docs developers (and LLMs) love

Get started for freeTalk to us