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

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

python -m agent_reach.cli doctor

Programmatic usage:

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:

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

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