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.

The @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.
npm install @bradygaster/squad-sdk
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:
PackagePurpose
@bradygaster/squad-sdkCore library. Zero CLI side effects. Import as a library in your own Node.js code, VS Code extension, or server.
@bradygaster/squad-cliCommand-line interface. Depends on the SDK and adds bin entry points (squad, copilot-squad). Install globally with npm install -g @bradygaster/squad-cli.
If you only need to orchestrate agents programmatically from application code, install @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.
Use these to define your Squad team in a squad.config.ts file. Run squad build to generate .squad/ markdown from the config.
ExportPurpose
defineSquadTop-level composition function — wraps all other builders
defineTeamDefine team metadata, project context, and member roster
defineAgentDefine a single agent with role, model, capabilities
defineRoutingDefine typed routing rules with patterns and fallback
defineCastingDefine casting universe allowlists and overflow strategy
defineCeremonyDefine a recurring ceremony with schedule, participants, and agenda
defineHooksDefine the governance hook pipeline (write guards, PII scrubbing)
defineTelemetryDefine OpenTelemetry endpoint, sample rate, and Aspire defaults
defineDefaultsDefine squad-level model and budget defaults
defineSkillDefine a reusable skill with domain, confidence, and patterns
defineBudgetDefine per-agent-spawn and per-session token/cost budgets
Also exports BuilderValidationError for catching config mistakes at startup.
Functions that locate and load Squad configuration on disk.
ExportPurpose
resolveSquadResolve all Squad paths from a working directory
resolveGlobalSquadPathLocate the global Squad home directory
ensureSquadPathResolve Squad path, throwing if missing
loadDirConfigLoad per-directory Squad config
deriveProjectKeyDerive a stable key from a project path
Also re-exports types: ResolvedSquadPaths, SquadDirConfig, SquadStateContext.
The casting engine maps real-world personas to agent roles and manages session cast history.
ExportPurpose
CastingEngineCore engine — selects cast members for a session
CastingHistoryPersisted history of past casting decisions
Key types: CastMember, AgentRole.
A fully-typed facade layer for reading and writing Squad’s file-based state. All collection classes accept a StateBackend and expose async CRUD methods.
ExportPurpose
SquadStateTop-level state facade — access all collections from one object
AgentsCollectionRead/write agent definitions
DecisionsCollectionManage typed agent decisions
ConfigCollectionSquad-level configuration data
LogCollectionAgent log and history entries
RoutingCollectionRouting rule storage
SkillsCollectionAgent skill definitions
TeamCollectionTeam composition metadata
TemplatesCollectionAgent charter templates
createAgentHandleFactory for scoped per-agent handles
Error classes: StateError, NotFoundError, ParseError, WriteConflictError, ProviderError.
Pluggable storage backends that persist Squad state inside the git repository using different git primitives.
ExportPurpose
resolveStateBackendResolve and instantiate a backend from config
WorktreeBackendStore state as files in a git worktree
GitNotesBackendStore state in git notes annotations
OrphanBranchBackendStore state on a dedicated orphan branch
TwoLayerBackendHot/cold two-layer backend with circuit breaking
CircuitBreakerFault-tolerance wrapper around any backend
StateBackendStorageAdapterAdapter bridge for custom storage providers
verifyStateBackendValidate that a backend is operational
Runtime utilities, model catalogs, event bus, and OpenTelemetry wiring.
ExportPurpose
VERSIONCurrent SDK version string, read from package.json at load time
loadConfig / loadConfigSyncLoad and validate a Squad config file
MODELSCatalog of supported model identifiers
TIMEOUTSDefault timeout constants
AGENT_ROLESBuilt-in agent role identifiers
RuntimeEventBusInternal pub/sub event bus
getMeterGet the OTel meter for custom metrics
getTracerGet the OTel tracer for custom spans
safeTimestampMonotonic timestamp helper
Functions for onboarding new agents into a team and resolving personal agent configurations.
ExportPurpose
onboardAgentRun the agent onboarding flow
resolvePersonalAgentsDiscover personal agent configs for a user
mergeSessionCastMerge personal agents into a session cast
Discover and delegate work across multiple Squad teams.
ExportPurpose
discoverSquadsScan for Squad manifests in the repository tree
validateManifestValidate a Squad manifest object
buildDelegationArgsBuild CLI args for delegating a task to another squad
formatDiscoveryTableFormat discovery results as a human-readable table
Install and manage agents and skills from the Squad marketplace.Exports everything from ./marketplace/index.js — see the plugins and marketplace guide for details.
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:
import {
  resolveSquad,
  CastingEngine,
  onboardAgent,
  SquadState,
  resolveStateBackend,
} from '@bradygaster/squad-sdk';

// Resolve paths from the current working directory
const paths = await resolveSquad(process.cwd());

// Initialize state with the default worktree backend
const backend = await resolveStateBackend(paths);
const state = new SquadState(backend);

// List all agents on the team
const agents = await state.agents.list();
console.log('Team members:', agents.map(a => a.name));

// Initialize the casting engine for a new session
const casting = new CastingEngine(state);
const cast = await casting.castForSession('feature-request');
console.log('Session cast:', cast.map(m => m.agentName));

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.

Build docs developers (and LLMs) love