npx github:bradygaster/squad appears to hang when no SSH agent is running

[dnoriegagoodwin]

Summary

npx github:bradygaster/squad appears to hang indefinitely when the user has no active SSH agent. The npm progress spinner overwrites the SSH passphrase prompt, making it invisible.

Root Cause

npm resolves github:bradygaster/squad to git+ssh://git@github.com/bradygaster/squad.git. When no SSH agent is available, git prompts for the key passphrase on the TTY. npm's progress spinner animation characters (⠙⠹⠸⠼...) overwrite the prompt, so the user sees what looks like a frozen spinner instead of a password request.

This happens at the npm/npx transport layer — Squad's index.js never executes.

Reproduction

# Simulate missing SSH agent (unset the socket)
env -u SSH_AUTH_SOCK npx github:bradygaster/squad --version

Expected: SSH passphrase prompt is visible and answerable
Actual: Spinner buries the prompt — output looks like:

⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋Enter passphrase for key '/home/user/.ssh/id_ed25519': ⠙⠹⠸⠼⠴⠦⠧⠇⠏⠋⠙⠹⠸...

Workarounds

Option 1 — Disable npm spinner:

npx --progress=false github:bradygaster/squad

This lets the passphrase prompt display cleanly.

Option 2 — Start SSH agent first:

eval "$(ssh-agent -s)" && ssh-add ~/.ssh/id_ed25519
npx github:bradygaster/squad

This loads the key into memory so git never prompts.

Proposed Fix

Document the SSH agent requirement and --progress=false workaround in the README (Known Limitations and Install sections). The underlying issue is in npm's TTY handling, not in Squad code.

[bradygaster]

Great catch, @dnoriegagoodwin — this is one of the best bug reports we've gotten. You nailed the root cause analysis and gave us clear reproduction steps and workarounds. That's exactly what we need.

We know this is an npm spinner issue, not Squad code itself, but it's real friction for users with SSH keys. We're addressing it head-on: shipping an update to the README with a Known Limitations section, adding notes to the install guide, and including a troubleshooting page that walks users through the workaround.

A PR is coming soon to land these docs. Thanks for bringing this to our attention and for the thoughtful report.

[bradygaster]

Docs shipped — README Known Limitations, install guide notes, and troubleshooting page all cover the SSH agent workaround. Closing.