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

> Discover how the Agent Reach watch command uses doctor and GitHub checks for robust scheduled task health monitoring, alerting only on detected issues for efficient cron jobs.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) at lines 127–151 and dispatched to the internal function `_cmd_watch` [source](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L127-L151).

```python
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](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L44-L53).

```python
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](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py#L12-L20). 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](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L56-L62).

## Version Update Detection

After completing health diagnostics, `_cmd_watch` queries the GitHub releases API to determine if a newer package version exists [source](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L66-L73).

```python
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](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L58-L66). 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](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L81-L84).

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](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L85-L100)

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:

```bash
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:

```cron

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py)). The orchestration logic that calls these checks is located in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), specifically within the `check_all` function that iterates over `get_all_channels()`.