Troubleshooting

Common issues and fixes for Squad installation and usage.

Quick fixes

npx github:bradygaster/squad appears to hang

Problem: Running the install command shows a frozen npm spinner. Nothing happens.

Cause: npm resolves github: package specifiers via git+ssh://git@github.com/.... If no SSH agent is running (or your key isn’t loaded), git prompts for your passphrase on the TTY — but npm’s progress spinner overwrites the prompt, making it invisible. This is an npm TTY handling issue, not a Squad bug.

Fix (choose one):

1. Start your SSH agent first (recommended):

   eval "$(ssh-agent -s)"
   ssh-add

   Then re-run npx github:bradygaster/squad.

2. Disable npm’s progress spinner to reveal the prompt:

   npx --progress=false github:bradygaster/squad

3. Use HTTPS instead of SSH by configuring git:

   git config --global url."https://github.com/".insteadOf git@github.com:

Reference: #30

gh CLI not authenticated

Problem: GitHub Issues, PRs, Ralph, or Project Boards commands fail with authentication errors.

Cause: The gh CLI isn’t logged in, or is missing required scopes.

Fix:

1. Log in:

   gh auth login

2. If using Project Boards, add the project scope:

   gh auth refresh -s project

3. Verify:

   gh auth status

Authentication fails on cross-org repos

Problem: Squad agents hit authentication errors when working with repositories across personal GitHub and GitHub Enterprise Managed Users (EMU) organizations.

Cause: The gh CLI and git credentials are tied to one account at a time. When you switch contexts between personal and EMU repos, the active account may not have access to the target repository.

Fix:

1. Use gh auth switch to toggle between authenticated accounts:

   gh auth status
   gh auth switch --user <username>

2. Add account mappings to .github/copilot-instructions.md so Squad agents know which account to use for which repos.

3. Configure git credential helpers per host or organization.

See Cross-organization authentication for detailed setup instructions.

Node.js version too old

Problem: npx github:bradygaster/squad fails with an engine compatibility error, or Squad behaves unexpectedly.

Cause: Squad requires Node.js 20.0.0 or later (LTS), enforced via engines in package.json.

Fix:

node --version

If below v20, upgrade to the latest LTS:

• nvm (macOS/Linux): nvm install --lts && nvm use --lts
• nvm-windows: nvm install lts && nvm use lts
• Direct download: nodejs.org

Squad agent not appearing in Copilot

Problem: After install, squad doesn’t show up in the /agent (CLI) or /agents (VS Code) list in GitHub Copilot.

Cause: The .github/agents/squad.agent.md file may not have been created, or Copilot hasn’t refreshed its agent list.

Fix:

1. Verify the file exists:

   ls .github/agents/squad.agent.md

   If missing, re-run npx github:bradygaster/squad.

2. Restart your Copilot session — close and reopen the terminal or editor.

Upgrade doesn’t change anything

Problem: Running npx github:bradygaster/squad upgrade completes but nothing changes.

Cause: You may already be on the latest version, or npm cached an old version.

Fix:

1. Check current version in .github/agents/squad.agent.md (frontmatter version: field).

2. Clear npm cache and retry:

   npx --yes github:bradygaster/squad upgrade

Windows-specific issues

Problem: Path errors or file operations fail on Windows.

Cause: Some shell commands assume Unix-style paths.

Fix: Squad’s core uses path.join() for all file operations and is Windows-safe. If you see path issues:

• Use PowerShell or Git Bash (not cmd.exe)
• Ensure git is in your PATH
• Ensure gh CLI is in your PATH

”⚠ squad pre-commit: refusing to commit two-layer state into the working tree”

Problem: A git commit is blocked with the message above.

Cause: You’re on the orphan or two-layer backend, and one or more state files (.squad/decisions.md, .squad/agents/*/history.md, .squad/casting/, .squad/routing/) were staged for commit. These files belong on the squad-state orphan branch, not in your working branch. Something wrote them back to disk after the migration — a direct fs.writeFile call, an editor auto-save, or an external tool — and you staged them unintentionally.

Recovery flow:

1. Unstage the state files:

   git restore --staged .squad/decisions.md
   git restore --staged ".squad/agents/*/history.md"

2. Check whether the orphan branch already has the content (it should, if squad sync has run):

   git show squad-state:decisions.md
   git show squad-state:agents/<agent-name>/history.md

3. If the working-tree copy contains new content not yet on the orphan branch, lift it through Squad before deleting:

   squad memory write --file .squad/decisions.md

4. Remove the working-tree copies:

   # PowerShell
   Remove-Item .squad\decisions.md -ErrorAction SilentlyContinue
   Get-ChildItem .squad\agents -Recurse -Filter history.md | Remove-Item

   # bash
   rm -f .squad/decisions.md .squad/agents/*/history.md

5. Commit normally — the post-commit hook will call squad sync --quiet automatically:

   git commit -m "your commit message"

When to use SQUAD_SYNC_ACTIVE=1: Rarely. This env var bypasses both the pre-commit and post-commit hooks. It’s intended for internal use by squad sync itself to prevent recursion. If you set it to unblock a commit, the state files will land in your working-branch history and appear in PRs — exactly what two-layer is designed to prevent. Use the recovery flow above instead.