# How the Agent-Reach Watch Command Performs Scheduled Health Checks

> Learn how the Agent-Reach watch command schedules health checks using cron-compatible monitoring and the doctor module to validate channels for automated alerts.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-07-03

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
agent-reach watch

```

Schedule daily execution via cron:

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

```

Integrate programmatically in Python scripts:

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.