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

> Learn how the Agent Reach watch command runs health checks for scheduled tasks. It loads config, checks channels, categorizes failures, queries GitHub, and reports status for cron monitoring.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-27

---

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

```bash
agent-reach watch

```

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

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

```

Programmatic invocation using the internal CLI function:

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