System Health Check

Overview

This skill guides you through checking the health of your Overdeck installation, including configuration, dependencies, and running services.

When to Use

• After initial installation
• Troubleshooting agent issues
• Before starting a new work session
• Verifying configuration changes
• Periodic maintenance

Quick Command

pan doctor

Health Check Workflow

1. Run Diagnostics

# Full health check
pan doctor

# Expected output:
# ✓ Configuration file exists
# ✓ Linear API key configured
# ✓ GitHub token configured
# ✓ Skills directory exists
# ✓ tmux available
# ✓ Docker available
# ⚠ orphan-proposed-specs: proposed xBRIEF specs without work agents, grouped by project with remediation hints

2. Check Configuration

# View current config
cat ~/.overdeck.env

# Required settings:
# LINEAR_API_KEY=lin_api_xxx
# GITHUB_TOKEN=ghp_xxx (optional but recommended)
# WORKSPACE_ROOT=/path/to/workspaces

3. Check Running Services

# Dashboard status
curl -s http://localhost:3011/api/health || echo "Dashboard not running"

# Running agents
tmux list-sessions | grep agent

# Docker containers
docker ps --format "table {{.Names}}\t{{.Status}}" | grep -E "(traefik|overdeck)"

4. Check Skills

# List installed skills
pan skills

# Verify skills are synced
ls -la ~/.claude/skills/ | head -20

5. Check Dependencies

# Node.js version (18+ required)
node --version

# npm version
npm --version

# tmux version
tmux -V

# Docker version
docker --version

# Git version
git --version

6. Herdr

Herdr is the default terminal backend and is strict: when it is selected but its binary or this home's
session socket is missing, agent launches fail and pan doctor exits 1. Doctor prints these rows:

Row	Fix when it fails
Terminal backend	pan install (or set terminal.backend: tmux in ~/.overdeck/config.yaml)
Herdr binary	pan install
Herdr server	pan sync (restarting a stale server is manual: systemctl --user restart overdeck-herdr.service closes every agent pane)
Herdr config	pan sync (sets resume_agents_on_restore = false)
Herdr integration: <target>	pan sync (pilot set pi, omp, kimi, opencode; claude, codex, hermes are not managed)

Under an explicit tmux backend only the Terminal backend row appears.

7. Plan home .pan/ tracking

Planning artifacts are committed under .pan/ in each project's plan home. Before the Cut, Overdeck
wrote .pan/ into project .gitignore files, and that rule makes every planning commit fail
(The following paths are ignored by one of your .gitignore files: .pan). The
Plan home .pan/ tracking row WARNs for each registered plan home where git check-ignore matches
.pan/, naming the rule's file:line:

Rule source	Fix
Exact .pan/ or .pan line in the repo's top-level .gitignore (Overdeck's legacy line)	pan admin migrate-plan-home <key> --repair-ignore removes that line and commits .gitignore alone (no migration, no tracker lookup), or delete the line and commit it yourself
Anything else (nested .gitignore, .git/info/exclude, core.excludesFile, a broader pattern)	Not Overdeck's rule: doctor never edits it. Remove or narrow it yourself

Doctor only reports; it has no --fix.

8. Sync sources checkout

pan sync distributes from the primary checkout's sync-sources/ when it can. The
Sync Sources Checkout row WARNs when that checkout is behind its upstream, on a branch other
than the remote's default branch, or has a detached HEAD, because every sync would then distribute
an old tree (PAN-3881). Doctor does not fetch; it compares with the last-fetched upstream ref and
says so in the row. Fix: fetch and fast-forward the checkout on its default branch, then pan sync.
The row is skipped (OK) when sync distributes a frozen pan reload generation's own copy; the
Deployed Hooks row covers that case.

Health Checklist

Component	Check Command	Expected
Config	cat ~/.overdeck.env	File exists with keys
Node.js	node --version	v18+
tmux	tmux -V	Any version
Docker	docker info	Running
Skills	ls ~/.overdeck/skills/	Skills present
Symlinks	ls -la ~/.claude/skills/	Symlinks to overdeck
Linear	pan doctor	API key valid

Component Status

Dashboard

# Start dashboard
cd ~/.overdeck/dashboard && npm run dev

# Check health endpoint
curl http://localhost:3011/api/health

# View dashboard
open http://localhost:3010

Traefik (if using)

# Check traefik
docker ps | grep traefik

# Traefik dashboard
curl -k https://traefik.overdeck.localhost:8080/api/overview

Agents

# List all agents
tmux list-sessions -F "#{session_name}" | grep "^agent-"

# Check agent health
for session in $(tmux list-sessions -F "#{session_name}" | grep "^agent-"); do
  echo "=== $session ==="
  tmux capture-pane -t $session -p | tail -5
done

Common Issues

Configuration Missing

# Create config file
pan init

# Or manually
cat > ~/.overdeck.env << 'EOF'
LINEAR_API_KEY=your_key_here
GITHUB_TOKEN=your_token_here
WORKSPACE_ROOT=/home/user/workspaces
EOF

Skills Not Synced

# Re-sync skills
pan sync

# Force overwrite
pan sync --force

Dashboard Won't Start

# Check port in use
lsof -i :3010
lsof -i :3011

# Kill conflicting processes
kill $(lsof -t -i:3010)
kill $(lsof -t -i:3011)

# Restart
cd ~/.overdeck/dashboard && npm run dev

tmux Issues

# Kill stuck server
tmux kill-server

# Fresh start
tmux new-session -d -s test
tmux kill-session -t test

Maintenance Tasks

Update Overdeck

npm update -g overdeck
pan init  # Re-copy bundled skills
pan sync  # Re-sync to AI tools

Clean Up Old Workspaces

# List workspaces
ls -la $WORKSPACE_ROOT/

# Remove completed ones
rm -rf $WORKSPACE_ROOT/old-issue/

Reset Configuration

# Backup and reset
cp ~/.overdeck.env ~/.overdeck.env.backup
pan init

Related Skills

• /pan:diagnose - Deep troubleshooting
• /pan:install - Initial setup
• /pan:sync - Skill synchronization