How the Agent Reach Watch Command Performs Health Checks for Scheduled Monitoring

The agent-reach watch command performs lightweight, non-interactive health checks by loading the user configuration, executing full channel diagnostics via check_all(), and emitting a concise one-line status report ideal for cron-based scheduled monitoring.

The watch sub-command in the Panniantong/Agent-Reach repository provides a "cron-friendly" entry point for automated health monitoring. Unlike interactive CLI commands, this utility is designed to run silently in scheduled environments while providing immediate visibility into channel health and availability updates.

Architecture of the Watch Command Health Check

The implementation in agent_reach/cli.py (lines 1678-1741) defines the _cmd_watch function, which orchestrates a four-phase health verification process without requiring user interaction.

Loading User Configuration

First, the command initializes a Config() instance that reads settings from ~/.agent-reach/config.yaml. This ensures the watch command operates with the same parameters used during installation or manual doctor runs, maintaining consistency across different execution contexts.

Executing Full Channel Diagnostics

The core health validation occurs through check_all(config) imported from agent_reach.doctor. This function iterates over every channel retrieved via get_all_channels() and invokes the channel-specific check(config) method defined in agent_reach/channels/base.py. Each channel returns a dictionary containing status, name, message, tier, and backends fields, creating a comprehensive health snapshot.

Aggregating Health Results

After collecting channel responses, the watch command categorizes results into three severity levels:

• Hard failures: Channels reporting status of off or error receive an [X] marker
• Warnings: Channels with status of warn receive a [!] marker
• Healthy: Channels with passing status contribute to the "ok" count

This aggregation produces a concise ratio of healthy versus total channels (e.g., "5/7 channels available").

Version Update Detection

The command performs a single HTTPS request to https://api.github.com/repos/Panniantong/Agent-Reach/releases/latest. When the returned tag name differs from the current __version__, the watch command stores the new version and release notes for inclusion in the output report.

Output Format and Monitoring Integration

When all channels pass and no updates exist, the command outputs a minimal one-line status:

Agent Reach: 全部正常 (X/Y 渠道可用，vZ 已是最新)

This terse format ensures monitoring tools and log aggregators capture a brief "all-clear" message without noise.

If issues exist or updates are available, the output expands to a structured report containing the current version and channel health ratio (ok/total), enumerated problem lines with severity markers, and new version information with truncated release notes.

Implementing Scheduled Monitoring with Cron

Because watch performs no installations or interactive prompts, it is safe to schedule via crontab.

Run manually:

agent-reach watch

Schedule daily execution:

0 2 * * * /home/you/.local/bin/agent-reach watch >> /home/you/agent-reach.log 2>&1

Programmatic usage:

from agent_reach.cli import _cmd_watch

if __name__ == "__main__":
    _cmd_watch()   # prints the same output as `agent-reach watch`

Summary

• The agent-reach watch command in agent_reach/cli.py provides non-interactive health monitoring suitable for automation
• Health checks execute via check_all() in agent_reach/doctor.py, which validates every configured channel through the BaseChannel.check() contract
• Results are aggregated into severity categories (error, warn, ok) and summarized as a channel availability ratio
• The command checks for newer releases via the GitHub API without impacting health check performance
• Output formats adapt to context: single-line for success states, multi-line diagnostic detail when failures occur

Frequently Asked Questions

Which source file contains the watch command implementation?

The _cmd_watch function is implemented in agent_reach/cli.py between lines 1678 and 1741. This module handles configuration loading, health check orchestration, update detection, and formatted output generation.

How does the watch command differ from the doctor command?

While both use check_all() from agent_reach/doctor.py to validate channels, the watch command is optimized for automation. It suppresses interactive prompts, emits machine-friendly one-line output when healthy, and includes version update checking, whereas the doctor command typically provides detailed, human-readable diagnostics and may offer repair options.

What specific channel data does the health check evaluate?

Each channel returns a status dictionary containing status (off/error/warn), name, message (descriptive failure text), tier (service level), and backends (infrastructure details). The watch command specifically monitors the status field to determine overall system health.

Can the watch command be used in containerized or CI/CD environments?

Yes. Because the command requires no TTY interaction and exits with appropriate status codes based on health check results, it integrates seamlessly into Docker health checks, Kubernetes liveness probes, or CI/CD pipeline validation steps by executing agent-reach watch as a validation stage.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}