Run agent diagnostics
This guide shows you how to run diagnostics on an agent’s environment.
What is agent doctor?
Section titled “What is agent doctor?”Agent doctor is a diagnostic tool that checks whether an agent’s execution environment is healthy. It verifies the sandbox, CLI tools, database, network, and disk.
Run diagnostics
Section titled “Run diagnostics”- Navigate to Agents
- Click the context menu (···) on an agent
- Select Run diagnostics
- Wait for the report to generate
You can also run doctor via the MCP doctor tool.
Diagnostic checks
Section titled “Diagnostic checks”The doctor report (DoctorReport) contains multiple DiagnosticResult entries:
| Check | What it verifies |
|---|---|
| Sandbox backend | The native sandbox (Seatbelt/bubblewrap) is available and functional |
| Database | SQLite is accessible, foreign keys are on, integrity is OK |
| CLI tools | The agent’s adapter CLI is installed and in PATH |
| Adapter version | The CLI reports a compatible version |
| Disk space | Sufficient disk space for worktrees and logs |
| Network | The agent can reach required external APIs (GitHub, Linear) |
Each check has a status:
- Pass — everything is fine
- Warning — non-critical issue (e.g. low disk space)
- Error — critical issue that will prevent the agent from running
Auto-repair
Section titled “Auto-repair”Some diagnostic results have canAutoRepair: true. For these:
- The doctor shows a Repair button
- Click it to apply the fix automatically
- Re-run diagnostics to verify
Common auto-repairable issues:
- Missing directory structures
- Stale cache entries
- Stuck run logs
Common issues
Section titled “Common issues”Adapter CLI not found
Section titled “Adapter CLI not found”Symptom: “CLI not found in PATH”
Fix: Install the CLI (e.g. npm install -g @anthropic-ai/claude-code) or register the adapter path manually in Settings → Adapters.
Sandbox unavailable
Section titled “Sandbox unavailable”Symptom: “Native sandbox backend not detected”
Fix: On macOS, ensure System Integrity Protection is enabled. On Linux, install bubblewrap (sudo apt install bubblewrap on Debian/Ubuntu).
Database integrity error
Section titled “Database integrity error”Symptom: “Database integrity check failed”
Fix: This is rare. Try restarting Control Center. If the error persists, the database may be corrupted — check the logs for details.
Network timeout
Section titled “Network timeout”Symptom: “Cannot reach api.github.com”
Fix: Check your network connection and proxy settings. If behind a corporate proxy, configure the proxy in the app’s network settings.