Use when diagnosing burrow plugin issues, troubleshooting connection failures, checking plugin health, or when the user says 'burrow doctor', 'fix burrow', 'burrow not working', 'debug burrow', 'check burrow'. Runs all diagnostic checks and fixes problems automatically.
Diagnose and fix all known issues with the burrow plugin installation and connectivity.
Run ALL checks in order. Fix each issue before proceeding to the next.
# Check Python version (need 3.11+)
python3 --version # Must be >= 3.11
# Check uv is available
which uv || echo "PROBLEM: uv not installed — run: curl -LsSf https://astral.sh/uv/install.sh | sh"
Fix: If Python < 3.11, install via uv python install 3.11
# Find burrow installation
BURROW_DIR=""
for dir in \
"${CLAUDE_PLUGIN_ROOT:-}" \
"$HOME/.claude/plugins/burrow" \
"/workspace/burrow"; do
[ -f "$dir/burrow/protocol.py" ] && BURROW_DIR="$dir" && break
done
[ -z "$BURROW_DIR" ] && echo "PROBLEM: burrow source not found"
Fix: git clone https://github.com/slapglif/burrow.git ~/.claude/plugins/burrow
# Check venv exists and has dependencies
ls "$BURROW_DIR/.venv/bin/python" 2>/dev/null || echo "PROBLEM: no venv"
"$BURROW_DIR/.venv/bin/python" -c "import websockets; import mcp" 2>/dev/null || echo "PROBLEM: missing deps"
Fix: cd "$BURROW_DIR" && uv venv && uv pip install -e .
Gotcha: Never use uv pip install --system — externally managed Python will reject it. Always create a venv first.
cd "$BURROW_DIR" && .venv/bin/python -c "
from burrow.mcp_server import mcp
tools = list(mcp._tool_manager._tools.keys())
assert len(tools) == 7, f'Expected 7 tools, got {len(tools)}: {tools}'
print(f'OK: {len(tools)} tools registered')
" 2>&1
Expected: OK: 7 tools registered
Fix if import fails:
ModuleNotFoundError: mcp → uv pip install "mcp>=1.0"ModuleNotFoundError: burrow → uv pip install -e . (editable install)# All required files must exist
for f in \
".claude-plugin/plugin.json" \
".mcp.json" \
"burrow/mcp_server.py" \
"hooks/hooks.json" \
"skills/connect/SKILL.md" \
"skills/swarm-status/SKILL.md" \
"skills/install/SKILL.md" \
"skills/doctor/SKILL.md" \
"agents/burrow-agent.md"; do
[ -f "$BURROW_DIR/$f" ] || echo "MISSING: $f"
done
# Validate JSON files
python3 -c "import json; json.load(open('$BURROW_DIR/.claude-plugin/plugin.json'))" || echo "INVALID: plugin.json"
python3 -c "import json; json.load(open('$BURROW_DIR/.mcp.json'))" || echo "INVALID: .mcp.json"
python3 -c "import json; json.load(open('$BURROW_DIR/hooks/hooks.json'))" || echo "INVALID: hooks.json"
CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
# Check symlink
ls -la "$CLAUDE_DIR/plugins/burrow" 2>/dev/null || echo "PROBLEM: no symlink in plugins dir"
# Check installed_plugins.json
python3 -c "
import json
with open('$CLAUDE_DIR/plugins/installed_plugins.json') as f:
data = json.load(f)
if 'burrow@local' in data.get('plugins', {}):
entry = data['plugins']['burrow@local'][0]
print(f'Registered: {entry[\"installPath\"]}')