Agent Reach watch Command: Purpose and Functionality for Scheduled Health Checks

The watch command performs automated health checks on all configured channels and verifies software updates, designed to run silently during healthy states and only output when problems or updates exist.

The Agent Reach CLI provides a specialized watch sub-command specifically engineered for production monitoring and cron-based automation. Unlike interactive commands, this utility orchestrates diagnostic routines that validate channel connectivity and software currency while minimizing noise during routine successful executions.

How the watch Command Works

The command is implemented as a lightweight orchestration routine in agent_reach/cli.py that aggregates diagnostic data from across the system without user intervention.

Entry Point and Command Registration

The watch sub-command is registered in agent_reach/cli.py at lines 127–151, dispatching execution to the internal _cmd_watch function.

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 the monitoring sequence by loading user configuration and preparing result aggregation structures before executing the dual verification routines.

Channel Health Diagnostics

Inside _cmd_watch (lines 44–53), the system builds a Config object and invokes the doctor's check_all helper imported from agent_reach/doctor.

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 function (implemented at lines 12–20 in agent_reach/doctor.py) iterates over the registry of channel classes returned by get_all_channels(). It invokes each channel's check method individually, wrapping calls in exception handling to ensure a single misbehaving channel cannot abort the entire health report.

Each channel returns a dictionary containing a status field (ok, warn, off, or error) and a human-readable message. The _cmd_watch function aggregates any non-ok statuses into an issues list (lines 56–62) for the final report.

Version Update Detection

Following health diagnostics, _cmd_watch queries the GitHub Releases API to detect available software updates (lines 66–73 in agent_reach/cli.py).

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 (lines 58–66) performs semantic version comparison to prevent false downgrade prompts, ensuring only genuinely newer releases trigger notifications.

Output Logic and Exit Behavior

The command implements conditional output optimized for automated scheduling. If no health issues and no version updates are found, the system prints a single concise line indicating complete system health (lines 81–84).

When problems exist or updates are available, the command generates a structured report (lines 85–100) listing healthy channel counts, specific error messages, and new version details with release notes excerpts. This design ensures that cron systems or monitoring alerts only trigger when actionable information exists.

Implementing Scheduled Monitoring

The watch command is optimized for cron-style automation because it produces no output during standard healthy operation, preventing alert fatigue.

Manual Execution

Run a one-off health check from the terminal:

agent-reach watch

Typical successful output:

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

Example output when channels fail and updates exist:

Agent Reach 监控报告
========================================
版本: v1.5.0  |  渠道: 10/12
[X] Twitter：未登录
! Reddit：需要 API token
...
新版本可用: v1.6.0
    • 修复 XSS 漏洞
    • 新增 TikTok 支持
  更新（一句话发给 Agent 即可完整更新）:
    帮我更新 Agent Reach：https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md

Cron Configuration

Configure automated monitoring by adding the command to your system's crontab:

# Run health check every hour, email on any output

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

This configuration executes hourly, emailing administrators only when the command emits output—meaning only when health issues emerge or software updates become available.

Summary

• The watch command in agent_reach/cli.py provides silent health monitoring optimized for scheduled tasks and cron jobs.
• Channel health checks iterate through all registered channels via check_all in agent_reach/doctor.py, catching exceptions to isolate individual channel failures.
• Version checking queries GitHub's latest release API with semantic version comparison via _is_newer_version to avoid false positives.
• The command produces output only when issues exist or updates are available, making it ideal for automated alerting systems that monitor stderr/stdout.
• Each channel implements its own check method, allowing modular diagnostic logic specific to each integration (e.g., Twitter, Reddit).

Frequently Asked Questions

What triggers the watch command to produce output?

The watch command remains silent and outputs only a single confirmation line when all channels report ok status and no software updates are available. It produces detailed reports only when channel health checks return warn, off, or error statuses, or when the GitHub API indicates a newer version exists than the currently installed __version__.

How does the watch command handle individual channel failures?

According to the implementation in agent_reach/doctor.py (lines 12–20), the check_all function wraps each channel's check method in a try-except block. This isolation ensures that exceptions thrown by one channel do not terminate the entire health check process, allowing the command to report comprehensive partial system health rather than failing completely on the first error.

Where is the watch command defined in the codebase?

The command entry point is defined in agent_reach/cli.py at lines 127–151, where the CLI parser registers the watch sub-command. The core orchestration logic resides in the _cmd_watch function spanning lines 44–100, which coordinates configuration loading, health diagnostics via the doctor module, and version checking against the GitHub API.

What version comparison logic does watch use?

The command utilizes a private helper function _is_newer_version implemented in agent_reach/cli.py (lines 58–66) to perform semantic version comparison. This ensures that only genuinely newer releases trigger update notifications, preventing false alerts for older or equivalent version strings that might be returned by the GitHub Releases API.

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