Squad Squad

Frequently asked questions

⚠️ Experimental — Squad is alpha software. APIs, commands, and behavior may change between releases.

Common questions, troubleshooting tips, and clarifications based on community feedback. Can’t find your answer? Open an issue.

Which CLI should I use?

Short answer: Use GitHub Copilot CLI for day-to-day work. Use Squad CLI for setup, diagnostics, and specific features.

Why GitHub Copilot CLI?

  • Full agent spawning capabilities
  • Access to all Squad features through natural conversation
  • Model selection and background execution
  • No manual commands — just describe what you need

When to use Squad CLI:

  • Initial setup: squad init
  • Diagnostics: squad doctor
  • Continuous triage: squad triage --interval 10
  • Aspire dashboard: squad aspire
  • Export/import: squad export and squad import
  • Remote phone access: squad start --tunnel

Common workflow pattern:

# Terminal 1: Run continuous triage
squad triage --interval 10

# Terminal 2: Work with your team
gh copilot
> @squad what issues are ready to work?

For a detailed feature comparison, see Client Compatibility Matrix.

Why doesn’t gh issue edit --add-assignee "@copilot" work?

Problem: Running gh issue edit <number> --add-assignee "@copilot" (or variants like copilot-swe-agent[bot]) fails locally, even with a Personal Access Token.

Why this happens: The GitHub Copilot coding agent is a bot account. Bot accounts cannot be assigned to issues via the GitHub CLI in the same way as human users — the GitHub API restricts direct assignment of bot accounts through standard endpoints.

Recommended workaround: Use label-based assignment through the GitHub Actions workflow:

  1. Add the squad:copilot label to the issue:

    gh issue edit <number> --add-label "squad:copilot"

  2. The auto-assign workflow (.github/workflows/squad-copilot-auto-assign.yml) detects the label and assigns @copilot automatically.

Prerequisites for auto-assign:

  • You must create a GitHub Classic Personal Access Token with repo scope
  • Add it as a repository secret: gh secret set COPILOT_ASSIGN_TOKEN
  • The workflow uses this token to perform the assignment on your behalf

See Copilot Coding Agent for full setup instructions.

I don’t see anything on the Aspire dashboard

Problem: You ran squad aspire and opened the dashboard, but no telemetry is showing up.

Why this happens: The Aspire dashboard integration requires the Squad CLI. It is not available when using GitHub Copilot CLI directly.

How to fix:

  1. Ensure you started Aspire with the Squad CLI:

    squad aspire

  2. Confirm the container is running:

    docker ps | grep aspire-dashboard

  3. Look for the dashboard URL in the output (usually http://localhost:18888)

  4. Run a Squad CLI command that generates telemetry:

    squad doctor
squad triage

  5. Refresh the Aspire dashboard — you should see traces, metrics, and logs appear

Note: GitHub Copilot CLI sessions do not send telemetry to Aspire. Only Squad CLI commands emit OpenTelemetry data to the dashboard.

See Using Squad with the Aspire Dashboard for details.

squad doctor complains about absolute path for teamRoot

Problem: Running squad doctor shows a warning like:

⚠ teamRoot uses absolute path — consider making it relative

Why this matters: Absolute paths (e.g., C:\Users\me\squad\ or /Users/me/squad/) break portability. If you share the squad with a teammate or clone it to a new machine, the absolute path won’t resolve correctly.

How to fix: Make the teamRoot path relative to the project root.

Example — Before (absolute):

{
  "teamRoot": "C:\\Users\\me\\repos\\my-team\\.squad"
}

Example — After (relative):

{
  "teamRoot": ".squad"
}

For linked teams (dual-root mode):

If your project links to a remote team repository:

{
  "teamRoot": "../team-repo/.squad"
}

The path should be relative to your project root (where .squad/ or squad.config.ts lives), not to the .squad/ directory itself.

Verify the fix:

squad doctor

You should see ✓ teamRoot is relative or no warning.

Can I use Squad CLI and GitHub Copilot CLI at the same time?

Yes! They complement each other:

  • Squad CLI provides infrastructure: triage, Aspire observability, export/import, diagnostics
  • GitHub Copilot CLI provides conversational interface to your team

Recommended setup:

  • Run squad triage --interval 10 in a dedicated terminal (or as a cron job / GitHub Action)
  • Use gh copilot (or @squad in VS Code) for all team interactions
  • Use squad doctor or squad aspire for diagnostics when needed

Both CLIs read and write the same .squad/ directory, so state stays synchronized.

What’s the difference between Ralph and triage?

Ralph and triage are different names for the same functionality:

  • squad ralph is the legacy command name
  • squad triage is the new primary command name (as of v0.8.26)
  • Both commands do the same thing: monitor GitHub issues, apply routing rules, and assign work to team members

Migration path:

  • Existing scripts using squad ralph will continue to work (it’s an alias)
  • New projects should use squad triage in documentation and automation
  • The ralph/ directory in .squad/ remains unchanged for backward compatibility

How do I add a new agent to my squad?

In conversation (recommended):

gh copilot
> @squad I want to add a new agent
> Role: Security specialist
> Name: Guardian
> Expertise: OWASP, dependency scanning, secrets detection

Squad will create the charter, update the team roster, and add routing rules.

Manual creation:

  1. Create a charter file in .squad/agents/<name>/charter.md
  2. Update .squad/team.md to include the new agent in the roster
  3. Add routing rules in .squad/routing.md (if applicable)
  4. Optionally add a history file in .squad/agents/<name>/history.md

See Team Setup for details.

What happens if I run squad init twice?

Nothing breaks! squad init is idempotent — it’s safe to run multiple times.

What it does:

  • Checks if .squad/ exists; if yes, does nothing
  • Copies missing templates to .squad/
  • Updates .github/workflows/ with Squad Actions (skips existing files)
  • Adds .github/agents/squad.agent.md if missing

Use cases:

  • Recover from partial initialization
  • Update workflows after a Squad upgrade
  • Add missing templates without overwriting custom changes

Can I use Squad without GitHub Issues?

Yes, but with limitations.

What works without GitHub Issues:

  • Conversational team interaction (@squad, gh copilot)
  • Agent spawning and parallel execution
  • Memory, decisions, and knowledge sharing
  • Skills and ceremonies
  • Export/import for portability

What requires GitHub Issues:

  • Ralph/triage auto-assignment
  • Issue-driven development workflows
  • Project board integration
  • Label-based routing
  • Copilot coding agent auto-assignment

If you’re using GitLab, see GitLab Issues for integration options.

How do I reset my squad without losing decisions?

Option 1: Archive and start fresh

# Export current state
squad export --out backup-$(date +%Y%m%d).json

# Remove .squad/
rm -rf .squad/

# Reinitialize
squad init

Manually copy decisions from the backup JSON or .squad/decisions.md if you archived it separately.

Option 2: Selective cleanup

# Remove agent state but keep team structure
rm -rf .squad/agents/*/history.md
rm -rf .squad/sessions/

# Keep .squad/decisions.md, .squad/team.md, .squad/routing.md

See Disaster Recovery for more recovery patterns.

Where should I report bugs or request features?

Open an issue on GitHub with:

  • Environment: OS, Node.js version, Squad version (squad --version)
  • Reproduction steps: What you ran, what happened, what you expected
  • Output: Copy the full terminal output, including any errors

For questions or discussions, use GitHub Discussions.

Edit this page on GitHub