
Workspace Doctor
- 1 installs
- 9 repo stars
- Updated January 25, 2026
- patricio0312rev/workspaces
Checks workspace prerequisites, verifies required tools, and runs health checks for workspace services from WORKSPACE.md.
About
Verifies prerequisites and required tools then runs health checks for workspace services defined in WORKSPACE.md. A developer uses it to confirm a multi-repo workspace is correctly set up and healthy.
- Parses Prerequisites and Health Checks sections from WORKSPACE.md
- Verifies git, curl/wget and jq availability
Workspace Doctor by the numbers
- 1 all-time installs (skills.sh)
- Ranked #2,479 of 3,282 Productivity & Planning skills by installs in the Skillselion catalog
- Data as of Aug 4, 2026 (Skillselion catalog sync)
npx skills add https://github.com/patricio0312rev/workspaces --skill workspace-doctorAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 1 |
|---|---|
| repo stars | ★ 9 |
| Last updated | January 25, 2026 |
| Repository | patricio0312rev/workspaces ↗ |
What it does
Checks workspace prerequisites, verifies required tools, and runs health checks for workspace services from WORKSPACE.md.
Files
Skill: Workspace Doctor
Description
Check prerequisites, verify installations, and run health checks for workspace services.
Instructions
When the user wants to check workspace health:
Step 1: Check Prerequisites
Parse the ## Prerequisites section from WORKSPACE.md:
## Prerequisites
- Node.js 20+
- Docker & Docker Compose
- PostgreSQL 15+ (or use Docker)Verify each prerequisite is installed and meets version requirements.
Step 2: Check Required Tools
Always verify these tools are available:
git- Version controlcurlorwget- HTTP requestsjq- JSON processing (optional but recommended)
Step 3: Run Health Checks
Parse the ## Health Checks section:
## Health Checks
api: curl -s http://localhost:3000/health | grep -q "ok"
admin: curl -s http://localhost:3001 | grep -q "<!DOCTYPE"Run each check and report results.
Step 4: Display Results
🩺 Workspace Doctor - Acme Corp
Prerequisites:
✓ Node.js 22.0.0 (required: 20+)
✓ Docker 24.0.6
✓ Docker Compose 2.21.0
✗ PostgreSQL not found (install or use Docker)
Tools:
✓ git 2.42.0
✓ curl 8.1.2
✓ jq 1.7
Projects:
✓ api - cloned at ~/work/acme/api
✓ admin - cloned at ~/work/acme/admin
✗ homepage - not cloned
Health Checks:
✓ api - healthy (http://localhost:3000/health)
○ admin - not running (port 3001)
Summary:
• 2 issues found
Recommendations:
• Clone missing projects: /workspaces:clone all
• Start services: /workspaces:start allStatus Icons
✓- Passed✗- Failed (blocking)○- Warning (non-blocking)
#!/bin/bash
# Workspace doctor - check prerequisites and health
set -e
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PLUGIN_DIR="$(cd "$SCRIPT_DIR/../../.." && pwd)"
# Source utilities
source "$PLUGIN_DIR/lib/workspace-utils.sh"
# Track issues
ISSUES=0
WARNINGS=0
# Check a command exists and optionally verify version
check_command() {
local cmd="$1"
local required_version="$2"
local version_flag="${3:---version}"
if ! command -v "$cmd" &> /dev/null; then
print_error "$cmd not found"
((ISSUES++))
return 1
fi
local version=$($cmd $version_flag 2>&1 | head -1 | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' | head -1)
if [ -n "$required_version" ]; then
# Simple version comparison (major version only)
local required_major=$(echo "$required_version" | cut -d. -f1 | tr -d '+')
local actual_major=$(echo "$version" | cut -d. -f1)
if [ "$actual_major" -lt "$required_major" ] 2>/dev/null; then
print_warning "$cmd $version (required: $required_version)"
((WARNINGS++))
return 0
fi
fi
print_success "$cmd $version"
return 0
}
# Check optional command
check_optional_command() {
local cmd="$1"
local description="$2"
if command -v "$cmd" &> /dev/null; then
local version=$($cmd --version 2>&1 | head -1 | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' | head -1)
print_success "$cmd $version"
else
echo -e " ${YELLOW}○${NC} $cmd not found - $description"
((WARNINGS++))
fi
}
# Run a health check command
run_health_check() {
local name="$1"
local check="$2"
if eval "$check" 2>/dev/null; then
print_success "$name - healthy"
return 0
else
echo -e " ${YELLOW}○${NC} $name - check failed"
((WARNINGS++))
return 1
fi
}
# Detect workspace
detected=$(detect_workspace)
if [ -z "$detected" ]; then
print_error "No workspace detected"
exit 1
fi
WORKSPACE_NAME=$(echo "$detected" | cut -d: -f1)
CONFIG_FILE=$(get_workspace_config "$WORKSPACE_NAME")
# Get workspace display name
DISPLAY_NAME=$(grep -E "^name:" "$CONFIG_FILE" | head -1 | sed 's/^name:[ ]*//')
[ -z "$DISPLAY_NAME" ] && DISPLAY_NAME="$WORKSPACE_NAME"
echo ""
echo "🩺 Workspace Doctor - $DISPLAY_NAME"
echo ""
# Check required tools
echo "Tools:"
check_command "git"
check_command "curl"
check_optional_command "jq" "JSON processing will be limited"
check_optional_command "rg" "search will use grep instead"
echo ""
# Check prerequisites from config
echo "Prerequisites:"
prereqs=$(sed -n '/^## Prerequisites/,/^## /p' "$CONFIG_FILE" | grep -E '^- ' | sed 's/^- //')
if [ -n "$prereqs" ]; then
while IFS= read -r prereq; do
# Parse prerequisite (e.g., "Node.js 20+")
tool=$(echo "$prereq" | awk '{print $1}')
version=$(echo "$prereq" | grep -oE '[0-9]+\+?' | head -1)
case "$tool" in
Node.js|node)
check_command "node" "$version" "--version"
;;
Docker)
check_command "docker" "" "--version"
;;
docker-compose|"Docker Compose")
check_command "docker-compose" "" "--version" || check_command "docker" "" "compose version"
;;
PostgreSQL|psql)
check_command "psql" "$version" "--version" || echo -e " ${YELLOW}○${NC} PostgreSQL not found (may use Docker)"
;;
*)
# Try to check the tool directly
cmd=$(echo "$tool" | tr '[:upper:]' '[:lower:]')
check_optional_command "$cmd" "$prereq"
;;
esac
done <<< "$prereqs"
else
echo " No prerequisites defined in WORKSPACE.md"
fi
echo ""
# Check projects
echo "Projects:"
while IFS='|' read -r name repo path stack port; do
[ -z "$name" ] && continue
expanded_path=$(expand_path "$path")
if [ -d "$expanded_path" ]; then
print_success "$name - cloned at $path"
else
print_error "$name - not cloned"
((ISSUES++))
fi
done < <(parse_projects "$CONFIG_FILE")
echo ""
# Run health checks
echo "Health Checks:"
health_section=$(sed -n '/^## Health Checks/,/^## /p' "$CONFIG_FILE" | grep -E '^[a-zA-Z]' | grep -v '^## ')
if [ -n "$health_section" ]; then
while IFS=: read -r name check; do
[ -z "$name" ] && continue
check=$(echo "$check" | sed 's/^[ ]*//')
# Get project path and port
project_info=$(get_project_info "$CONFIG_FILE" "$name")
if [ -z "$project_info" ]; then
continue
fi
port=$(echo "$project_info" | cut -d'|' -f5)
path=$(echo "$project_info" | cut -d'|' -f3)
expanded_path=$(expand_path "$path")
# Check if project is cloned
if [ ! -d "$expanded_path" ]; then
echo -e " ${YELLOW}○${NC} $name - not cloned"
((WARNINGS++))
continue
fi
# Check if service is running (by port)
if [ -n "$port" ] && [ "$port" != "-" ]; then
if ! port_in_use "$port"; then
echo -e " ${YELLOW}○${NC} $name - not running (port $port)"
((WARNINGS++))
continue
fi
fi
# Run the health check
run_health_check "$name" "$check"
done <<< "$health_section"
else
echo " No health checks defined in WORKSPACE.md"
fi
echo ""
# Summary
echo "Summary:"
if [ $ISSUES -eq 0 ] && [ $WARNINGS -eq 0 ]; then
print_success "All checks passed!"
else
if [ $ISSUES -gt 0 ]; then
print_error "$ISSUES issue(s) found"
fi
if [ $WARNINGS -gt 0 ]; then
print_warning "$WARNINGS warning(s)"
fi
fi
echo ""
# Recommendations
if [ $ISSUES -gt 0 ] || [ $WARNINGS -gt 0 ]; then
echo "Recommendations:"
# Check for uncloned projects
uncloned=$(parse_projects "$CONFIG_FILE" | while IFS='|' read -r name repo path stack port; do
expanded_path=$(expand_path "$path")
[ ! -d "$expanded_path" ] && echo "$name"
done)
if [ -n "$uncloned" ]; then
echo " • Clone missing projects: /workspaces:clone all"
fi
# Check for stopped services
stopped=$(parse_projects "$CONFIG_FILE" | while IFS='|' read -r name repo path stack port; do
[ -z "$port" ] || [ "$port" = "-" ] && continue
expanded_path=$(expand_path "$path")
[ -d "$expanded_path" ] && ! port_in_use "$port" && echo "$name"
done)
if [ -n "$stopped" ]; then
echo " • Start services: /workspaces:start all"
fi
echo ""
fi