AGENT SKILL

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 swarm
  • spawn-agent-lib.sh - Core spawning library

04 同仓库更多 Skills

stevengonsalvez
stevengonsalvez/ainb-toolkit

well-formed

Fixture skill that satisfies every mechanical rule, used to prove the conformance check passes a clean tree instead of failing everything.

★ 1
stevengonsalvez
stevengonsalvez/ainb-toolkit

underscore-tools

Fixture skill that spells the tool allowlist key with an underscore instead of the hyphen the spec requires.

★ 1
stevengonsalvez
stevengonsalvez/ainb-toolkit

no-frontmatter

暂无简介

★ 1
stevengonsalvez
stevengonsalvez/ainb-toolkit

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.

★ 1
stevengonsalvez
stevengonsalvez/ainb-toolkit

some-other-name

Fixture skill whose frontmatter name does not match its parent directory name.

★ 1
stevengonsalvez
stevengonsalvez/ainb-toolkit

bad_Name

Fixture skill whose name uses an underscore and a capital letter, so it violates the agentskills.io name pattern.

★ 1