# How the `agent-reach doctor` Command Diagnoses Platform Availability

> Discover how agent-reach doctor diagnoses platform availability by auditing channels, running check methods, and generating a health report with fix instructions.

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

---

**The `agent-reach doctor` command audits every supported platform by iterating through registered channel classes, executing each channel's isolated `check()` method, and aggregating results into a tiered health report with actionable fix instructions.**

Agent Reach is an open-source routing framework that supports multiple communication platforms (or "channels"). The `agent-reach doctor` command—implemented in the [Panniantong/Agent-Reach](https://github.com/Panniantong/Agent-Reach) repository—provides a comprehensive health audit of every supported channel, helping users identify missing dependencies, configuration gaps, and available backends.

## How the Diagnostic Engine Works

The diagnostic flow follows a five-step pipeline that isolates failures and produces actionable results.

### Step 1: Channel Discovery via Registry

The doctor first collects all available channel implementations. In [[`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py), the registry builds a list of instantiated channel classes called `ALL_CHANNELS`. The function `get_all_channels()` returns this list, ensuring the doctor knows exactly which platforms (Twitter, Slack, Email, etc.) are supported by the current installation.

### Step 2: Isolated Health Check Execution

In [[`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), the `check_all()` function iterates over the `ALL_CHANNELS` list and invokes each channel's `check()` method inside a `try/except` block. This isolation ensures that a failure in one channel—such as a missing Python dependency or a network timeout—never aborts the entire diagnostic report. The doctor captures exceptions gracefully and records them as `error` status for that specific channel.

### Step 3: Channel-Specific Availability Probing

Every channel inherits from the abstract base class in [[`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py). Each implementation must define a `check(self, config=None)` method that probes the underlying tools (CLI binaries, OpenCLI, environment variables) and returns a tuple `(status, message)`.

For example, [[`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py) attempts backends in priority order: `twitter-cli`, `OpenCLI`, and the legacy `bird CLI`. It uses the **`probe_command`** utility from [[`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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. The method then maps the probe result to one of four statuses:

- **`ok`** – Backend available and functional
- **`warn`** – Installed but missing credentials or configuration
- **`error`** – Command broken or dependency missing
- **`off`** – Channel explicitly disabled

### Step 4: Result Aggregation

The `check_all()` function aggregates results into a dictionary keyed by channel name. For each channel, it stores:

- **`status`** – The health state (`ok`, `warn`, `error`, or `off`)
- **`name`** – Human-readable channel description
- **`message`** – Diagnostic text explaining the status
- **`tier`** – Configuration complexity level (0 = no config required, 1 = free key/login needed, 2 = optional complex setup)
- **`backends`** – List of possible backends for the platform
- **`active_backend`** – The specific backend that satisfied the health check, if any

This structure allows the doctor to present granular details while supporting platforms with multiple implementation options (e.g., a channel that can use either a native CLI or a Docker container).

### Step 5: Human-Friendly Report Generation

Finally, `format_report(results)` converts the dictionary into a Rich-markup string. The report groups channels by their **tier** level, displays visual icons (`✅` for available, `⚠️` for credential issues, `❌` for missing dependencies), and notes the `active_backend` when multiple options exist. On Unix systems, the doctor also warns about insecure `~/.agent-reach/config.yaml` permissions, suggesting `chmod 600` to protect API tokens.

## Running the Doctor: CLI and Programmatic Examples

You can invoke the diagnostic from the command line or integrate it into Python workflows.

**Command-line execution:**

```bash
python -m agent_reach.cli doctor

```

**Programmatic usage:**

```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 manually:**

```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` command discovers platforms via the `ALL_CHANNELS` registry in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py).
- Each channel's `check()` method runs in isolation using `try/except` blocks to prevent cascade failures.
- Health checks probe actual CLI binaries and environment variables, mapping results to `ok`, `warn`, `error`, or `off` statuses.
- Results include **tier** levels (0-2) and **active_backend** information to guide configuration complexity.
- The report generator uses Rich markup to display visual indicators and security warnings about file permissions.

## Frequently Asked Questions

### What do the four status values mean in the doctor report?

The statuses map to specific actionable states. **`ok`** means the channel is fully operational with an active backend. **`warn`** indicates the tool is installed but lacks credentials or configuration (e.g., missing `TWITTER_AUTH_TOKEN`). **`error`** signals a broken installation or missing dependency. **`off`** means the channel is explicitly disabled by the user or configuration.

### How does the doctor handle channels with multiple backends?

Channels like Twitter support fallback backends (`twitter-cli`, `OpenCLI`, `bird CLI`). The `check()` method probes each in priority order and sets `active_backend` to the first successful one. The final report displays which backend satisfied the health check, allowing users to understand which binary is actually being used or why a preferred option failed.

### Can I run the doctor on a subset of channels or a single channel?

While the CLI command `python -m agent_reach.cli doctor` audits all registered channels, you can programmatically check individual channels by instantiating the specific class (e.g., `TwitterChannel()`) and calling its `check()` method directly, as shown in the programmatic examples above.

### Why does the doctor warn about file permissions on Unix systems?

When `~/.agent-reach/config.yaml` is readable by group or others (mode `644` or `755`), the doctor outputs a security warning recommending `chmod 600`. This prevents API tokens and authentication secrets stored in the configuration file from being exposed to other users on the system, following standard Unix security practices for credential files.