How the Doctor Command Checks Platform Availability in Agent Reach

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 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, 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. 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 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.

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. Channel implementations like _check_twitter_cli at line 66 of 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:

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:

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.

Machine-Readable JSON Output

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

agent-reach doctor --json

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

{
  "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():

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 (_cmd_doctor) parses arguments and initializes the configuration before calling the diagnostic engine.
• check_all in 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, 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 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 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.

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