doctor Command
The doctor
command performs comprehensive health checks on your SwissArmyHammer installation and configuration. It identifies issues and provides recommendations for optimal operation.
Usage
swissarmyhammer doctor [OPTIONS]
Overview
The doctor command checks:
- Installation integrity and version compatibility
- Configuration file validity
- Prompt directory accessibility and structure
- Prompt file syntax and metadata
- MCP server functionality
- System dependencies and environment
Options
--verbose
- Description: Enable detailed output with additional diagnostic information
- Default: Disabled
- Example: Shows file paths, configuration details, and system information
swissarmyhammer doctor --verbose
--json
- Description: Output results in JSON format for programmatic use
- Default: Human-readable text output
- Example: Useful for scripts and automation
swissarmyhammer doctor --json
--fix
- Description: Automatically fix issues when possible
- Default: Report-only mode
- Example: Creates missing directories, fixes permissions
swissarmyhammer doctor --fix
--check <CATEGORY>
- Description: Run specific check categories only
- Values:
installation
,config
,prompts
,mcp
,system
- Repeatable: Can specify multiple categories
# Check only prompt-related issues
swissarmyhammer doctor --check prompts
# Check multiple categories
swissarmyhammer doctor --check config --check prompts
Check Categories
Installation Checks
Verifies SwissArmyHammer installation:
Binary Location
- Checks if
swissarmyhammer
is in PATH - Verifies executable permissions
- Confirms version compatibility
Dependencies
- Validates system requirements
- Checks for required libraries
- Verifies runtime dependencies
Example Output
✓ SwissArmyHammer binary found: /usr/local/bin/swissarmyhammer
✓ Version: 0.1.0 (latest)
✓ Executable permissions: OK
✓ System dependencies: All present
Configuration Checks
Validates configuration files and settings:
Configuration File
- Checks for valid TOML syntax
- Validates configuration schema
- Identifies deprecated settings
Directory Structure
- Verifies default directories exist
- Checks directory permissions
- Validates custom prompt directories
Environment Variables
- Lists relevant environment variables
- Checks for conflicts or inconsistencies
- Validates variable values
Example Output
✓ Configuration file: ~/.swissarmyhammer/config.toml
✓ Configuration syntax: Valid TOML
✓ Default directories: Created and accessible
⚠ Custom directory not found: /nonexistent/prompts
✓ Environment variables: No conflicts
Prompt Checks
Analyzes prompt files and library structure:
Directory Scanning
- Scans all configured prompt directories
- Counts prompt files by category
- Identifies orphaned or miscategorized files
File Validation
- Validates YAML front matter syntax
- Checks required fields presence
- Verifies argument specifications
Content Analysis
- Validates Liquid template syntax
- Checks for common template errors
- Identifies missing or broken references
Duplicate Detection
- Finds prompts with identical names
- Shows override hierarchy
- Warns about potential conflicts
Example Output
✓ Prompt directories: 3 found, all accessible
✓ Prompt files: 47 total, 45 valid
✗ Invalid prompts: 2 files with errors
- debug-helper.md: Missing required field 'description'
- code-review.md: Invalid YAML syntax on line 8
⚠ Duplicate names: 1 conflict found
- 'help' defined in both builtin and ~/.swissarmyhammer/prompts/
✓ Template syntax: All valid
MCP Checks
Tests Model Context Protocol functionality:
Server Startup
- Attempts to start MCP server
- Tests port binding
- Verifies server responds to requests
Protocol Compliance
- Validates MCP protocol responses
- Checks capability advertisements
- Tests prompt exposure format
Integration Status
- Checks Claude Code configuration
- Tests end-to-end connectivity
- Validates prompt accessibility
Example Output
✓ MCP server startup: Success on port 8080
✓ Protocol compliance: All tests passed
✓ Prompt exposure: 45 prompts available
⚠ Claude Code integration: Not configured
Run: claude mcp add swissarmyhammer swissarmyhammer serve
System Checks
Analyzes system environment and performance:
Operating System
- Identifies OS and version
- Checks compatibility
- Validates system requirements
File System
- Tests file watching capabilities
- Checks disk space availability
- Validates permissions
Performance
- Measures prompt loading time
- Tests file watching responsiveness
- Checks memory usage patterns
Example Output
✓ Operating system: macOS 14.0 (supported)
✓ File system: APFS with file watching support
✓ Disk space: 15.2 GB available
✓ Performance: Prompt loading < 100ms
⚠ Memory usage: High with 1000+ prompts (consider --watch false)
Common Issues and Solutions
Installation Issues
SwissArmyHammer Not Found
✗ SwissArmyHammer binary: Not found in PATH
Solutions:
- Install SwissArmyHammer:
curl -sSL https://install.sh | bash
- Add to PATH:
export PATH="$HOME/.local/bin:$PATH"
- Verify installation:
which swissarmyhammer
Permission Denied
✗ Executable permissions: Permission denied
Solutions:
# Fix permissions
chmod +x $(which swissarmyhammer)
# Or reinstall
curl -sSL https://install.sh | bash
Configuration Issues
Invalid Configuration File
✗ Configuration syntax: Invalid TOML at line 15
Solutions:
- Validate TOML syntax online
- Check for missing quotes or brackets
- Reset to defaults:
swissarmyhammer doctor --fix
Missing Directories
⚠ Prompt directory not accessible: /custom/prompts
Solutions:
# Create missing directory
mkdir -p /custom/prompts
# Fix automatically
swissarmyhammer doctor --fix
Prompt Issues
Invalid YAML Front Matter
✗ Invalid prompts: 3 files with YAML errors
- code-review.md: missing required field 'name'
Solutions:
- Add missing required fields
- Validate YAML syntax
- Use
swissarmyhammer test <prompt>
for detailed errors
Duplicate Prompt Names
⚠ Duplicate names: 'help' defined in multiple locations
Solutions:
- Rename one of the conflicting prompts
- Use different directories for different contexts
- Check prompt override hierarchy
Template Syntax Errors
✗ Template errors: 2 prompts with Liquid syntax issues
- debug.md: Unknown filter 'unknownfilter'
Solutions:
- Fix Liquid template syntax
- Check available filters: see Custom Filters
- Test templates:
swissarmyhammer test <prompt>
MCP Issues
Server Won’t Start
✗ MCP server startup: Failed to bind to port 8080
Solutions:
# Try different port
swissarmyhammer serve --port 8081
# Check what's using the port
lsof -i :8080 # macOS/Linux
netstat -an | findstr 8080 # Windows
Claude Code Not Configured
⚠ Claude Code integration: Not configured
Solutions:
# Add to Claude Code
claude mcp add swissarmyhammer swissarmyhammer serve
# Verify configuration
claude mcp list
Performance Issues
Slow Prompt Loading
⚠ Performance: Prompt loading > 1000ms
Solutions:
- Reduce prompt directory size
- Disable file watching:
--watch false
- Use SSDs for prompt storage
- Split large libraries into categories
High Memory Usage
⚠ Memory usage: 2.1 GB with file watching enabled
Solutions:
# Disable file watching
swissarmyhammer serve --watch false
# Limit prompt directories
swissarmyhammer serve --prompts ./essential-prompts
Automated Fixes
With the --fix
flag, doctor can automatically resolve:
Directory Issues
- Creates missing prompt directories
- Sets appropriate permissions
- Creates default configuration file
Configuration Issues
- Repairs malformed TOML files
- Sets missing default values
- Removes deprecated settings
Permission Issues
- Fixes file and directory permissions
- Makes binaries executable
- Sets appropriate ownership
Example Auto-Fix
swissarmyhammer doctor --fix
# Output:
Fixed: Created missing directory ~/.swissarmyhammer/prompts
Fixed: Set executable permission on swissarmyhammer binary
Fixed: Created default configuration file
Warning: Could not fix invalid YAML in code-review.md (manual intervention required)
Output Formats
Human-Readable (Default)
SwissArmyHammer Doctor Report
============================
Installation Checks:
✓ Binary found and executable
✓ Version 0.1.0 (latest)
✓ Dependencies satisfied
Configuration Checks:
✓ Configuration file valid
⚠ Custom directory not found: /tmp/prompts
Prompt Checks:
✓ 45 prompts loaded successfully
✗ 2 prompts with errors (see details below)
MCP Checks:
✓ Server starts successfully
✓ Protocol compliance verified
System Checks:
✓ OS compatibility confirmed
⚠ High memory usage detected
Summary: 3 warnings, 1 error found
JSON Format
{
"timestamp": "2024-03-20T10:30:00Z",
"version": "0.1.0",
"checks": {
"installation": {
"status": "passed",
"details": [
{
"check": "binary_found",
"status": "passed",
"message": "Binary found at /usr/local/bin/swissarmyhammer"
}
]
},
"configuration": {
"status": "warning",
"details": [
{
"check": "custom_directory",
"status": "warning",
"message": "Directory not found: /tmp/prompts",
"fixable": true
}
]
}
},
"summary": {
"total_checks": 15,
"passed": 12,
"warnings": 2,
"errors": 1
}
}
Integration with CI/CD
Use doctor in automated workflows:
GitHub Actions
- name: Check SwissArmyHammer Health
run: |
swissarmyhammer doctor --json > health-report.json
if [ $(jq '.summary.errors' health-report.json) -gt 0 ]; then
echo "Health check failed"
exit 1
fi
Pre-commit Hook
#!/bin/bash
# .git/hooks/pre-commit
swissarmyhammer doctor --check prompts
if [ $? -ne 0 ]; then
echo "Prompt validation failed. Fix issues before committing."
exit 1
fi
Development Script
#!/bin/bash
# dev-setup.sh
echo "Setting up development environment..."
swissarmyhammer doctor --fix --verbose
echo "Health check complete. Run 'swissarmyhammer serve' to start."
Best Practices
Regular Health Checks
# Weekly health check
swissarmyhammer doctor --verbose
# Before important deployments
swissarmyhammer doctor --check mcp --check prompts
Monitoring Integration
# Check and alert on issues
swissarmyhammer doctor --json | jq -r '.summary.errors' | \
xargs -I {} sh -c 'if [ {} -gt 0 ]; then echo "Alert: SwissArmyHammer errors detected"; fi'
Development Workflow
# After making prompt changes
swissarmyhammer doctor --check prompts --fix
# Before committing
swissarmyhammer doctor --check prompts
Troubleshooting Doctor Issues
Doctor Command Not Found
# Verify installation
which swissarmyhammer
# Reinstall if needed
curl -sSL https://install.sh | bash
Doctor Hangs or Crashes
# Run with timeout
timeout 30s swissarmyhammer doctor --verbose
# Check specific categories
swissarmyhammer doctor --check installation
False Positives
# Skip problematic checks
swissarmyhammer doctor --check config --check prompts
# Use verbose mode for details
swissarmyhammer doctor --verbose
Next Steps
- Fix any issues identified by doctor
- Set up regular health monitoring
- Configure automated fixes where appropriate
- See Troubleshooting for detailed problem resolution
- Check Configuration for advanced settings