swarm-agent-troubleshooting
Diagnose and fix swarm agent spawn failures when agents don't start processing tasks
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 1
- Forks
- 1
01 前言 Front Matter
- name
- swarm-agent-troubleshooting
- description
- Diagnose and fix swarm agent spawn failures when agents don't start processing tasks
- user-invocable
- true
03 SKILL.md 正文
Swarm Agent Troubleshooting
Diagnose and fix swarm agent spawn failures when agents don't start processing tasks.
When to Use
- Agent tmux session created but stuck at shell prompt
- Agent not responding to inbox messages
wait_for_claude_ready()times out- Symptoms: dotenv prompt, zsh theme loading, or no Claude banner visible
Quick Diagnosis
# 1. List swarm sessions
tmux list-sessions | grep swarm
# 2. Attach to stuck agent
tmux attach -t swarm-XXXX-agent-1
# 3. Check what's showing:
# - Shell prompt (zsh/bash) = Claude didn't start
# - "dotenv: found '.env'" = Blocked by prompt
# - Claude banner = Ready (check if task was sent)
Common Causes
| Symptom | Cause | Fix |
|---|---|---|
dotenv: found '.env' file. Source it? |
dotenv plugin prompt | Send a (always) then restart claude |
| Shell prompt showing | Claude command never ran | Manually run claude --dangerously-skip-permissions |
| Claude banner but idle | Task not sent after spawn | Resend the task prompt |
| "command not found: claude" | Claude not in PATH | Check which claude or use full path |
Manual Recovery Steps
# Step 1: Attach to the stuck session
tmux attach -t swarm-XXXX-agent-1
# Step 2: If at dotenv prompt, answer it
# (type 'a' for always, then Enter)
# Step 3: If at shell, start Claude manually
claude --dangerously-skip-permissions
# Step 4: Once Claude is ready, send the task
# (paste the agent's task prompt)
# Step 5: Detach (Ctrl+B, D) and continue monitoring
Prevention
Update Shell Config
Add to ~/.zshrc or ~/.bashrc:
# Auto-accept dotenv in non-interactive contexts
export DOTENV_ASSUME_YES=1
Increase Detection Timeout
In spawn-agent-lib.sh, increase the timeout:
wait_for_claude_ready "$SESSION" 60 # Increase from 30 to 60 seconds
Add Detection Patterns
The wait_for_claude_ready() function looks for these patterns:
- "Claude Code"
- "Welcome back"
- "──────" (horizontal rule)
- "Style:"
- "bypass permissions"
If your terminal has different output, add patterns to the grep regex.
Debug Logs
Failed spawn attempts save debug output:
cat /tmp/spawn-agent-swarm-XXXX-agent-1-failure.log
Related
/swarm-status- Check overall swarm health/swarm-shutdown- Clean up stuck swarmspawn-agent-lib.sh- Core spawning library
04 同仓库更多 Skills
well-formed
Fixture skill that satisfies every mechanical rule, used to prove the conformance check passes a clean tree instead of failing everything.
underscore-tools
Fixture skill that spells the tool allowlist key with an underscore instead of the hyphen the spec requires.
no-frontmatter
暂无简介
long-description
Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling.
some-other-name
Fixture skill whose frontmatter name does not match its parent directory name.
bad_Name
Fixture skill whose name uses an underscore and a capital letter, so it violates the agentskills.io name pattern.