How the Agent-Reach Doctor Command Checks Channel Availability and Selects Backends

The doctor command iterates through every registered channel in agent_reach.channels, executes each channel's check() method with fault tolerance, and selects the first backend reporting "ok" status (or "warn" if no healthy backends exist) based on the ordering defined in Channel.ordered_backends().

The Agent-Reach repository provides a diagnostic doctor command that performs comprehensive health checks across all integrated channels. This command validates which backends are available and determines which specific implementation will handle requests for each channel. Understanding how the doctor command checks channel availability reveals the robust fallback mechanisms and configuration-driven backend selection that power the Agent-Reach ecosystem.

Channel Discovery and Registry Initialization

The doctor command begins by loading all available channels through the centralized registry.

In agent_reach/channels/__init__.py, the get_all_channels() function returns a list of instantiated channel objects. This module imports every concrete channel class (such as GitHub, Twitter, and YouTube) and stores singleton instances in ALL_CHANNELS. When the doctor command runs, it calls this registry to discover which channels are installed and available for health checks.

Protected Health Check Execution

Once channels are loaded, the doctor command iterates through them with defensive programming to ensure one failing channel does not crash the entire diagnostic report.

The doctor.check_all() function in agent_reach/doctor.py implements a protected loop:

for ch in get_all_channels():
    try:
        status, message = ch.check(config)
    except Exception as e:
        # Captures exception and marks channel as error

        status = "error"
        message = str(e)

This exception handling ensures that a misbehaving channel only produces a status="error" entry while allowing subsequent channels to proceed with their health checks. The results dictionary captures the health status, human-readable message, and the active backend for each channel.

Backend Ordering and Configuration Overrides

Before probing individual backends, the doctor command determines the evaluation order through the Channel.ordered_backends() method defined in agent_reach/channels/base.py.

This method returns the channel's backends list with a critical modification: it moves any user-specified override to the front. The override can be set via:

• The config file using the <channel>_backend key
• Environment variables using the <CHANNEL>_BACKEND key

For example, if you set TWITTER_BACKEND=twitter-cli in your environment, that backend will be checked first, regardless of the default ordering.

The Backend Selection Algorithm

Each concrete channel implements its own check() method that probes candidates in the order returned by ordered_backends(). The selection logic follows a strict priority system:

1. First "ok" wins: The first backend reporting a status of "ok" becomes channel.active_backend
2. Fallback to "warn": If no backend is "ok" but one reports "warn" (e.g., installed but not authenticated), the first such warning is selected
3. Error state: If all candidates are broken, the channel is marked as "error" with aggregated failure messages
4. Installation warning: If no backends are installed, the channel returns "warn" with installation instructions

In agent_reach/channels/twitter.py, this logic manifests as probing twitter-cli, then OpenCLI, then the legacy bird CLI. The channel uses agent_reach/probe.py helper functions like probe_command() to safely execute backend checks and classify results as missing, broken, timeout, or ok.

Implementation Files and Their Roles

The doctor command's functionality spans several key files:

• agent_reach/doctor.py: Orchestrates health checks, catches per-channel exceptions, and builds the final report
• agent_reach/channels/base.py: Defines the abstract Channel API, backend ordering logic, and default check() implementation
• agent_reach/channels/__init__.py: Registers every concrete channel for automatic discovery
• agent_reach/probe.py: Provides safe command execution and result classification utilities

Practical Usage Examples

You can invoke the doctor command programmatically or via CLI:

Programmatic usage:

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

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

status = check_all(cfg)            # → dict keyed by channel name

print(format_report(status))       # nicely formatted Rich output

CLI usage:

$ python -m agent_reach.cli doctor

# or, using the entry-point installed by pip

$ agent-reach doctor

Both approaches invoke the same check_all() flow that validates channel availability and determines active backends.

Summary

• The doctor command discovers channels via agent_reach.channels.get_all_channels(), which returns singleton instances from the channel registry
• Health checks run in a protected loop where individual channel failures are caught and reported as errors without aborting the entire diagnostic process
• Backend selection respects user configuration overrides through Channel.ordered_backends(), which prioritizes environment variables and config file settings
• The selection algorithm chooses the first backend with "ok" status, falls back to "warn" if necessary, and reports detailed error messages when all candidates fail
• Concrete implementations in individual channel files (like twitter.py) define specific probe logic while inheriting the base ordering and selection mechanisms

Frequently Asked Questions

How does the doctor command prevent one broken channel from crashing the entire report?

The check_all() function in agent_reach/doctor.py wraps each channel's check() call in a try-except block. When a channel raises an exception, the code catches it, assigns status="error" and message=str(e), and continues processing remaining channels. This ensures the final report contains status entries for all registered channels, even when some implementations are fundamentally broken.

Can I force the doctor command to use a specific backend for testing?

Yes, you can override the backend ordering by setting either a configuration key <channel>_backend in your ~/.agent-reach/config.yaml file or an environment variable <CHANNEL>_BACKEND. The Channel.ordered_backends() method detects these overrides and moves the specified backend to the front of the evaluation list, causing the doctor command to probe it first during the health check.

What is the difference between "warn" and "error" status in the doctor report?

A "warn" status indicates the channel has at least one backend installed but cannot fully function (typically due to missing authentication or partial configuration), while an "error" status means all candidate backends are either broken, missing, or threw unhandled exceptions. The doctor command selects the first "warn" backend as the active backend if no "ok" backends exist, but will not select any backend when the status is "error".

How does the doctor command know which backends to check for each channel?

Each concrete channel class defines a backends attribute listing its supported implementations. The base class method ordered_backends() in agent_reach/channels/base.py returns this list, applying any user-specified overrides. Individual channels like TwitterChannel in agent_reach/channels/twitter.py then iterate through this ordered list, probe each backend's availability, and apply the selection algorithm to determine which backend becomes the active one.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}