How Agent-Reach Doctor Diagnoses Platform Availability: A Technical Deep Dive

The Agent-Reach doctor diagnoses platform availability by iterating over registered channel objects, executing their check() methods in isolated try/except blocks, and aggregating per-channel health status into a Rich-formatted report that identifies available backends, configuration tiers, and actionable remediation steps.

Agent Reach includes a built-in diagnostic system that audits the health of every supported platform (or "channel") you can route through the framework. This doctor utility probes CLI binaries, environment variables, and API credentials to determine whether each channel is ready for use. Understanding how the agent-reach doctor diagnoses platform availability helps you troubleshoot integration failures and validate your deployment before running agents.

The Diagnostic Architecture

The health check system separates concerns between channel registration, individual platform probing, and report aggregation. This design ensures that a single failing channel never aborts the entire diagnostic session.

Channel Registry and Collection

All supported channels are registered in agent_reach/channels/__init__.py, which builds a list of instantiated channel classes called ALL_CHANNELS. When the doctor runs, it calls get_all_channels() to retrieve this registry, providing a centralized inventory of every platform Agent Reach can utilize.

The Doctor Orchestrator

The core logic resides in agent_reach/doctor.py. The check_all() function iterates over the channel list and invokes each channel's check() method inside a try/except block. This isolation prevents exceptions in one platform check (e.g., a missing binary) from crashing the entire audit.

How Individual Channels Report Health

Each platform implements a consistent health-check interface while handling its own backend-specific logic.

Base Channel Contract

Every channel inherits from agent_reach/channels/base.py and implements check(self, config=None). This method returns a tuple (status, message) where status is one of:

• ok – fully operational
• warn – installed but needs configuration
• error – missing dependencies or broken
• off – explicitly disabled

Multi-Backend Probing with Twitter

Concrete implementations demonstrate the flexibility of this system. In agent_reach/channels/twitter.py, the doctor evaluates multiple backends in priority order: twitter-cli, OpenCLI, and the legacy bird CLI.

The channel uses probe_command from agent_reach/probe.py to detect whether a command is missing, broken, or times out. Based on the probe result, it maps the outcome to the appropriate status and identifies which backend satisfied the check.

Aggregation and Reporting

The doctor aggregates results into a dictionary keyed by channel name, built in check_all(). Each entry contains:

• status – the health state
• name – human-readable description
• message – diagnostic details
• tier – configuration complexity (0 = no config, 1 = free key/login, 2 = optional complex setup)
• backends – available backend options
• active_backend – the backend that passed the check, if any

The format_report(results) function transforms this data into a Rich-markup string. It groups channels by tier, displays icons (✅ available, ⚠️ needs credentials, ❌ missing), and surfaces security warnings like insecure config.yaml permissions on Unix systems.

Running the Doctor

You can invoke the diagnostic via CLI or programmatically.

Command-Line Usage

Run the complete health audit from your terminal:

python -m agent_reach.cli doctor

Programmatic Diagnostics

Import the doctor functions to inspect platform health within your Python code:

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

For targeted debugging, manually instantiate a specific channel:

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 diagnoses platform availability by orchestrating health checks across all registered channels in agent_reach/channels/__init__.py.
• Each channel implements a check() method defined in agent_reach/channels/base.py that returns standardized status codes and probes binaries via agent_reach/probe.py.
• Fault isolation is achieved through try/except blocks in agent_reach/doctor.py, ensuring one broken channel doesn't crash the entire report.
• Results aggregate into a structured dictionary containing status, tier levels, and active backends, then render via format_report() with Rich formatting and security warnings.
• Invoke diagnostics via python -m agent_reach.cli doctor or import check_all() programmatically for custom health monitoring.

Frequently Asked Questions

How does the Agent-Reach doctor handle missing CLI dependencies?

The doctor uses probe_command from agent_reach/probe.py to safely execute external commands and classify outcomes as missing, broken, or timed out. When a dependency is missing, the channel returns an error status with a message indicating the required installation command, while the doctor continues checking other channels due to its try/except isolation.

What do the tier levels (0, 1, 2) indicate in the doctor report?

Tier levels indicate configuration complexity: Tier 0 requires no configuration (works out of the box), Tier 1 requires free API keys or basic login credentials, and Tier 2 involves optional complex setup like enterprise authentication or multiple environment variables. The format_report() function groups channels by these tiers to help users prioritize which platforms they can use immediately versus those requiring setup.

Can I run health checks for a single platform instead of all channels?

Yes, you can instantiate individual channel classes directly from agent_reach/channels/ and call their check() method. For example, importing TwitterChannel from agent_reach/channels/twitter.py allows you to run twitter.check() to receive a (status, message) tuple without executing the full diagnostic suite.

Where does the doctor load configuration during the health check?

The doctor loads user configuration via Config() from agent_reach/config.py, which reads ~/.agent-reach/config.yaml. This configuration object is passed to each channel's check(config=None) method, allowing channels to verify that required API keys or authentication tokens are present and valid while reporting warn status for missing credentials.

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