How the `watch` Command Performs Health Checks for Scheduled Tasks in Agent Reach

The watch command loads user configuration from ~/.agent-reach/config.yaml, executes a full channel health check via check_all(), categorizes failures by severity, queries the GitHub API for updates, and emits a concise one-line status or multi-line diagnostic report optimized for cron monitoring.

The agent-reach watch sub-command provides a lightweight, non-interactive health monitoring mechanism designed specifically for scheduled execution. According to the Panniantong/Agent-Reach source code, this command offers a "cron-friendly" entry point that validates channel connectivity and detects new releases without performing installations or prompting for user input. Understanding how watch performs health checks enables you to set up reliable monitoring for your Agent Reach channels.

Configuration Loading and Initialization

The watch command begins by establishing its operational context through the same configuration system used by other CLI commands.

In agent_reach/cli.py (lines 1678-1686), the _cmd_watch function initializes a Config() instance that reads from ~/.agent-reach/config.yaml. This ensures the health check operates with the identical settings used during install or doctor runs, maintaining consistency across your Agent Reach environment.

Channel Health Verification Process

Once configuration is loaded, watch delegates the actual health assessment to the doctor module.

The command calls check_all(config) from agent_reach/doctor.py (lines 12-24). This function iterates over every channel returned by get_all_channels() and invokes the channel-specific check(config) method for each. Each channel returns a dictionary containing:

• status: The health state (ok, warn, off, or error)
• name: The channel identifier
• message: Human-readable diagnostic text
• tier: The service tier classification
• backends: Associated backend configurations

This structured approach allows watch to aggregate health data across all configured channels without requiring channel-specific logic within the CLI layer.

Issue Classification and Severity Mapping

After collecting channel results, watch processes the returned dictionaries to categorize problems by severity.

In agent_reach/cli.py (lines 1690-1701), the command distinguishes between:

• Hard failures ([X] …): Channels reporting status values of off or error
• Warnings ([!] …): Channels reporting status of warn

The command counts total channels versus healthy channels (ok vs. total), preserving only the textual snippets necessary for a concise report rather than the full diagnostic objects.

Version Update Detection

Beyond channel health, watch monitors the Agent Reach installation itself for available updates.

The command performs a single HTTP request to https://api.github.com/repos/Panniantong/Agent-Reach/releases/latest (lines 1703-1717 in agent_reach/cli.py). If the returned tag name differs from the current __version__, watch stores the new version tag and release body for inclusion in the output report.

Output Format and Scheduling Optimization

The watch command produces two distinct output modes depending on system state.

When no issues are detected and no updates are available, watch emits a minimal one-line status (lines 1720-1722):

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

Where X represents healthy channels, Y represents total channels, and Z represents the current version.

If problems exist or an update is available, the command outputs a multi-line report (lines 1724-1740) summarizing:

• Current version and overall channel health (ok/total)
• Each problem line gathered from the severity classification
• Update information including new version and release notes excerpt

This dual-mode output ensures cron jobs receive silent success states while providing detailed diagnostics when human attention is required.

Practical Usage Examples

Execute a manual health check:

agent-reach watch

Schedule daily monitoring via crontab (runs at 2:00 AM daily, appending output to log):

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

Programmatic invocation using the internal CLI function:

from agent_reach.cli import _cmd_watch

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

Summary

• The watch command loads configuration from ~/.agent-reach/config.yaml via Config() to ensure consistency with other CLI operations.
• Health checks execute through check_all(config) in agent_reach/doctor.py, which iterates over all channels and aggregates their individual check() results.
• Status values of off or error generate hard failure markers ([X]), while warn generates warning markers ([!]).
• The command queries the GitHub API to detect newer releases against the current __version__.
• Output is optimized for automation: a single line when healthy, expanded details when issues require attention.
• The command performs no installations or interactive prompts, making it safe for unattended cron scheduling.

Frequently Asked Questions

Where does the watch command load its configuration from?

The watch command reads user configuration from ~/.agent-reach/config.yaml through the Config() class. This occurs in agent_reach/cli.py during initialization, ensuring the health check uses the same settings as interactive commands like install or doctor.

What channel statuses trigger a warning versus an error in the report?

According to the logic in agent_reach/cli.py, channels with status values of off or error are recorded as hard failures (marked with [X]), while channels with status of warn are recorded as warnings (marked with [!]). Only ok statuses are considered healthy.

How does watch check for new Agent Reach releases?

The command performs a single HTTPS request to https://api.github.com/repos/Panniantong/Agent-Reach/releases/latest. It compares the JSON response's tag name against the local __version__ string. If they differ, watch includes the new version number and release notes excerpt in its output report.

Is the watch command safe to run unattended in cron jobs?

Yes. The watch command is explicitly designed as a "cron-friendly" entry point that performs no installations, modifications, or interactive prompts. It only reads configuration, checks channel health, queries the GitHub API, and prints output, making it safe for periodic automated execution without user supervision.

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