Self-Healing AI Agents

Q: What is YOLO mode in amux?

YOLO mode (--yolo flag) auto-approves all Claude Code tool calls, preventing the tool-approval stuck failure mode entirely. Enable it with: amux register myproject --dir ~/Dev/myproject --yolo, or set YOLO=1 in ~/.amux/server.env.

Q: How do I configure the context threshold for auto-compact?

Set WATCHDOG_CONTEXT_THRESHOLD in ~/.amux/server.env as a percentage (0-100). The default is 20, meaning amux sends /compact when Claude Code's context falls below 20% remaining capacity. Lower values trigger compaction later; higher values trigger it earlier.

Q: Can amux self-healing run completely unattended overnight?

Yes. Enable YOLO mode and set your watchdog thresholds in ~/.amux/server.env, then start your agents with amux start. The watchdog handles all four failure modes — context exhaustion, thinking-block corruption, tool-approval blocks, and silent hangs — without any human intervention.

amux runs a background watchdog that recovers from every known Claude Code failure mode — automatically, overnight, without you.

// quick answer

Does amux restart Claude Code agents automatically? Yes. The watchdog monitors every session and recovers from four failure modes: context exhaustion (auto-compact), thinking-block corruption (restart + replay), tool-approval blocks (YOLO mode), and silent hangs (continue signal). Agents run unattended overnight.

The four failure modes Claude Code sessions hit

Most developers running multiple Claude Code agents overnight encounter the same four failures. amux is built around detecting and recovering from all of them automatically.

1. Context exhaustion (most common)

Claude Code has a finite context window. As a long-running session accumulates code edits, tool outputs, and conversation history, the context fills. When it reaches capacity, the session stalls — Claude can't continue because there's nowhere to put new tokens.

amux recovery: When context falls below a configurable threshold (default: 20% remaining), the watchdog automatically sends /compact. Claude Code summarizes its full context into a compressed form and continues the task from where it left off.

# Configure the threshold in ~/.amux/server.env
WATCHDOG_CONTEXT_THRESHOLD=20   # trigger /compact when below 20% remaining

2. Thinking-block corruption

Certain Claude response patterns — particularly around extended thinking — can produce malformed output that hangs the UI. The session appears to be running but produces no more output. This failure mode is silent and easy to miss in a fleet of 10+ agents.

amux recovery: The watchdog monitors output patterns. When it detects a thinking-block error signature, it kills and restarts the Claude Code process, then replays the last message sent to the session so the agent picks up where it left off.

3. Tool-approval stuck

Unless YOLO mode is enabled, Claude Code pauses at every tool call (file write, bash command, etc.) and waits for the user to press Enter to approve. In an unattended session, this pause is indefinite — the agent just stops working and waits forever.

amux recovery (YOLO mode): The --yolo flag pre-approves all tool calls at session start. This is the recommended setup for overnight or background agents — register your session with --yolo and the failure mode doesn't exist.

amux register myproject --dir ~/Dev/myproject --yolo

4. Silent hang

Sometimes Claude Code produces no output for an extended period for reasons unrelated to the above — a stuck network call, a paused subprocess, a model timeout. The session isn't crashed; it's just frozen.

amux recovery: When no output is detected for the idle timeout period (configurable), the watchdog sends a continue signal to kick the agent back into action.

# Configure in ~/.amux/server.env
WATCHDOG_IDLE_TIMEOUT=900   # 15 minutes of silence triggers a continue signal

Last-message replay

When a session is restarted after a crash or thinking-block corruption, amux replays the last message that was sent to it. This means the agent picks up the task it was working on, not a blank slate. Combined with context compaction history, agents lose very little progress even after a hard restart.

Recovery vs. manual babysitting — comparison

Failure scenario	Without amux	With amux self-healing
Context fills overnight	Agent stops; you wake up to a dead session	Auto-compact; agent continues
Thinking-block corruption	Session hangs forever; requires manual kill + restart	Detected in ~2 s; auto-restart + replay
Tool-approval prompt	Agent waits indefinitely	Auto-approve (YOLO) or continue signal
Silent hang (>15 min idle)	Session appears running but produces nothing	Watchdog sends continue signal
Process crash (exit code ≠0)	Dead session until you notice	Auto-restart within ~5 s
Replay loop detection	N/A — you'd notice manually	Restart counter; marked failed after N consecutive restarts

Configuration reference

All watchdog settings live in ~/.amux/server.env. The server reads this file at startup (and after an auto-restart).

Variable	Default	Description
`WATCHDOG_CONTEXT_THRESHOLD`	20	% context remaining that triggers auto-compact
`WATCHDOG_IDLE_TIMEOUT`	900	Seconds of silence before a continue signal is sent
`YOLO`	0	Set to 1 to auto-approve all tool calls globally

Frequently asked questions

Does amux automatically restart Claude Code when it crashes?

Yes. The amux watchdog detects process exits and automatically restarts the Claude Code session within ~5 seconds. When YOLO mode is enabled, the agent resumes where it left off without any human intervention.

What is YOLO mode?

YOLO mode (--yolo flag) auto-approves all Claude Code tool calls, preventing the tool-approval stuck failure mode entirely. Enable it with amux register myproject --dir ~/Dev/myproject --yolo, or set YOLO=1 in ~/.amux/server.env to apply globally to all sessions.

How do I configure the context threshold for auto-compact?

Set WATCHDOG_CONTEXT_THRESHOLD in ~/.amux/server.env as a percentage (0–100). The default is 20, meaning amux sends /compact when Claude Code's context falls below 20% remaining capacity. Lower values trigger compaction later (less frequent); higher values trigger it earlier (more frequent).

Can amux self-healing run completely unattended overnight?

Yes. Enable YOLO mode and set your watchdog thresholds in ~/.amux/server.env, then start your agents with amux start. The watchdog handles all four failure modes without any human intervention. Thousands of developers run amux fleets overnight this way.

What happens if last-message replay causes an infinite loop?

The amux watchdog tracks restart counts per session. After consecutive restarts without forward progress (no new output), it marks the session as failed and stops auto-restarting. The session is flagged in the dashboard with a red status dot so you can investigate manually.

Run Claude Code agents that never die overnight

amux is an open-source control plane for running an AI engineering team from a single dashboard or your phone. MIT licensed, single Python file.

git clone https://github.com/mixpeek/amux && cd amux && ./install.sh
amux register myproject --dir ~/Dev/myproject --yolo
amux start myproject
amux serve  # → https://localhost:8822

⭐ Star on GitHub Get started