Diagnostic Tools

Relevant source files

• agent/i18n.py
• gateway/status.py
• hermes_cli/__init__.py
• hermes_cli/doctor.py
• hermes_cli/gateway.py
• hermes_cli/profiles.py
• hermes_cli/status.py
• locales/ar.yaml
• optional-mcps/unreal-engine/manifest.yaml
• plugins/observability/nemo_relay/README.md
• plugins/observability/nemo_relay/__init__.py
• pyproject.toml
• scripts/contributor_audit.py
• scripts/release.py
• tests/agent/test_i18n.py
• tests/gateway/test_discord_document_handling.py
• tests/gateway/test_document_cache.py
• tests/gateway/test_gateway_command_line_matcher.py
• tests/gateway/test_runner_startup_failures.py
• tests/gateway/test_send_image_file.py
• tests/gateway/test_status.py
• tests/gateway/test_telegram_documents.py
• tests/hermes_cli/test_config_validation.py
• tests/hermes_cli/test_doctor.py
• tests/hermes_cli/test_ensure_utf8_locale.py
• tests/hermes_cli/test_gateway.py
• tests/hermes_cli/test_gateway_linger.py
• tests/hermes_cli/test_gateway_proc_fallback.py
• tests/hermes_cli/test_gateway_service.py
• tests/hermes_cli/test_profiles.py
• tests/plugins/test_nemo_relay_plugin.py
• tests/test_packaging_metadata.py
• tests/test_project_metadata.py
• tests/tools/test_lazy_deps.py
• tools/lazy_deps.py
• uv.lock
• website/docs/reference/profile-commands.md
• website/docs/user-guide/profile-distributions.md
• website/docs/user-guide/profiles.md

Hermes Agent provides a suite of diagnostic utilities for validating system configuration, troubleshooting environment issues, and monitoring service health. These tools range from hermes doctor for deep environment validation to hermes status for component health and automated API error classification for smart failover.

---

Overview

The diagnostic system provides visibility into the agent's runtime environment, authentication state, and service health.

Command	Purpose	Implementation File
hermes doctor	Comprehensive system health check and auto-repair.	hermes_cli/doctor.py1-5
hermes status	Quick overview of components, auth, and gateway.	hermes_cli/status.py1-5
hermes gateway status	Specific health and PID tracking for the gateway daemon.	hermes_cli/gateway.py73-89
Error Classifier	Internal API error taxonomy for automated recovery.	agent/error_classifier.py1-10

Sources: hermes_cli/doctor.py1-5 hermes_cli/status.py1-5 hermes_cli/gateway.py73-89 agent/error_classifier.py1-10

---

Doctor Command Architecture

The hermes doctor command performs a multi-stage validation of the Python environment, configuration files, and system services. It is designed to be "Termux-aware," adjusting its recommendations based on whether it detects an Android environment hermes_cli/doctor.py60-61

Natural Language to Code Entity Mapping: Doctor

Sources: hermes_cli/doctor.py60-61 hermes_cli/doctor.py103-105 hermes_cli/doctor.py108-117 hermes_cli/doctor.py198-202 hermes_cli/doctor.py67-72 hermes_cli/doctor.py137-152

Internal Logic and Auto-Fix

• Environment Loading: Loads variables from ~/.hermes/.env to ensure API key checks work hermes_cli/doctor.py22-24 It specifically reads .env as UTF-8 to avoid crashes on Windows Chinese locales (GBK) tests/hermes_cli/test_doctor.py83-98
• Tool Availability: The _apply_doctor_tool_availability_overrides function handles special cases like kanban (gated for dispatcher-spawned workers) and honcho (available if configured, even without an active session) hermes_cli/doctor.py137-152
• OAuth Fallbacks: Uses _has_healthy_oauth_fallback_for_apikey_provider to determine if a missing API key is non-blocking because a valid OAuth session exists for MiniMax or xAI hermes_cli/doctor.py155-176
• Platform-Specific Hints: Provides custom installation commands for Termux (using pkg) versus standard Linux/macOS (using uv or brew) hermes_cli/doctor.py63-72

Sources: hermes_cli/doctor.py22-24 hermes_cli/doctor.py63-72 hermes_cli/doctor.py137-152 hermes_cli/doctor.py155-176 tests/hermes_cli/test_doctor.py83-98

---

Status and Health Monitoring

The hermes status command provides a real-time snapshot of the environment, configured models, and API connectivity.

Implementation Details:

• Provider Resolution: Uses resolve_requested_provider and resolve_provider to determine which LLM backend is currently active hermes_cli/status.py75-81
• Credential Masking: API keys are redacted via mask_secret (imported from agent.redact) before being printed to the terminal hermes_cli/status.py32-41
• Timestamp Formatting: ISO timestamps from gateway state are converted to local time for human readability hermes_cli/status.py44-60

Sources: hermes_cli/status.py32-41 hermes_cli/status.py44-60 hermes_cli/status.py75-81

Gateway Liveness Detection

The system uses a PID-file and lock-file mechanism to track the health of the gateway daemon.

Sources: gateway/status.py69-82 gateway/status.py139-171 gateway/status.py174-176 tests/gateway/test_status.py13-23

• PID Reuse Guard: The system captures stable process fingerprints to ensure a recycled PID is not mistaken for a live gateway gateway/status.py139-171
• Atomic Writes: write_pid_file uses O_CREAT | O_EXCL to prevent racing gateway instances from clobbering each other's state tests/gateway/test_status.py24-47
• Respawn Storm Breaker: record_start_and_check_storm implements an append-only ledger (gateway-starts.log) to detect rapid restart loops and enforce exponential backoff gateway/status.py69-121

Sources: gateway/status.py69-121 gateway/status.py139-171 tests/gateway/test_status.py24-47

---

API Error Classification

The ClassifiedError system provides a structured taxonomy of API failures to drive smart failover and recovery logic.

Error Taxonomy Mapping

Sources: agent/error_classifier.py24-73 agent/error_classifier.py78-94

• Smart Recovery: Each ClassifiedError includes boolean hints such as should_rotate_credential, should_compress, and should_fallback agent/error_classifier.py88-94
• Disambiguation: The classifier distinguishes between per-credential rate limits (which trigger rotation) and upstream provider overloads (which trigger backoff) agent/error_classifier.py164-171
• Billing Detection: Uses _BILLING_PATTERNS and _BILLING_ERROR_CODES to identify confirmed credit exhaustion agent/error_classifier.py104-143

Sources: agent/error_classifier.py88-94 agent/error_classifier.py104-143 agent/error_classifier.py164-171

---

Troubleshooting Summary Table

Symptom	Diagnostic Step	Implementation Reference
Gateway fails to start	Check for stale PID files or active locks	gateway/status.py66-70
API keys not loading	Check .env encoding (must be UTF-8)	tests/hermes_cli/test_doctor.py83-98
Gateway restart loop	Check gateway-starts.log for storm backoff	gateway/status.py62-66
LLM Failures	Check ClassifiedError.reason in logs	agent/error_classifier.py24-73

Sources: gateway/status.py62-70 agent/error_classifier.py24-73 tests/hermes_cli/test_doctor.py83-98