TheDocumentation 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.
@bradygaster/squad-sdk package is the core runtime library for Squad. It provides everything you need to build multi-agent systems programmatically — from team definition and agent casting to session management, hooks, and state persistence. The SDK has zero CLI side effects by design: importing it as a library will never spawn processes or read configuration from disk unless you explicitly call resolution functions.
Installation
Install the SDK from npm. Node.js 22.5.0 or later is required.The
engines field in the package enforces node >=22.5.0. Use nvm or
fnm to switch Node versions if your environment is older.Package structure
Squad ships two npm packages. They are deliberately separated so library consumers do not inherit CLI startup costs:| Package | Purpose |
|---|---|
@bradygaster/squad-sdk | Core library. Zero CLI side effects. Import as a library in your own Node.js code, VS Code extension, or server. |
@bradygaster/squad-cli | Command-line interface. Depends on the SDK and adds bin entry points (squad, copilot-squad). Install globally with npm install -g @bradygaster/squad-cli. |
@bradygaster/squad-sdk alone. The CLI layer is optional.
Key exports
The SDK barrel export (import … from '@bradygaster/squad-sdk') is organized into functional categories. Expand a category below to see what it exposes.
Builder functions — SDK-first team definition
Builder functions — SDK-first team definition
Use these to define your Squad team in a
Also exports
squad.config.ts file. Run squad build to generate .squad/ markdown from the config.| Export | Purpose |
|---|---|
defineSquad | Top-level composition function — wraps all other builders |
defineTeam | Define team metadata, project context, and member roster |
defineAgent | Define a single agent with role, model, capabilities |
defineRouting | Define typed routing rules with patterns and fallback |
defineCasting | Define casting universe allowlists and overflow strategy |
defineCeremony | Define a recurring ceremony with schedule, participants, and agenda |
defineHooks | Define the governance hook pipeline (write guards, PII scrubbing) |
defineTelemetry | Define OpenTelemetry endpoint, sample rate, and Aspire defaults |
defineDefaults | Define squad-level model and budget defaults |
defineSkill | Define a reusable skill with domain, confidence, and patterns |
defineBudget | Define per-agent-spawn and per-session token/cost budgets |
BuilderValidationError for catching config mistakes at startup.Resolution — path and config discovery
Resolution — path and config discovery
Functions that locate and load Squad configuration on disk.
Also re-exports types:
| Export | Purpose |
|---|---|
resolveSquad | Resolve all Squad paths from a working directory |
resolveGlobalSquadPath | Locate the global Squad home directory |
ensureSquadPath | Resolve Squad path, throwing if missing |
loadDirConfig | Load per-directory Squad config |
deriveProjectKey | Derive a stable key from a project path |
ResolvedSquadPaths, SquadDirConfig, SquadStateContext.Casting — agent selection engine
Casting — agent selection engine
The casting engine maps real-world personas to agent roles and manages session cast history.
Key types:
| Export | Purpose |
|---|---|
CastingEngine | Core engine — selects cast members for a session |
CastingHistory | Persisted history of past casting decisions |
CastMember, AgentRole.State — typed facade over .squad/ state
State — typed facade over .squad/ state
A fully-typed facade layer for reading and writing Squad’s file-based state. All collection classes accept a
Error classes:
StateBackend and expose async CRUD methods.| Export | Purpose |
|---|---|
SquadState | Top-level state facade — access all collections from one object |
AgentsCollection | Read/write agent definitions |
DecisionsCollection | Manage typed agent decisions |
ConfigCollection | Squad-level configuration data |
LogCollection | Agent log and history entries |
RoutingCollection | Routing rule storage |
SkillsCollection | Agent skill definitions |
TeamCollection | Team composition metadata |
TemplatesCollection | Agent charter templates |
createAgentHandle | Factory for scoped per-agent handles |
StateError, NotFoundError, ParseError, WriteConflictError, ProviderError.State backends — git-native persistence
State backends — git-native persistence
Pluggable storage backends that persist Squad state inside the git repository using different git primitives.
| Export | Purpose |
|---|---|
resolveStateBackend | Resolve and instantiate a backend from config |
WorktreeBackend | Store state as files in a git worktree |
GitNotesBackend | Store state in git notes annotations |
OrphanBranchBackend | Store state on a dedicated orphan branch |
TwoLayerBackend | Hot/cold two-layer backend with circuit breaking |
CircuitBreaker | Fault-tolerance wrapper around any backend |
StateBackendStorageAdapter | Adapter bridge for custom storage providers |
verifyStateBackend | Validate that a backend is operational |
Runtime — config, constants, observability
Runtime — config, constants, observability
Runtime utilities, model catalogs, event bus, and OpenTelemetry wiring.
| Export | Purpose |
|---|---|
VERSION | Current SDK version string, read from package.json at load time |
loadConfig / loadConfigSync | Load and validate a Squad config file |
MODELS | Catalog of supported model identifiers |
TIMEOUTS | Default timeout constants |
AGENT_ROLES | Built-in agent role identifiers |
RuntimeEventBus | Internal pub/sub event bus |
getMeter | Get the OTel meter for custom metrics |
getTracer | Get the OTel tracer for custom spans |
safeTimestamp | Monotonic timestamp helper |
Agents — onboarding and personal agents
Agents — onboarding and personal agents
Functions for onboarding new agents into a team and resolving personal agent configurations.
| Export | Purpose |
|---|---|
onboardAgent | Run the agent onboarding flow |
resolvePersonalAgents | Discover personal agent configs for a user |
mergeSessionCast | Merge personal agents into a session cast |
Cross-squad — multi-team coordination
Cross-squad — multi-team coordination
Discover and delegate work across multiple Squad teams.
| Export | Purpose |
|---|---|
discoverSquads | Scan for Squad manifests in the repository tree |
validateManifest | Validate a Squad manifest object |
buildDelegationArgs | Build CLI args for delegating a task to another squad |
formatDiscoveryTable | Format discovery results as a human-readable table |
Marketplace — agent and skill packages
Marketplace — agent and skill packages
Install and manage agents and skills from the Squad marketplace.Exports everything from
./marketplace/index.js — see the plugins and marketplace guide for details.Streams — SubSquad streaming patterns
Streams — SubSquad streaming patterns
Streaming primitives for SubSquad delegation and fan-out patterns.Exports everything from
./streams/index.js — used internally by the coordinator for parallel task dispatch.Quick example
The following snippet shows the minimal imports needed to resolve a Squad configuration, initialize the casting engine, and onboard an agent:What’s next
SDK-First Mode
Define your team in TypeScript with builder functions and generate
.squad/ markdown from squad.config.ts.Hooks & Tools
Intercept tool calls, enforce file-write guards, scrub PII, and add governance policies programmatically.
.NET Package
Expose a Squad team as a Microsoft Agent Framework
AIAgent in any .NET 10 application.