Health Checks & Diagnostics
Relevant source files
The following files were used as context for generating this wiki page:
The Health Checks & Diagnostics system in CCS (Claude Code Switch) is a multi-layered framework designed to ensure the operational integrity of the CLI, its web dashboard, and compatible third-party runtimes like Codex. It provides automated verification of system dependencies, environment variables, configuration files, and authentication states. The system is primary exposed through the ccs doctor CLI command and the /health page on the web dashboard.
This module is responsible for identifying misconfigurations (such as invalid YAML/JSON files), environment readiness (port availability for OAuth), and system health (symlink integrity and directory permissions). It also includes an auto-repair mechanism that can fix common issues, such as missing directories or corrupt configuration files.
Sources: src/management/doctor.ts:1-20, src/web-server/health-service.ts:1-12
Architecture Overview
The diagnostics architecture is split between a CLI orchestrator (Doctor class) and a web-based service (health-service.ts). Both share a modular logic core comprised of specific health checkers and validation functions.
The Doctor Orchestrator
The Doctor class serves as the main entry point for CLI-based diagnostics. It executes a series of "safe" check groups defensively, ensuring that a failure in one check (e.g., a malformed configuration file) does not prevent the generation of the final summary and repair hints.
Web Health Service
The web health service mirrors the CLI's logic but packages the results into a structured HealthReport for consumption by the React-based dashboard. It groups checks into categories like System, Configuration, and OAuth Readiness.
| Category | Description | Key Source |
|---|---|---|
| System | Verifies Claude CLI installation and CCS directory existence. | checkClaudeCli |
| Configuration | Validates config.yaml (v2) or config.json (legacy) integrity. | checkConfigFile |
| Profiles | Inspects account instances and delegation settings. | checkProfiles |
| CLIProxy | Checks OAuth providers and port availability (8317). | checkCliproxyPort |
| WebSearch | Verifies search CLI provider availability. | checkWebSearchClis |
Sources: src/web-server/health-service.ts:38-95
Diagnostic Components
Configuration Validation
The system prioritizes config.yaml (unified v2 format) over the legacy config.json. The ConfigFilesChecker uses js-yaml to validate the contents and provides specific recovery commands if the file is corrupted.
// Example of defensive YAML validation logic
try {
const yaml = require('js-yaml');
const content = fs.readFileSync(configYamlPath, 'utf8');
yaml.load(content);
// ... success handling
} catch (e) {
const reason = (e as Error).message.split('\n')[0].trim();
results.addCheck('config.yaml', 'error', `Invalid YAML: ${reason}`, ...);
}
Sources: src/management/checks/config-check.ts:47-75
Codex Diagnostics
For compatible CLIs like Codex, CCS provides a specialized service (codex-dashboard-service.ts) that probes the config.toml file. It tracks binary installation, feature flag states, and "Project Trust" levels.
| Diagnostic Field | Description | Logic |
|---|---|---|
| Binary Info | Detects version and PATH location. | getCodexBinaryInfo() |
| Project Trust | Summarizes trusted/untrusted paths. | summarizeCodexProjectTrust() |
| Feature Flags | Lists enabled/disabled experimental flags. | summarizeCodexFeatureFlags() |
| MCP Servers | Monitors transport and timeout settings. | summarizeCodexMcpServers() |
Sources: src/web-server/services/codex-dashboard-service.ts:544-633
Hardening & Maintainability Inventory
CCS maintains an internal "Hardening Inventory" script that tracks technical debt and code health metrics. This is used by architects to monitor the adoption of typed errors and the removal of legacy synchronous filesystem calls in runtime hotpaths.
Key Metrics Tracked
- Typed Error Adoption: Measures the ratio of
CCSErrorsubclasses versus plainErrorthrows. Target adoption is >40% in locked subdomains. - CLI-UX Exemptions: The scanner ignores
console.errorcalls insrc/commands/as these are intended for terminal output, not diagnostic logging. - Sync FS Occurrences: Identifies usage of
fs.readFileSyncorfs.writeFileSyncin runtime hotpaths that should ideally be asynchronous.
Sources: scripts/maintainability-metrics.js:34-60, scripts/hardening-inventory.js:46-78
Auto-Repair Mechanism
The fixHealthIssue function in the health service provides a programmatic way to resolve detected errors.
| Check ID | Action | Result |
|---|---|---|
ccs-dir | fs.mkdirSync(ccsDir, ...) | Creates missing ~/.ccs directory. |
config-file | mutateConfig(() => {}) | Generates a fresh config.yaml. |
profiles-file | fs.writeFileSync(...) | Initializes an empty profiles.json. |
Sources: src/web-server/health-service.ts:114-142
Summary
The Health Checks & Diagnostics system provides a comprehensive safety net for CCS users and developers. By combining CLI-based inspection (ccs doctor) with real-time dashboard monitoring and automated technical debt inventory, the project ensures that both the user environment and the codebase remain maintainable and operational.