Configuration Reference

Try this:

squad init

That’s it. Squad works out of the box. Everything below is optional.

squad.config.ts

For type-safe SDK-First configuration, create this at your project root:

import {
  defineSquad,
  defineTeam,
  defineAgent,
  defineRouting,
} from '@bradygaster/squad-sdk';

export default defineSquad({
  version: '1.0.0',
  team: defineTeam({
    name: 'my-squad',
    description: 'My project team',
    members: ['@edie', '@mcmanus'],
  }),
  agents: [
    defineAgent({
      name: 'edie',
      role: 'TypeScript Engineer',
      model: 'claude-sonnet-5',
      tools: ['grep', 'edit', 'view'],
    }),
    defineAgent({
      name: 'mcmanus',
      role: 'DevRel',
      model: 'claude-haiku-4.5',
      tools: ['grep', 'view'],
    }),
  ],
  routing: defineRouting({
    rules: [
      { pattern: 'feature-*', agents: ['@edie'], tier: 'standard' },
      { pattern: 'docs-*', agents: ['@mcmanus'], tier: 'lightweight' },
    ],
    defaultAgent: '@coordinator',
  }),
});

Each builder (defineSquad(), defineTeam(), defineAgent(), etc.) validates your config at runtime with type-safe error messages. Edit your .ts file, then run squad build to generate .squad/ markdown.

Or start with markdown: squad init creates a markdown-only squad with no config file needed.

.squad/ Directory

.squad/
├── team.md              # Who's on the team
├── routing.md           # Work routing rules
├── decisions.md         # Architectural decisions (shared memory)
├── directives.md        # Permanent team rules
├── casting-state.json   # Agent names + universe theme
├── model-config.json    # Per-agent model overrides
├── agents/
│   ├── {name}/
│   │   ├── charter.md   # Role, expertise, voice
│   │   └── history.md   # What this agent has done
│   └── ...
├── skills/              # Reusable knowledge files
├── decisions/inbox/     # Pending decisions (Scribe merges these)
├── log/                 # Session logs
└── orchestration-log/   # Coordinator state

.squad/config.json may also carry clients: the portable list of host projections to keep fresh (copilot, claude, kiro, opencode, cursor, codex, antigravity). It never holds credentials, paths, URLs or session ids. See Using Squad across clients.

Commit this directory. It’s your team’s brain. Anyone who clones the repo gets the full team with all their knowledge.

.squad/ — Required vs Optional Files

squad init creates a working team. Here’s what’s required and what’s optional.

Required Files

These are always created by squad init. The loader expects them.

Optional Files

These are created only when you opt in during init.

• .squad/templates/ — SDK templates, overwritten on upgrade
• .github/workflows/*.yml — CI/CD workflows (opt-in: --include-workflows)
• .copilot/mcp-config.json — MCP server config (opt-in: --include-mcp-config)

⚠️ Hard rule: Squad NEVER writes temp files, logs, or memory to your repo root. All team state lives in .squad/ only. Your project tree stays clean.

Quick Recovery

squad doctor                        # Check for issues
rm -rf .squad && squad init         # Full reset (back up agents/decisions first)

Routing Rules

Control which agent gets which work. Edit .squad/routing.md or configure in squad.config.ts:

# Routing Rules

**Frontend changes** → Trinity
**Backend API work** → Morpheus
**Database migrations** → Morpheus
**Test writing** → Tank
**Architecture decisions** → Neo

Or programmatically:

routing: {
  workTypes: [
    { pattern: /\bAPI|backend\b/i, targets: ['backend'], tier: 'standard' },
    { pattern: /\bUI|React\b/i, targets: ['frontend'], tier: 'standard' },
    { pattern: /\bstatus|help\b/i, targets: [], tier: 'direct' },
  ],
  issueLabels: [
    { labels: ['bug', 'backend'], targets: ['backend'] },
  ],
}

Model Configuration

17 models across three tiers. Squad picks the right one, or you override:

Per-agent overrides in model-config.json:

{
  "neo": "claude-opus-5",
  "tank": "claude-haiku-4.5"
}

Resolution order: user override → charter → task auto-select → config default.

Resolution Order

Squad finds .squad/ by walking up:

1. Current directory (./.squad/)
2. Parent directories (walk up to project root)

First match wins. Squad never resolves a squad from your user profile: outside a project (no .squad/ in the directory tree) state commands such as squad status, squad doctor and squad cast fail with No squad in this directory — run squad init in the project first.

Environment Variables

See Also

• CLI Reference — Commands and shell interactions
• SDK Reference — Programmatic API