swarm-agent-troubleshooting

Diagnose swarm agent startup failures and recover stuck tmux sessions.

Updated Apr 10, 2026

Search Tags:#troubleshooting #claude #agent #tmux #swarm #startup #container

Ready to run

npx skills add https://github.com/stevengonsalvez/nanoclaw-standalone --skill swarm-agent-troubleshooting

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: swarm-agent-troubleshooting
Source: https://github.com/stevengonsalvez/nanoclaw-standalone/tree/main/container/skills/swarm-agent-troubleshooting
Command: npx skills add https://github.com/stevengonsalvez/nanoclaw-standalone --skill swarm-agent-troubleshooting

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Diagnose and fix swarm agent spawn failures when agents fail to start processing tasks.

Core Features & Use Cases

Guided diagnosis of common startup issues for swarm agents, with steps to attach to sessions, check prompts, and verify Claude readiness.
Manual recovery steps to regain agent operation, upgrade shell prompts, and ensure task delivery.
Use cases include stuck tmux sessions, non-responsive agents, and timeouts in wait_for_claude_ready.

Quick Start

Attach to the swarm agent session and follow the guided recovery steps to restore Claude readiness.

Frequently Asked Questions about swarm-agent-troubleshooting

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I fix a swarm agent that is stuck at a tmux shell prompt?▼

To fix a swarm agent stuck at a tmux shell prompt, you need to diagnose startup failures by attaching to the session, inspecting outputs, and triggering manual recovery steps to restore agent readiness.

Why does wait_for_claude_ready timeout when spawning swarm agents?▼

The wait_for_claude_ready timeout occurs when swarm agents fail to start processing tasks, requiring a guided diagnosis of the tmux session environment and manual recovery to stabilize operation.

What is the best way to diagnose non-responsive swarm agents in containers?▼

Diagnosing non-responsive swarm agents involves listing tmux sessions, attaching to the correct agent, checking shell prompts, and verifying environment configurations to identify the startup failure.

Can I manually recover a swarm agent tmux session without restarting the container?▼

Yes, you can manually recover a swarm agent tmux session by attaching to it, inspecting the current state, and applying guided procedural steps to upgrade shell prompts and ensure task delivery.

How do I check if my swarm agent environment is preventing Claude from becoming ready?▼

Checking swarm agent readiness involves attaching to the specific tmux session, inspecting diagnostic outputs, and performing environment checks to identify issues blocking Claude startup.