Health Check

​

Run Health Check

claudedev health-check

🔍 Running Health Check...

┌───────────────────────┐
│  SYSTEM REQUIREMENTS  │
└───────────────────────┘
✅ Operating System     │ macOS 14.2.1 (compatible)
✅ Node.js Version      │ v20.10.0 (compatible)
✅ Memory Available     │ 16.0GB total, 8.5GB free (sufficient)
✅ Network Connection   │ Connected to Anthropic API
✅ Shell Environment    │ zsh (excellent autocompletion support)

┌─────────────────────┐
│  CLAUDE CODE SETUP  │
└─────────────────────┘
✅ Installation         │ v2.1.0 (globally installed)
✅ Authentication       │ Authenticated via OAuth (user@example.com)
✅ Auto-updates         │ Auto-updates assumed enabled
✅ Permissions          │ Claude directory permissions OK

┌─────────────────┐
│  PROJECT SETUP  │
└─────────────────┘
✅ Project Structure    │ Valid project detected (package.json, .git)
✅ Configuration Files  │ Found .claude/ directory with 12 files
✅ User Settings        │ Valid user settings (5 hooks, MCP auto-approve: true)
✅ Project Settings     │ Valid project settings (3 agents, 2 commands)
⚠️  Local Settings       │ No local settings found (.claude/settings.local.json)

📊 Health Score: 23/24 checks passed (96%)

💡 Recommendations:
   • Consider creating .claude/settings.local.json for machine-specific settings

​

Check Categories

​

1. System Requirements:lines/health-check.js:70

• Validates platform (macOS, Linux, Windows)
• Checks OS version compatibility
• Supported: macOS 10.15+, Linux 20.04+, Windows 10+

• Requires Node.js 18 or higher
• Displays current version
• Warns if outdated

• Checks total and free memory
• Recommends 4GB+ RAM
• Shows current usage

• Tests connection to api.anthropic.com
• 5-second timeout
• Detects slow connections

• Identifies current shell (bash, zsh, fish)
• Recommends zsh for autocompletion
• Checks $SHELL environment variable

​

2. Claude Code Setup:lines/health-check.js:109

• Checks local node_modules/@anthropic-ai/claude-code
• Checks global claude command
• Displays version

• Reads ~/.claude.json
• Checks OAuth account (email)
• Checks API key
• Validates ANTHROPIC_API_KEY env var

• Placeholder check
• Assumes enabled by default

• Validates ~/.claude directory access
• Checks write permissions
• Ensures directory exists

​

3. Project Setup:lines/health-check.js:142

• Looks for project indicators:
  • package.json (Node.js)
  • requirements.txt (Python)
  • Cargo.toml (Rust)
  • go.mod (Go)
  • .git (Git repository)
  • README.md

• Checks .claude/ directory exists
• Counts files in directory
• Lists configuration files

• Reads ~/.claude/settings.json
• Validates JSON syntax
• Analyzes structure:lines/health-check.js:1197
  • Permissions (allow/deny rules)
  • Hooks configuration
  • Environment variables
  • Model settings
  • MCP auto-approval

• Reads .claude/settings.json
• Validates JSON syntax
• Same structure analysis as user settings

• Reads .claude/settings.local.json
• Optional file for machine-specific config
• Validates JSON syntax

​

4. Agents:lines/health-check.js:181

• Scans .claude/agents/ directory
• Recursively counts .md files
• Reports total agent count

• Scans ~/.claude/agents/ directory
• Recursively counts .md files
• Reports total agent count

• Validates frontmatter presence
• Checks for name: field
• Checks for description: field
• Reports malformed agents

​

5. Custom Commands:lines/health-check.js:229

• Scans .claude/commands/ directory
• Counts .md files
• Reports total command count

• Scans ~/.claude/commands/ directory
• Counts .md files
• Reports total command count

• Checks for $ARGUMENTS placeholder
• Reports commands missing placeholder
• Essential for parameter handling

​

6. MCP Servers:lines/health-check.js:208

