doctor

name	doctor
description	System health diagnostics and troubleshooting
emoji	🩺

Doctor - Complete API Reference

Run system diagnostics, check health status, and troubleshoot issues.

---

Chat Commands

Health Checks

/doctor                                     Run all diagnostics
/doctor quick                               Quick health check
/doctor full                                Full diagnostic scan
/doctor <component>                         Check specific component

Component Checks

/doctor system                              OS, memory, disk
/doctor node                                Node.js version, memory
/doctor network                             Connectivity tests
/doctor api                                 API key validation
/doctor database                            Database connection
/doctor channels                            Channel health

Status

/health                                     Quick health status
/status                                     System status overview
/status verbose                             Detailed status

---

TypeScript API Reference

Create Doctor Service

import { createDoctorService } from 'clodds/doctor';

const doctor = createDoctorService({
  // Checks to run
  checks: ['system', 'node', 'network', 'api', 'database', 'channels'],

  // Thresholds
  thresholds: {
    memoryWarning: 80,    // % memory usage
    memoryCritical: 95,
    diskWarning: 80,      // % disk usage
    diskCritical: 95,
    latencyWarning: 1000, // ms
    latencyCritical: 5000,
  },

  // Timeout
  timeoutMs: 30000,
});

Run Diagnostics

// Run all checks
const report = await doctor.runDiagnostics();

console.log(`Overall: ${report.status}`);  // 'healthy' | 'degraded' | 'unhealthy'
console.log(`Checks passed: ${report.passed}/${report.total}`);

for (const check of report.checks) {
  const icon = check.status === 'pass' ? '✓' : check.status === 'warn' ? '⚠' : '✗';
  console.log(`${icon} ${check.name}: ${check.message}`);
  if (check.details) {
    console.log(`  ${JSON.stringify(check.details)}`);
  }
}

Run Specific Check

// Check system resources
const system = await doctor.checkSystem();

console.log(`OS: ${system.os} ${system.version}`);
console.log(`CPU: ${system.cpuUsage}%`);
console.log(`Memory: ${system.memoryUsage}% (${system.memoryUsedGB}/${system.memoryTotalGB} GB)`);
console.log(`Disk: ${system.diskUsage}% (${system.diskUsedGB}/${system.diskTotalGB} GB)`);

Check Node.js

const node = await doctor.checkNode();

console.log(`Node.js: ${node.version}`);
console.log(`Heap: ${node.heapUsed}/${node.heapTotal} MB`);
console.log(`RSS: ${node.rss} MB`);
console.log(`Uptime: ${node.uptime} seconds`);

Check Network

const network = await doctor.checkNetwork();

console.log(`Internet: ${network.internet ? 'Connected' : 'Disconnected'}`);
console.log(`DNS: ${network.dns ? 'Working' : 'Failed'}`);

for (const [endpoint, result] of Object.entries(network.endpoints)) {
  console.log(`${endpoint}: ${result.reachable ? 'OK' : 'Failed'} (${result.latencyMs}ms)`);
}

Check API Keys

const api = await doctor.checkApiKeys();

for (const [provider, status] of Object.entries(api)) {
  console.log(`${provider}: ${status.valid ? 'Valid' : 'Invalid'}`);
  if (status.error) {
    console.log(`  Error: ${status.error}`);
  }
  if (status.quota) {
    console.log(`  Quota: ${status.quota.used}/${status.quota.limit}`);
  }
}

Check Database

const db = await doctor.checkDatabase();

console.log(`Connected: ${db.connected}`);
console.log(`Latency: ${db.latencyMs}ms`);
console.log(`Version: ${db.version}`);
console.log(`Tables: ${db.tables}`);
console.log(`Size: ${db.sizeMB} MB`);

Check Channels

const channels = await doctor.checkChannels();

for (const channel of channels) {
  console.log(`${channel.name}: ${channel.status}`);
  if (channel.error) {
    console.log(`  Error: ${channel.error}`);
  }
  console.log(`  Connected: ${channel.connected}`);
  console.log(`  Last message: ${channel.lastMessage}`);
}

Format Report

// Get formatted report
const report = await doctor.runDiagnostics();
const formatted = doctor.formatReport(report);

console.log(formatted);
// Outputs nicely formatted diagnostic report

---

Diagnostic Checks

Check	What it Tests
system	OS, CPU, memory, disk
node	Node.js version, heap, memory
network	Internet, DNS, API endpoints
api	API key validity and quotas
database	Connection, latency, schema
channels	Channel connections, health
mcp	MCP server connections
dependencies	npm packages, versions

---

Status Levels

Status	Meaning
healthy	All checks pass
degraded	Some warnings, still functional
unhealthy	Critical failures, action needed

Check Results

Result	Meaning
pass	Check succeeded
warn	Warning threshold exceeded
fail	Critical failure
skip	Check skipped (not applicable)

---

CLI Commands

# Run all diagnostics
clodds doctor

# Quick check
clodds doctor --quick

# Check specific component
clodds doctor --check system

# JSON output
clodds doctor --json

---

Common Issues

High Memory Usage

⚠ Memory: 85% used

Solution: Restart the service or increase available memory

API Key Invalid

✗ Anthropic API: Invalid key

Solution: Check ANTHROPIC_API_KEY in .env

Database Connection Failed

✗ Database: Connection refused

Solution: Check DATABASE_URL and ensure PostgreSQL is running

Channel Disconnected

⚠ Telegram: Disconnected

Solution: Check TELEGRAM_BOT_TOKEN and network connectivity

---

Best Practices

1. Run regularly — Check health daily or after changes
2. Monitor trends — Watch for gradual degradation
3. Set alerts — Alert on unhealthy status
4. Fix warnings — Don't wait for failures
5. Review before deploy — Run doctor before production changes