squad_questions.md

I read through docs starting here: https://bradygaster.github.io/squad/docs/get-started/installation/

I have some questions as squad is a bit confusing:

1. Seems squad is designed to run locally? There is copilot coding agent support but the docs seem to imply it adds the coding agent as another member to run tasks in the cloud as opposed to running all team agents concurrently in the cloud?
2. What's difference between running squad vs copilot --agent squad? The later seems to work better for me.
3. To customise your squad, do you need to edit all the underlying files that were created or can you prompt each squad member to adjust their prompt, skills, model, etc.?
4. After a squad completes, what if I want to work on a different task and perhaps form a different squad. Are all those squad files and members polluting my repo? Can I resume from a previous squad if I need to?

Let me research the Squad repository to answer your questions thoroughly.Great questions! After digging through the Squad repo, docs, and source code, here are answers to each:

---

1. Local vs. Cloud — Where Does Squad Run?

Yes, Squad is primarily designed to run locally — on your machine, inside a Codespace, or wherever you have a terminal with GitHub Copilot CLI or VS Code. The agents aren't cloud services; they're Copilot sub-agents spawned within your Copilot session. Each "team member" is a prompt context that the Squad coordinator agent spawns as a background sub-agent inside your local Copilot process.

The squad copilot command is specifically for adding GitHub's Copilot Coding Agent (@copilot) as an additional team member — this is the cloud-based coding agent that can work on issues asynchronously via PRs. It's treated as just another roster member in .squad/team.md, and the coordinator can route suitable tasks (like straightforward code changes) to it. So you're right: the coding agent is one more member on the team that happens to run in the cloud, not a mode that runs the entire squad remotely.

---

2. squad vs. copilot --agent squad

From the CLI reference:

Command	What it does
squad (no args)	Launches the Squad interactive shell — a custom REPL with /status, /agents, /sessions, /resume, /nap, etc. You talk to agents directly in this shell.
copilot --agent squad	Launches GitHub Copilot CLI and pre-selects the Squad agent. This is Copilot's native agent system with Squad loaded as the active agent.

Why copilot --agent squad may work better: It uses Copilot's full tool execution pipeline directly, which means Squad's squad.agent.md coordinator file is loaded as a proper Copilot agent with native tool calling support. The Squad shell (squad with no args) is a custom REPL built on top of the SDK that manages its own session pool and agent spawning — it's more experimental.

The docs' Quick Start actually recommends the Copilot route:

copilot --yolo

# Then type /agent and select Squad

Bottom line: copilot --agent squad is the more battle-tested path. The squad shell is a convenience layer with extra features (session management, /resume, /nap) but may be less stable in alpha.

---

3. Customizing Your Squad

You don't need to manually edit files! Squad is designed so you can customize your team through natural language prompts to the coordinator. From the Your Team docs:

What You Say	What Happens
"Add a database specialist"	Coordinator casts a new member, creates charter, updates routing
"Remove McManus from the team"	Archives agent directory to .squad/agents/.archived/, updates team.md
"Change the tester to focus on integration tests"	Updates the tester's charter and expertise
"Route all CSS files to Frontend"	Adds a rule to .squad/routing.md

That said, the files are just markdown, so you can also edit them directly:

• .squad/agents/{name}/charter.md — Each agent's identity, role, expertise, voice, and model preference
• .squad/team.md — The roster of who's on the team
• .squad/routing.md — Who handles what file patterns/domains
• squad.config.ts (SDK-first mode) — Define agents programmatically with defineAgent({ name, role, model, tools, capabilities }) and run squad build to regenerate the markdown

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

export default defineSquad({
  team: defineTeam({ name: 'Platform Squad', members: ['@edie', '@mcmanus'] }),
  agents: [
    defineAgent({ name: 'edie', role: 'TypeScript Engineer', model: 'claude-sonnet-4' }),
    defineAgent({ name: 'mcmanus', role: 'DevRel', model: 'claude-haiku-4.5' }),
  ],
});

---

4. Switching Tasks, Multiple Squads, and Cleanup

This is a valid concern. Here's how Squad handles it:

Are squad files "polluting" your repo?

Everything lives under .squad/ (plus .github/agents/squad.agent.md). The docs explicitly say commit this folder — it's meant to be part of your repo as team memory. Think of it like .github/ or .vscode/ — team configuration that persists.

Working on a different task

You don't need a new squad for a different task. The same team handles different tasks — just tell them what to work on next. Agent history.md files accumulate knowledge across tasks, which is by design (agents get smarter over time).

Forming a different squad

If you genuinely need a different team composition:

• Use squad export to snapshot your current team to a JSON file
• Use squad import <file> to restore a previous team (with --force to replace the current one — the old one gets archived)

Context hygiene between tasks

Use squad nap to clean up between heavy work sessions:

• Compresses agent history.md files (archives older entries)
• Prunes old logs (>7 days)
• Archives stale decisions (>30 days)
• Cleans up the decision inbox
• Use --deep for more aggressive cleanup, --dry-run to preview

Resuming previous work

The interactive shell supports session resume:

• /sessions — list saved sessions
• /resume <id> — restore a past session

Sessions are persisted to .squad/sessions/ as JSON files with automatic cleanup after 30 days.

TL;DR workflow for switching contexts:

# Finish current work, tidy up
squad nap

# Optionally snapshot if you want a clean restore point
squad export --out my-auth-sprint.json

# Start new work with the same team
# Just tell them the new task — they'll adapt

# Want to restore a previous team entirely?
squad import my-auth-sprint.json --force