# Debug

> Diagnose and fix issues with the Pibox container environment — tools, paths, mounts, pi configuration.

- Skill: `rcarmo/debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rcarmo/debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rcarmo/debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: rcarmo (https://skillmd.com/u/rcarmo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rcarmo/debug

---


# Debug

Use this skill to diagnose and fix Pibox container issues.

## Steps

1. Check system basics:
   ```bash
   uname -a && cat /etc/os-release | head -3
   whoami && id
   df -h / /workspace /home/agent 2>/dev/null
   free -h
   ```

2. Check tool availability:
   ```bash
   for cmd in bun brew git rg make pi vim tmux htop jq curl; do
     printf "%-8s " "$cmd"; which "$cmd" 2>/dev/null && "$cmd" --version 2>/dev/null | head -1 || echo "NOT FOUND"
   done
   ```

3. Check pi configuration:
   ```bash
   echo "=== Global skills ===" && ls ~/.pi/agent/skills/ 2>/dev/null || echo "none"
   echo "=== Global settings ===" && cat ~/.pi/agent/settings.json 2>/dev/null || echo "none"
   echo "=== Project AGENTS.md ===" && head -5 AGENTS.md 2>/dev/null || echo "none"
   echo "=== Project skills ===" && ls .pi/skills/ 2>/dev/null || echo "none"
   ```

4. Check piclaw (if running):
   ```bash
   echo "=== Piclaw ===" && pgrep -af "bun.*piclaw" || echo "not running"
   ls -la data/ipc/ 2>/dev/null || echo "no IPC directory"
   ```

5. Report the findings and suggest fixes.

## Common Issues

- *bun not found:* `source ~/.bashrc` or check `~/.bun/bin` is in PATH
- *brew not found:* `eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"`
- *pi not found:* `bun add -g @earendil-works/pi-coding-agent`
- *Permission denied:* `sudo chown -R agent:agent /workspace`
- *Config not persisting:* Check `/config` volume is mounted and `~/.pi` is symlinked