How the Agent Reach Doctor Command Verifies Channel Availability

The agent-reach doctor command verifies channel availability by iterating over all registered channel classes, invoking each channel's check() method to probe for required external tools and credentials, and aggregating the results into a human-readable health report.

The doctor sub-command serves as the health-checking engine for Agent Reach, an open-source platform that unifies social media integrations. When you run agent-reach doctor, the system validates that every supported channel—from Twitter to YouTube—is correctly installed and configured. This article examines the source code to explain exactly how the doctor command verifies channel availability.

Channel Discovery Through the Registry

The verification process begins by loading the complete registry of available channels. In agent_reach/channels/__init__.py, the framework maintains a global list named ALL_CHANNELS that contains every platform class. The function get_all_channels() exposes this registry to the doctor command.

When check_all() is invoked in agent_reach/doctor.py, it retrieves the list of channel objects by calling get_all_channels(). This design ensures that the doctor command automatically detects new channels as soon as they are added to the ALL_CHANNELS registry, without requiring manual updates to the health-check logic.

The Self-Diagnosis Pattern: Channel Check Methods

Each channel class inherits from agent_reach.channels.base.Channel, which defines the interface for health verification. The base class provides a default check() implementation that simply returns an "ok" status, suitable for built-in channels that require no external dependencies.

Concrete channel implementations override this method to perform platform-specific validation. The check() method receives the current configuration object and returns a tuple containing the status ("ok", "warn", "off", or "error") and a descriptive message.

Twitter Channel Verification Example

In agent_reach/channels/twitter.py, the TwitterChannel.check() method implements a multi-layered verification strategy. First, it uses shutil.which to locate the twitter-cli binary. If the binary is missing, it returns ("warn", "Twitter CLI 未安装...").

If the binary exists, the method executes twitter status and parses the output. A successful execution with valid authentication yields ("ok", "..."). If the binary is present but the user is not authenticated, it returns a distinct warning message indicating the authentication failure.

Other Platform-Specific Checks

Other channels follow the same pattern but probe for their respective external tools:

• YouTube: Verifies the presence of yt-dlp
• Weibo: Checks for mcporter
• Bilibili: Validates bili-cli installation

Each channel interprets exit codes and output to determine whether the external tool is properly installed and configured.

Aggregating Health Status in check_all()

The central orchestration logic resides in agent_reach/doctor.py. The check_all() function iterates over the channel list returned by get_all_channels() and invokes ch.check(config) for each instance.

For every channel, it collects:

• The dynamic status and message from the check() method
• Static metadata including name, description, tier, and back-ends

These results are stored in a dictionary keyed by the channel's name attribute, enabling downstream components to access both the health status and platform metadata.

Rendering the Health Report

After collecting statuses from all channels, agent_reach/doctor.py calls format_report() to transform the raw results into a human-readable display. This function uses the Rich library to generate styled output grouped by tier, with colored symbols indicating status.

The report displays categories such as "装好即用" (ready to use) and "可选渠道" (optional channels), followed by a summary line like "状态：✅ 3/5 个渠道可用" (Status: 3/5 channels available).

CLI Integration and Command Execution

The doctor command is registered in agent_reach/cli.py as a sub-parser. When invoked, the _cmd_doctor() function instantiates a Config() object and passes it to check_all(). After receiving the results dictionary, it prints the formatted report to the terminal.

This architecture separates the CLI interface from the core verification logic, allowing the health checks to be triggered programmatically or through other interfaces.

Code Examples

Run the health check from your terminal:

python -m agent_reach.cli doctor

Typical output shows tiered availability:

Agent Reach 状态
========================================

✅ 装好即用：
  ✅ YouTube — 内置
  ✅ GitHub — 内置

可选渠道（已安装）：
  ✅ Twitter — twitter-cli 完整可用（搜索、读推文、时间线、长文/Article、用户查询、Thread）
  ✅ Bilibili — bili-cli 已安装

状态：[green]4/5[/green] 个渠道可用
还有 1 个可选渠道可以解锁（Weibo），告诉你的 Agent「帮我装 Weibo」即可

Use the doctor functionality programmatically in your own scripts:

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

cfg = Config()
results = check_all(cfg)            # dict of channel statuses

print(format_report(results))       # pretty text report

Summary

• Registry-based discovery: The doctor command loads all channels from ALL_CHANNELS in agent_reach/channels/__init__.py, ensuring automatic detection of new platforms.
• Self-diagnostic pattern: Each channel implements a check() method that probes for required binaries and credentials, returning standardized status codes.
• Concrete implementations: Channels like Twitter verify specific CLI tools (twitter-cli) and authentication states, while others check for yt-dlp, mcporter, or bili-cli.
• Centralized aggregation: The check_all() function in agent_reach/doctor.py coordinates the verification workflow and compiles metadata.
• Rich formatting: The format_report() function generates color-coded, tier-grouped output showing exactly which channels are available and what is missing.

Frequently Asked Questions

How do I run the doctor command to check channel availability?

Execute python -m agent_reach.cli doctor from your terminal. The command automatically scans all registered channels in ALL_CHANNELS and displays a formatted report showing which platforms are ready to use and which require installation or configuration.

Can I use the doctor functionality programmatically without the CLI?

Yes. Import check_all and format_report from agent_reach.doctor, instantiate a Config object from agent_reach.config, and call check_all(cfg) to receive a dictionary of results. Pass this dictionary to format_report() to generate the same text output shown in the CLI, or inspect the results dictionary directly for automated health monitoring.

What statuses can the doctor command return for each channel?

The check() method returns one of four statuses: "ok" (fully operational), "warn" (installed but misconfigured or unauthenticated), "off" (not installed), or "error" (unexpected failure). These statuses determine the color coding and messaging in the final report generated by format_report().

How does adding a new channel affect the doctor command?

When you add a new channel class to agent_reach/channels/ and register it in ALL_CHANNELS within agent_reach/channels/__init__.py, the doctor command automatically includes it in health checks. You only need to implement the check() method in your channel class to define how the system verifies that platform's availability via agent_reach/doctor.py.

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