# How the Doctor Command Checks Platform Availability in Agent Reach

> Learn how the doctor command in Agent Reach checks platform availability by invoking channel check methods and aggregating status results for external CLI tools.

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

---

**The `doctor` command verifies platform availability by iterating through registered channels in `check_all`, invoking each channel's `check` method to probe external CLI tools, and aggregating results into `ok`, `warn`, or `error` statuses.**

The `doctor` command in Agent Reach serves as a comprehensive diagnostic tool that validates the health of every supported platform (channel). It orchestrates a three-stage pipeline involving the CLI entry point, a diagnostic engine, and channel-specific health checks to determine whether external dependencies like Twitter CLI or Reddit tools are installed, authenticated, and functional.

## CLI Entry Point and Command Initialization

The diagnostic process begins in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) at line 1476, where the `_cmd_doctor` function parses command-line arguments and initializes the configuration. This function creates a `Config` object and passes it to the diagnostic engine.

When you invoke `agent-reach doctor`, the CLI handles optional flags like `--json` for machine-readable output before delegating to the core checking logic. The entry point establishes the connection between user input and the platform verification system.

## The Diagnostic Engine: Orchestrating Platform Checks

The central orchestration logic resides in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), specifically in the `check_all` function defined at line 12. This engine implements the following flow:

1. Retrieves all registered channels via `get_all_channels()`
2. Iterates through each channel and invokes `ch.check(config)`
3. Catches exceptions and converts them to error status results
4. Aggregates results into a structured dictionary

The loop at lines 18-34 handles the iteration, automatically discovering new channels through the registration mechanism in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py). This design ensures that any new platform added to the codebase automatically participates in health checks without modifying the doctor logic.

## Per-Channel Health Check Implementation

Each platform channel inherits from the abstract `Channel` base class defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) and implements a `check(self, config=None)` method. This method follows a two-stage probing pattern exemplified by `TwitterChannel.check` at line 19 of [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py).

**Stage 1: Backend Probing** – The method tests every available backend (e.g., `twitter-cli`, `OpenCLI`, or legacy `bird`).

**Stage 2: Status Selection** – It selects the first backend reporting `status="ok"`, falls back to the first `warn` if no ok exists, or aggregates error messages if all fail.

This architecture allows channels to support multiple implementations of the same platform, choosing the healthiest available option at runtime.

## Backend Probing and Command Execution

The actual interaction with external tools occurs through `probe_command` in [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py). Channel implementations like `_check_twitter_cli` at line 66 of [`twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/twitter.py) use this utility to execute commands with specific timeouts and capture stdout/stderr.

The probing system classifies outcomes into four categories:
- **`missing`** – The command is not installed or not in PATH
- **`broken`** – The command exists but returns a non-zero exit code
- **`timeout`** – The command exceeded the configured timeout period
- **`ok`** – The command executed successfully and returned valid health data

## Result Aggregation and Status Classification

Results flow back through the diagnostic pipeline following this structure:

```text
CLI → Config → check_all → (for each Channel) → Channel.check → status/message

```

The `check_all` function constructs a result dictionary at lines 27-34 containing:
- `status`: `"ok"`, `"warn"`, or `"error"`
- `name`: Human-readable platform name
- `message`: Detailed description of the check outcome
- `tier`: Configuration difficulty level (0-2)
- `backends`: List of attempted backends
- `active_backend`: The selected working backend or null

**Platform Availability Criteria:**
- **Tier 0** – Zero-config platforms always available
- **Tier 1** – Requires free API keys or login (e.g., Twitter, Reddit)
- **Tier 2** – Optional platforms needing additional setup

## Running the Doctor Command

### Human-Readable Output

Execute the default diagnostic report to see a formatted Rich table:

```bash
agent-reach doctor

```

This outputs color-coded status indicators showing available channels (e.g., `[green]12/14[/green]`), generated by `format_report` in [`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/doctor.py).

### Machine-Readable JSON Output

For integration with scripts or CI/CD pipelines, use the JSON flag:

```bash
agent-reach doctor --json

```

The JSON structure matches the internal dictionary built in `check_all`, including backend details and authentication status:

```json
{
  "twitter": {
    "status": "warn",
    "name": "Twitter/X 推文",
    "message": "Twitter CLI 未安装。安装方式：\n  pipx install twitter-cli",
    "tier": 1,
    "backends": ["twitter-cli", "OpenCLI", "bird CLI (legacy)"],
    "active_backend": null
  }
}

```

### Implementing Custom Platform Checks

To add a new platform to the diagnostic suite, create a channel class implementing `check()`:

```python
from agent_reach.channels.base import Channel
from agent_reach.probe import probe_command

class MyServiceChannel(Channel):
    name = "myservice"
    description = "MyService API"
    backends = ["myservice-cli"]
    tier = 1

    def check(self, config=None):
        probe = probe_command("myservice", ["status"], timeout=10, package="myservice-cli")
        if probe.status == "missing":
            return None
        if probe.ok and "ready" in probe.output:
            return "ok", "myservice-cli ready"
        return "warn", "myservice-cli installed but not authenticated"

```

Place this file in `agent_reach/channels/` and the next `doctor` run will automatically include it.

## Summary

- The `doctor` command entry point in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (`_cmd_doctor`) parses arguments and initializes the configuration before calling the diagnostic engine.
- `check_all` in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) (lines 12-34) iterates over all registered channels and invokes their `check` methods, catching exceptions to prevent single-platform failures from crashing the entire diagnostic.
- Each channel implements a `check` method that probes multiple backends using `probe_command` from [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py), classifying results as `ok`, `warn`, or `error`.
- The system supports tiered platform classification (0-2) indicating configuration complexity, with results aggregated into either Rich-formatted tables or JSON output via the `--json` flag.

## Frequently Asked Questions

### What determines if a platform shows as "available" in the doctor output?

A platform displays as available when its `check` method returns a `status` of `"ok"`, meaning the backend command executed successfully and reported healthy. If the tool is installed but lacks authentication or configuration, it returns `"warn"`. A status of `"error"` indicates the command is broken, missing, or timed out during the probe.

### How does the doctor command discover new platforms automatically?

The diagnostic engine uses `get_all_channels()`, which leverages a registration mechanism in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) to discover all subclasses of the base `Channel` class. When you create a new channel file and inherit from `Channel`, the class automatically registers itself, and `check_all` will invoke its `check` method without requiring modifications to the doctor logic.

### Can I check platform availability programmatically instead of via CLI?

Yes, you can import `check_all` directly from [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) and pass a `Config` object to receive the raw results dictionary. This returns the same structured data used by the CLI, including statuses, messages, and backend information, allowing you to integrate platform health checks into Python scripts or automated monitoring systems.

### Why does the doctor command check multiple backends for a single platform?

Channels implement multiple backend probing to provide fallback options and identify the best available tool. For example, the Twitter channel checks `twitter-cli`, `OpenCLI`, and legacy `bird` implementations, selecting the first one reporting `ok` status. This ensures the diagnostic remains robust even if users have different CLI tools installed for the same platform.