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

The Agent Reach watch command executes two independent verification routines—channel health diagnostics via the doctor component and semantic version checks against GitHub releases—designed to produce output only when issues are detected, making it ideal for cron-based scheduled monitoring.

The Agent Reach CLI provides a lightweight orchestration utility specifically architected for automated health monitoring through its watch sub-command. This functionality enables operators to verify multi-channel system integrity and detect available software updates without manual intervention. Understanding how the watch command performs health checks for scheduled tasks allows you to configure reliable, silent monitoring pipelines that alert only when actionable problems occur.

Command Entry Point and Registration

The watch sub-command is registered in agent_reach/cli.py at lines 127–151 and dispatched to the internal function _cmd_watch source.

def _cmd_watch():
    """Quick health check + update check, designed for scheduled tasks.

    Only outputs problems. If everything is fine, outputs a single line.
    """

This entry point initializes a Config object and orchestrates the dual verification workflow, aggregating results into a concise report format suitable for automated alerting systems.

Channel Health Diagnostics

Inside _cmd_watch, the function imports and invokes check_all from agent_reach/doctor to evaluate every configured channel source.

from agent_reach.doctor import check_all
...
config = Config()
issues = []
results = check_all(config)          # ← asks every channel to run its own `check`

The check_all helper iterates over the registry of channel classes returned by get_all_channels() and invokes each channel’s check method individually source. Exception handling wraps each invocation, ensuring that a single misbehaving channel never aborts the entire health report.

Each channel returns a dictionary containing:

• status: One of ok, warn, off, or error
• message: A human-readable description of the state

The _cmd_watch function aggregates any non-ok statuses into an issues list (lines 56–62) for inclusion in the final output source.

Version Update Detection

After completing health diagnostics, _cmd_watch queries the GitHub releases API to determine if a newer package version exists source.

resp, err, _ = _github_get_with_retry(
    "https://api.github.com/repos/Panniantong/Agent-Reach/releases/latest",
    timeout=10,
    retries=2,
)
if not err and resp and resp.status_code == 200:
    data = resp.json()
    latest = data.get("tag_name", "").lstrip("v")
    if latest and _is_newer_version(latest, __version__):
        update_available = True
        new_version = latest
        release_body = data.get("body", "")

The helper _is_newer_version performs semantic version comparison to prevent false downgrade prompts source. The retry logic with a 10-second timeout ensures transient network failures do not falsely trigger update alerts.

Silent Operation and Output Logic

The command implements fail-silent behavior optimized for scheduled execution. If no health issues are found and no update is available, the command prints a single concise line indicating system health source.

When problems are detected, the output expands to include:

• The count of healthy vs. total channels
• Specific error or warning messages from failing channels
• Available version information and truncated release notes source

This design allows cron jobs to trigger alerts only when the command produces non-empty output or returns a non-zero exit status.

Configuring watch for Scheduled Tasks

Manual Execution

Run a one-off health check from your terminal:

agent-reach watch

Typical output when healthy:

Agent Reach: 全部正常 (12/12 渠道可用，v1.5.0 已是最新)

Cron Job Integration

Configure a cron job to run the check hourly and email only when issues exist:

# Run health check every hour, email on any output

0 * * * * /usr/local/bin/agent-reach watch | mail -s "Agent Reach health" admin@example.com

Because the command remains silent on success, the mail command only sends notifications when the watch command detects channel failures or available updates.

Summary

• The watch command is implemented in agent_reach/cli.py within the _cmd_watch function, registered at lines 127–151.
• Channel health checks utilize check_all from agent_reach/doctor.py to iterate through all registered channels via get_all_channels(), capturing statuses of ok, warn, off, or error.
• Version checking queries the GitHub releases API with 10-second timeouts and 2 retries, using _is_newer_version for semantic comparison.
• The command outputs a single line on success and detailed reports only when issues are detected, making it ideal for cron-based scheduled tasks.
• Individual channel implementations (such as agent_reach/channels/twitter.py) contain the specific check methods invoked during the diagnostic sweep.

Frequently Asked Questions

What statuses can the channel health checks return?

Each channel returns one of four statuses: ok indicates healthy operation, warn signals non-critical issues requiring attention, off indicates the channel is disabled or unavailable, and error represents critical failures preventing operation. The _cmd_watch function aggregates all non-ok statuses into the issues list for reporting.

How does the watch command handle network failures during update checks?

The implementation uses _github_get_with_retry with explicit parameters of timeout=10 and retries=2 when querying the GitHub API. If the request fails after retries or returns a non-200 status code, the error is captured silently and the update check continues without crashing the health report, ensuring network transient issues do not trigger false alerts.

Can I run the watch command manually or only via cron?

You can execute the watch command interactively from the terminal using agent-reach watch for immediate diagnostics. While designed for silent operation in scheduled tasks, the command provides human-readable output when issues are detected, making it suitable for both manual troubleshooting and automated monitoring pipelines.

Which file contains the logic for individual channel health checks?

Individual channel health check implementations reside within specific channel modules (for example, agent_reach/channels/twitter.py). The orchestration logic that calls these checks is located in agent_reach/doctor.py, specifically within the check_all function that iterates over get_all_channels().

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