• Reads .mcp.json in project
• Counts configured servers
• Validates mcpServers object

• Validates each server configuration
• Required fields:
  • command: Executable path
• Optional fields:
  • args: Array of arguments
  • env: Object of environment variables
• Reports invalid configurations

​

7. Hooks:lines/health-check.js:256

• Reads ~/.claude/settings.json
• Extracts hooks array
• Counts configured hooks

• Reads .claude/settings.json
• Extracts hooks array
• Counts configured hooks

• Reads .claude/settings.local.json
• Extracts hooks array
• Counts configured hooks

• Validates each hook command exists
• Checks if command is executable
• Validates shell builtins:lines/health-check.js:1080
  • echo, cd, pwd, test, etc.
• Uses command -v to check existence:lines/health-check.js:1089

• Placeholder for future validation
• Currently returns warning

​

Status Indicators

• ✅ Pass: Check completed successfully
• ⚠️ Warn: Non-critical issue found
• ❌ Fail: Critical issue requiring attention

​

Health Score

const percentage = Math.round((passedChecks / totalChecks) * 100);

• 90-100%: Excellent
• 80-89%: Good
• 70-79%: Fair
• Below 70%: Needs attention

​

Recommendations

• “Consider switching to Zsh for better autocompletion”
• “Add $ARGUMENTS placeholder to command files”
• “Add proper frontmatter to agent files”
• “Create .claude/agents/ directory”
• “Create .mcp.json for MCP servers”
• “Fix JSON syntax errors in configuration”

​

Post-Check Setup

Would you like to run the Project Setup? (Y/n)

​

Usage Patterns

​

New Project Setup

cd my-new-project
claudedev health-check
# Review results
# Accept setup prompt

​

Pre-deployment Check

claudedev health-check
# Ensure 100% pass rate
# Fix any warnings
# Commit configuration

​

Troubleshooting

claudedev health-check > health-report.txt
# Share report with team
# Review specific failures

​

API Usage

const { HealthChecker, runHealthCheck } = require('./health-check');

// Create checker instance
const checker = new HealthChecker();

// Run specific checks
const osInfo = checker.checkOperatingSystem();
const nodeInfo = checker.checkNodeVersion();

// Run full health check
const results = await runHealthCheck();
console.log(`Health Score: ${results.percentage}%`);

​

Configuration Validation

• allow rules (array)
• deny rules (array)
• additionalDirectories (array)

• Valid hook types: PreToolUse, PostToolUse, Stop, Notification
• Hook structure validation

• Lists env vars
• Warns on sensitive vars in project settings:
  • ANTHROPIC_API_KEY
  • ANTHROPIC_AUTH_TOKEN

• enableAllProjectMcpServers setting
• enabledMcpjsonServers array
• disabledMcpjsonServers array

• model: Model selection
• cleanupPeriodDays: Conversation cleanup (must be ≥ 1)
• apiKeyHelper: API key management

​

Example: Automated CI Check

#!/bin/bash
# ci-health-check.sh

claudedev health-check > health-check.txt

# Extract health score
SCORE=$(grep "Health Score" health-check.txt | \
  grep -oE '[0-9]+%' | \
  sed 's/%//')

if [ "$SCORE" -lt 80 ]; then
  echo "Health check failed: $SCORE%"
  cat health-check.txt
  exit 1
fi

echo "Health check passed: $SCORE%"
exit 0

​

Troubleshooting

​

Authentication Fails

1. Run claude login to authenticate
2. Set ANTHROPIC_API_KEY environment variable
3. Create ~/.claude.json with OAuth credentials

​

Permission Denied

chmod 755 ~/.claude
chmod 644 ~/.claude/settings.json

​

Invalid JSON Syntax

jq . .claude/settings.json
# Fix reported syntax errors

​

Hook Command Not Found

1. Executable: chmod +x my-script
2. In PATH or use absolute path
3. Shell builtin or installed command

​

See Also

• Stats Tools - Analyze commands, hooks, and MCPs
• Analytics Dashboard - Runtime analytics
• Plugin Dashboard - Plugin management