Installation

⚠️ Experimental — Squad is alpha software. APIs, commands, and behavior may change between releases.

Three ways to get Squad running. Pick the one that fits.

Try this:

npm install -g @bradygaster/squad-cli
squad

That’s it. You’re in.

1. CLI (Recommended)

The CLI is the fastest way to use Squad from any terminal.

Global install

npm install -g @bradygaster/squad-cli

Now use it anywhere:

squad init
squad status
squad watch

One-off with npx

No install needed — run the latest version directly:

npx @bradygaster/squad-cli init
npx @bradygaster/squad-cli status

Verify

squad --version

Update

npm install -g @bradygaster/squad-cli@latest

Which method should I use?

Pick based on what you’re doing:

You want to…	Use	Why
Try Squad quickly	CLI with `npx`	No install needed. Run `npx @bradygaster/squad-cli init` and you’re testing it.
Use Squad across all projects	CLI with `--global`	One install. Works everywhere. Run `squad` from any terminal.
Work inside VS Code	VS Code (just open your project)	Already using Copilot? Squad just works. Same `.squad/` directory as CLI.
Build tools on top of Squad	SDK	Typed APIs, routing config, agent lifecycle hooks. Programmatic access to everything.

Can’t decide? → Start with CLI. You can always add VS Code or the SDK later. Your .squad/ directory works identically everywhere.

2. VS Code

Squad works in VS Code through GitHub Copilot. Your .squad/ directory works identically in both CLI and VS Code — same agents, same decisions, same memory.

Tip: Initialize your team with the CLI (squad), then open the project in VS Code to keep working with the same squad.

3. SDK

Building your own tooling on top of Squad? Install the SDK as a project dependency:

npm install @bradygaster/squad-sdk

Then import what you need:

import { defineConfig, loadConfig, resolveSquad } from '@bradygaster/squad-sdk';

The SDK gives you typed configuration, routing, model selection, and the full agent lifecycle API. See the SDK Reference for details.

Personal squad (cross-project)

Want the same agents across all your projects?

squad init --global

This creates your personal squad directory — a personal team root that any project can inherit from. See Upstream Inheritance for details.

Personal squad location by platform:

Platform	Path
Linux	`~/.config/squad/`
macOS	`~/Library/Application Support/squad/`
Windows	`%APPDATA%\squad\`

First-Time Setup

After installing, initialize Squad in your project:

cd your-project
squad init

This creates:

.github/agents/squad.agent.md  — coordinator agent
.squad/                        — team state directory

Configuration (optional)

For typed configuration, create a squad.config.ts at your project root:

import { defineConfig } from '@bradygaster/squad-sdk';

export default defineConfig({
  team: {
    name: 'my-squad',
    root: '.squad',
    description: 'My project team',
  },
});

defineConfig() gives you full autocomplete and validation. But you don’t need it to get started — Squad works out of the box with sensible defaults.

Troubleshooting

`squad: command not found`

Your npm global bin isn’t in your PATH. Fix:

# Check if installed
npm list -g @bradygaster/squad-cli

# If installed but not found, check PATH:
echo $PATH | grep npm          # macOS/Linux
echo %PATH% | findstr npm      # Windows

`Cannot find .squad/ directory`

Run squad init in your project root, or squad init --global for a personal squad.

Version mismatch between CLI and SDK

Update both:

npm install -g @bradygaster/squad-cli@latest
npm install @bradygaster/squad-sdk@latest