Repository navigation
npx github:bradygaster/squad appears to hang when no SSH agent is running #30
Description
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 --versionExpected: 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/squadThis lets the passphrase prompt display cleanly.
Option 2 — Start SSH agent first:
eval "$(ssh-agent -s)" && ssh-add ~/.ssh/id_ed25519
npx github:bradygaster/squadThis 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.
Activity
[-]npx github:bradygaster/squad hangs when no SSH agent is running[/-][+]npx github:bradygaster/squad appears to hang when no SSH agent is running[/+]bradygaster commentedon Feb 13, 2026
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.
fix: document SSH agent requirement and workaround (#30)
bradygaster commentedon Feb 13, 2026
Docs shipped — README Known Limitations, install guide notes, and troubleshooting page all cover the SSH agent workaround. Closing.
fix: apply P0+P1 security audit findings for remote-control
feat: Squad Remote Control - PTY mirror + devtunnel for phone access (#…
Research: Squad Monitoring & Ralph Watch Reliability (GitHub Issue gi…
docs: append Issue github#30 squad-monitoring-reliability research to…