How the Agent-Reach Watch Command Performs Scheduled Health Checks

The agent-reach watch command performs lightweight, cron-compatible health monitoring by loading user configuration, executing check_all() from the doctor module to validate every channel, and outputting a minimal status line or diagnostic report suitable for automated alerting systems.

The watch subcommand in the Panniantong/Agent-Reach repository provides a non-interactive, cron-friendly entry point designed specifically for scheduled health monitoring. Unlike the interactive doctor command, watch executes silently and produces machine-readable output that integrates seamlessly with automation tools while maintaining the same rigorous validation across all configured channels.

Configuration Loading and Initialization

The watch command begins by instantiating the Config class to load user settings from ~/.agent-reach/config.yaml. This ensures scheduled runs use identical configuration to interactive CLI operations, maintaining consistency across install, doctor, and watch commands.

In agent_reach/cli.py, the _cmd_watch function initializes this process between lines 1678-1686, creating a configuration object that subsequent health checks reference.

Executing the Health Check Pipeline

Once configured, the command invokes check_all(config) from the agent_reach.doctor module. This function iterates over every channel returned by get_all_channels() and executes the channel-specific check(config) method defined in the abstract BaseChannel class.

According to the implementation in agent_reach/doctor.py (lines 12-24), check_all constructs a dictionary keyed by channel name, containing status, name, message, tier, and backends for each validated channel. Each concrete channel implementation in agent_reach/channels/base.py defines its own validation logic while conforming to this standard interface.

Aggregating Results and Classifying Issues

After the health check completes, the watch command processes results to distinguish between healthy and degraded channels. In agent_reach/cli.py (lines 1690-1701), the implementation categorizes outcomes into three distinct states:

• [X] Hard failures: Channels reporting status of off or error
• [!] Warnings: Channels reporting status of warn
• OK channels: Channels without issues

The command calculates aggregate statistics (OK count versus total channels) and compiles concise textual snippets for each problem detected, mirroring the doctor's internal structure but optimized for brevity.

Checking for Software Updates

The watch command optionally queries the GitHub API to detect new Agent-Reach releases. Between lines 1703-1717 in agent_reach/cli.py, the implementation performs a single HTTPS request to https://api.github.com/repos/Panniantong/Agent-Reach/releases/latest.

If the retrieved tag name differs from the current __version__, the command stores the new version tag and release body for inclusion in the final report. This update check runs automatically during each watch execution, providing early notification of available improvements without requiring manual version checking.

Output Formats for Cron Integration

The command produces two distinct output modes optimized for automated monitoring systems.

All-Clear Status: When no issues exist and no updates are available, watch outputs a single minimal line:

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

Here, X represents OK channels, Y represents total channels, and Z represents the current version. This format appears in agent_reach/cli.py between lines 1720-1722.

Diagnostic Report: When health issues or updates exist, the command expands to a multi-line summary (lines 1724-1740) containing:

• Current version and channel health ratio (ok/total)
• Each problem line marked with [X] or [!]
• Update information including new version and release notes excerpt

Practical Usage Examples

Configure the watch command in your automation environment using these patterns.

Run manually for immediate status:

agent-reach watch

Schedule daily execution via cron:

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

Integrate programmatically in Python scripts:

from agent_reach.cli import _cmd_watch

if __name__ == "__main__":
    _cmd_watch()  # Prints same output as CLI invocation

Summary

• The agent-reach watch command loads configuration from ~/.agent-reach/config.yaml using the Config class to ensure consistency with other CLI operations.
• Health validation occurs through check_all() in agent_reach/doctor.py, which executes channel-specific check() methods across all configured channels.
• Results aggregate into OK counts, hard failures ([X]), and warnings ([!]) for concise reporting without interactive overhead.
• Optional GitHub API polling detects new releases by comparing the latest tag against __version__.
• Output formats range from single-line success messages to multi-line diagnostic reports, making the command safe for cron scheduling and monitoring tool integration.

Frequently Asked Questions

What is the difference between agent-reach watch and agent-reach doctor?

While both commands validate channel health, doctor runs interactively with detailed output and potential user prompts, whereas watch produces minimal, machine-readable output designed specifically for cron jobs and automated monitoring systems. The watch command never performs installations or interactive operations, making it safe to schedule without user intervention.

Where does the watch command store its configuration?

The command reads user settings from ~/.agent-reach/config.yaml through the Config class, as implemented in agent_reach/cli.py lines 1678-1686. This ensures scheduled runs use the same configuration as manual CLI operations, maintaining consistency across all Agent-Reach commands.

How does the watch command handle channel health failures?

The implementation classifies failures into two categories: hard failures ([X]) for channels with status of off or error, and warnings ([!]) for channels with status of warn. These classifications appear in the final report alongside the ratio of healthy channels to total channels, providing immediate visibility into system health.

Can the watch command run without checking for updates?

The current implementation in agent_reach/cli.py (lines 1703-1717) performs the GitHub release check automatically during each execution. There is no built-in flag to disable this check, though the single API request adds minimal overhead to the health monitoring process.

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