Squad
A GitHub Copilot team workspace that keeps AI development work persistent, inspectable, and human-led.
What does this agent do, and when should you use it?
Squad is a human-directed AI development-team system built around GitHub Copilot, delivered as a CLI and TypeScript SDK. It stores the roster, routing rules, decisions, agent histories, and session logs in a repository-local .squad/ directory so team context can persist across sessions and travel with Git. Users interact through copilot --agent squad or the Squad agent in VS Code Copilot Chat, while a coordinator routes work among team members. The CLI covers setup, upgrades, portable imports and exports, remote-team links, and Ralph polling; the SDK can generate Markdown team state from squad.config.ts. The project is explicitly alpha software, and its APIs and CLI commands may change between releases.
squad init creates repository state including .squad/team.md, routing.md, decisions.md, agents/*/charter.md, history.md, identity/, and log/. After a user gives GitHub Copilot a task, the coordinator uses routing.md to delegate work; members operate in separate contexts, read their own knowledge, and write learnings and decisions back to project files. squad upgrade updates squad.agent.md, templates, and GitHub workflows without changing .squad/ team state. squad triage, also available as watch or loop, polls issues, writes an issue-and-team context snapshot to a temporary file, and can invoke a configured agent command when --execute is enabled; its state can use git-notes or an orphan branch. In SDK-first mode, @bradygaster/squad-sdk exposes defineSquad, defineTeam, and defineAgent for a squad.config.ts file, and squad build generates the .squad/ Markdown files.
- A full-stack developer using GitHub Copilot who wants frontend, backend, and testing responsibilities recorded in the repository and retained between sessions.
- A small engineering team managing GitHub Issues that wants squad watch --execute to poll for actionable work and hand execution to Copilot sessions.
- A developer starting a React and Node project who wants squad init --preset default to create an immediately configured team, charters, and routing rules.
- A developer who switches branches often and needs to keep team state outside the working tree by using squad externalize.
- An engineer who prefers defining a team in TypeScript instead of hand-authoring Markdown, using squad.config.ts followed by squad build.
What are this agent's strengths and limitations?
- Persists roster data, routing, decisions, agent history, and searchable session logs in .squad/, allowing team context to be versioned and cloned with the repository.
- Offers CLI, Markdown-first configuration, and an SDK-first TypeScript path that generates team Markdown from squad.config.ts.
- Ralph watch includes issue polling, optional agent dispatch, health reporting, logging, selectable persistence backends, and four tiers of remediation.
- Keeps human accountability explicit: people retain control of priorities, approvals, and final changes.
- Its documented core experience depends on GitHub Copilot, making it platform-specific rather than a documented provider-neutral agent system.
- Adoption requires a recent Node.js runtime, npm, Git SSH setup, and GitHub CLI; Issues, PRs, and Ralph also require GitHub authentication through gh auth login.
- The project is labeled alpha, with documented potential CLI and API changes; SDK-first mode is experimental and has known bugs.
- watch --execute starts agent sessions, and --yolo suppresses per-tool-call approval prompts, so teams need to assess local permissions and review controls.
How do you install or deploy this agent?
Requirements are Node.js >=22.5.0, npm >=10.0.0, Git with an SSH agent, and GitHub CLI for GitHub integration. From a Git repository, run:
npm install -g @bradygaster/squad-cli
squad init
Authenticate for Issues, PRs, and Ralph:
gh auth login
Verify that .squad/team.md exists. For local source development, clone the repository, run npm install and npm run build, then run node ./packages/squad-cli/dist/cli-entry.js init.
How do you use this agent?
Start Squad through GitHub Copilot CLI:
copilot --agent squad --yolo
Describe the project or task in natural language, for example: “I'm starting a new project. Set up the team. Here's what I'm building: a recipe sharing app with React and Node.” Confirm the proposed members to begin. In VS Code, select the Squad agent in Copilot Chat instead. To monitor issues without execution, run npx @bradygaster/squad-cli watch. To dispatch agents for actionable issues, run npx @bradygaster/squad-cli watch --execute --interval 5. For SDK-first mode, create squad.config.ts using @bradygaster/squad-sdk builder functions and run squad build.
How does this agent compare with similar options?
Squad recommends GitHub Copilot CLI as its current interface and deprecates the no-argument squad interactive shell. Its default Markdown-first mode is recommended for production teams, while SDK-first uses squad.config.ts and squad build but is documented as experimental.