# How Agent-Reach Doctor Diagnoses Platform Availability: A Technical Deep Dive

> Discover how Agent-Reach doctor diagnoses platform availability by checking channel health, identifying issues, and generating actionable reports.

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

---

**The Agent-Reach doctor diagnoses platform availability by iterating over registered channel objects, executing their `check()` methods in isolated `try/except` blocks, and aggregating per-channel health status into a Rich-formatted report that identifies available backends, configuration tiers, and actionable remediation steps.**

Agent Reach includes a built-in diagnostic system that audits the health of every supported platform (or "channel") you can route through the framework. This **doctor** utility probes CLI binaries, environment variables, and API credentials to determine whether each channel is ready for use. Understanding how the agent-reach doctor diagnoses platform availability helps you troubleshoot integration failures and validate your deployment before running agents.

## The Diagnostic Architecture

The health check system separates concerns between channel registration, individual platform probing, and report aggregation. This design ensures that a single failing channel never aborts the entire diagnostic session.

### Channel Registry and Collection

All supported channels are registered in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py), which builds a list of instantiated channel classes called `ALL_CHANNELS`. When the doctor runs, it calls `get_all_channels()` to retrieve this registry, providing a centralized inventory of every platform Agent Reach can utilize.

### The Doctor Orchestrator

The core logic resides in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py). The `check_all()` function iterates over the channel list and invokes each channel's `check()` method inside a `try/except` block. This isolation prevents exceptions in one platform check (e.g., a missing binary) from crashing the entire audit.

## How Individual Channels Report Health

Each platform implements a consistent health-check interface while handling its own backend-specific logic.

### Base Channel Contract

Every channel inherits from [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) and implements `check(self, config=None)`. This method returns a tuple `(status, message)` where status is one of:
- `ok` – fully operational
- `warn` – installed but needs configuration
- `error` – missing dependencies or broken
- `off` – explicitly disabled

### Multi-Backend Probing with Twitter

Concrete implementations demonstrate the flexibility of this system. In [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py), the doctor evaluates multiple backends in priority order: `twitter-cli`, `OpenCLI`, and the legacy `bird CLI`.

The channel uses `probe_command` from [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) to detect whether a command is missing, broken, or times out. Based on the probe result, it maps the outcome to the appropriate status and identifies which backend satisfied the check.

## Aggregation and Reporting

The doctor aggregates results into a dictionary keyed by channel name, built in `check_all()`. Each entry contains:
- `status` – the health state
- `name` – human-readable description
- `message` – diagnostic details
- `tier` – configuration complexity (0 = no config, 1 = free key/login, 2 = optional complex setup)
- `backends` – available backend options
- `active_backend` – the backend that passed the check, if any

The `format_report(results)` function transforms this data into a Rich-markup string. It groups channels by tier, displays icons (✅ available, ⚠️ needs credentials, ❌ missing), and surfaces security warnings like insecure [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) permissions on Unix systems.

## Running the Doctor

You can invoke the diagnostic via CLI or programmatically.

### Command-Line Usage

Run the complete health audit from your terminal:

```bash
python -m agent_reach.cli doctor

```

### Programmatic Diagnostics

Import the doctor functions to inspect platform health within your Python code:

```python
from agent_reach.config import Config
from agent_reach.doctor import check_all, format_report

cfg = Config()                     # loads ~/.agent-reach/config.yaml

raw = check_all(cfg)               # dict of per-channel status

report = format_report(raw)        # Rich-markup string

print(report)                      # prints the health summary

```

### Inspecting a Single Channel

For targeted debugging, manually instantiate a specific channel:

```python
from agent_reach.channels.twitter import TwitterChannel

twitter = TwitterChannel()
status, message = twitter.check()
print(f"Twitter status: {status}\nDetails: {message}")

```

## Summary

- The **agent-reach doctor** diagnoses platform availability by orchestrating health checks across all registered channels in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py).
- Each channel implements a `check()` method defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) that returns standardized status codes and probes binaries via [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py).
- **Fault isolation** is achieved through `try/except` blocks in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), ensuring one broken channel doesn't crash the entire report.
- Results aggregate into a structured dictionary containing status, tier levels, and active backends, then render via `format_report()` with Rich formatting and security warnings.
- Invoke diagnostics via `python -m agent_reach.cli doctor` or import `check_all()` programmatically for custom health monitoring.

## Frequently Asked Questions

### How does the Agent-Reach doctor handle missing CLI dependencies?

The doctor uses `probe_command` from [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) to safely execute external commands and classify outcomes as missing, broken, or timed out. When a dependency is missing, the channel returns an `error` status with a message indicating the required installation command, while the doctor continues checking other channels due to its `try/except` isolation.

### What do the tier levels (0, 1, 2) indicate in the doctor report?

Tier levels indicate configuration complexity: **Tier 0** requires no configuration (works out of the box), **Tier 1** requires free API keys or basic login credentials, and **Tier 2** involves optional complex setup like enterprise authentication or multiple environment variables. The `format_report()` function groups channels by these tiers to help users prioritize which platforms they can use immediately versus those requiring setup.

### Can I run health checks for a single platform instead of all channels?

Yes, you can instantiate individual channel classes directly from `agent_reach/channels/` and call their `check()` method. For example, importing `TwitterChannel` from [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py) allows you to run `twitter.check()` to receive a `(status, message)` tuple without executing the full diagnostic suite.

### Where does the doctor load configuration during the health check?

The doctor loads user configuration via `Config()` from [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), which reads `~/.agent-reach/config.yaml`. This configuration object is passed to each channel's `check(config=None)` method, allowing channels to verify that required API keys or authentication tokens are present and valid while reporting `warn` status for missing credentials.