Squad Documentation

The Squad SDK documentation is transitioning to an auto-generated API reference system using TypeDoc and Markdown. This system is designed to provide a searchable, linkable, and canonical source for all exported symbols, including classes, interfaces, functions, and type aliases.

Key components being documented include:

• SquadState: Central architecture type for state management.
• StorageProvider: The interface contract for state layer implementations.
• AgentHandle: The interface defining operations available to agents in .squad/agents/.
• SquadCoordinator: Core orchestration class.
• Config Schemas: Definitions found in config/schema.ts and runtime/config.ts.

The Squad CLI uses a fixed bottom input box design to provide a grounded user experience similar to Copilot or Claude. The input area is contained within a box using a rounded border style to distinguish it from the streaming message history.

Key Design Features

• Border Style: Uses borderStyle="round" (e.g., ╔═╗╚═╝) for a soft visual feel that matches the header.
• Error Handling: Errors are not rendered inside the input box. Instead, they appear as system messages in the scrollback history above the input box, allowing users to see errors in context.
• Terminal Compatibility: The layout is designed to be responsive across different terminal widths (40, 80, and 120 columns).
• NO_COLOR Support: When NO_COLOR is detected, the UI degrades gracefully to a plain text format using separators (e.g., ─────── sq> [text] ───────).

The sample demonstrates several core Squad patterns:

• Casting: Using CastingEngine to cast multiple agents and create individual sessions per agent.
• Session Management: Using SquadClientWithPool to manage concurrent sessions with rate limiting.
• Routing: Mapping user input to specific agents via keyword matching.
• Streaming: Using StreamingPipeline to capture and display token-by-token output in real time.
• Event Handling: Using EventBus to emit and subscribe to session lifecycle events.

Squad supports several ways to enter the initialization/onboarding flow depending on your current state:

1. New Project: Running squad in a directory without a .squad/ folder will prompt you to run squad init.
2. Scaffold Only: Running squad init (without a prompt) creates the .squad/ directory and an empty team.md roster, but requires a subsequent step to cast the team.
3. Deferred Casting: Running squad init "<prompt>" creates the scaffold and a .init-prompt file. Running squad afterwards will trigger an automatic team cast.
4. REPL Casting: If you enter the REPL with an empty roster, your first message can be used as the prompt to cast your team.
5. Copilot Extension: Using the squad.agent.md template in Copilot provides a rich, two-phase casting flow (propose $\rightarrow$ confirm $\rightarrow$ create).

The sample demonstrates several key Squad SDK workflows:

• Directory Resolution: Using resolveSquad() to find or create a .squad/ directory.
• Themed Casting: Using the CastingEngine to create a team of agents from a specific universe system.
• Agent Onboarding: Creating individual agent directories and initializing their charter and history files.
• Deterministic Identities: Using the casting history system to ensure that casting the same configuration twice results in consistent agent names.

Ralph (the Squad automation engine) can operate at three different levels of autonomy depending on your setup:

1. In-session: Active loop triggered manually while you are at the keyboard (e.g., "Ralph, go"). This is ephemeral and lives only while the Copilot session is active.
2. Local watchdog: A separate process running on your machine while you are away (e.g., squad watch --execute). It polls at a defined --interval.
3. Cloud heartbeat: Fully unattended execution triggered by GitHub Actions events (e.g., squad-heartbeat.yml) in response to events like issue closures or PR merges.

Presets are reusable, named bundles of agent charters (roles, expertise, and prompt styles) that you can apply to any Squad project. They define the shape of a team but do not capture casting state, skills, routing rules, decisions, or memory.

Built-in presets are available by default, and you can save your own custom rosters to ~/.squad/presets/<name>/.

Squad uses a tiered memory architecture to separate concerns between low-level persistence and high-level intelligence.

• StorageProvider: A low-level abstraction for reading, writing, listing, and deleting bytes/blobs. It does not understand semantic meaning or retention policies.
• SquadState: The structured surface for .squad/ data.
• MemoryGovernanceProvider / MemoryStore: A high-level layer sitting above state and storage. It handles classification, policy enforcement, routing, retrieval, and promotion of memory entries.

This architecture allows Squad to support local worktree memory (default) alongside optional external semantic providers like Copilot Memory.

The Platform Adapter allows Squad to interact with different source code hosting platforms (such as GitHub and Azure DevOps) using a unified interface. This abstraction ensures that Squad's triage and assignment logic remains consistent regardless of whether you are using GitHub or Azure DevOps.

Key features include:

• Zero-config detection: The platform is automatically detected by reading the origin git remote URL.
• CLI-based interaction: Instead of managing OAuth tokens or PATs, the adapters wrap existing CLI tools (gh for GitHub, az for Azure DevOps), leveraging your existing local authentication.

The hook-governance sample demonstrates four specific types of deterministic hooks that enforce security and policy without relying on prompt instructions:

• File-write guards: Blocks writes to prohibited paths (e.g., preventing writes to /etc/passwd) by defining allowed safe zones.
• PII scrubbing: Automatically redacts personally identifiable information, such as email addresses, from tool output strings and nested objects.
• Reviewer lockout: Prevents a specific agent from editing a file after a review rejection, while still allowing other agents access.
• Ask-user rate limiting: Caps the number of times an agent can prompt the user within a single session.