How to Perform a Health Check with the Agent Reach Doctor Command

Run agent-reach doctor to verify that every registered channel (Twitter, Reddit, YouTube, etc.) is properly configured and ready for use.

The doctor command is the built-in diagnostic tool for the Agent Reach framework. It probes all configured channels, validates authentication states, and identifies misconfigurations before they cause runtime failures. This guide covers both CLI usage and programmatic access based on the Panniantong/Agent-Reach source code.

Running the Doctor Command

Agent Reach provides a first-class CLI entry point for health diagnostics. The command is implemented in [agent_reach/cli.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) within the _cmd_doctor function (around line 1447).

Basic Usage

Execute the standard health check from your terminal:

agent-reach doctor

Alternatively, invoke the module directly:

python -m agent_reach.cli doctor

The output displays a tiered summary (0 = zero-config, 1 = optional key-login, 2 = complex setup) showing which backends are authenticated and operational:

✅ Ready to use:
  ✅ Twitter  — Logged in
  [!] Reddit  — Login required
Status: 7/9 channels available

JSON Output

For CI/CD pipelines or automated monitoring, use the --json flag to emit machine-readable results:

agent-reach doctor --json

This outputs a structured dictionary containing status, tier levels, active backends, and descriptive messages for every registered channel.

How the Health Check Works Internally

The diagnostic flow follows a three-stage pipeline defined in agent_reach/doctor.py.

Configuration Loading

First, Config() initializes by reading ~/.agent-reach/config.yaml. This determines which channels are enabled and what credentials are available. According to the source, if the config file has world-readable permissions, the doctor emits a security warning (lines 109-124) before proceeding with checks.

Channel Verification

The check_all(config) function (implemented at line 12 of [doctor.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)) iterates over every registered channel:

1. Each channel implements a check(config) method returning a (status, message) tuple.
2. Common statuses include "ok", "warn", "off", and "error".
3. Exceptions within individual channels are isolated so one broken backend cannot crash the entire report.

Individual channel implementations (e.g., agent_reach/channels/twitter.py, agent_reach/channels/reddit.py) contain the backend-specific logic for validating tokens and connectivity.

Report Rendering

Results are formatted based on output mode:

• Human-readable: format_report(results) (lines 47-99) generates a Rich-markup table with color-coded status indicators.
• Machine-readable: json.dumps serializes the raw results dictionary.

After printing the report, the CLI automatically triggers _install_skill() to ensure the Agent Reach skill is registered locally.

Programmatic Health Checks

You can import the health-checking logic directly into Python scripts without invoking the subprocess.

Generating a Standard Report

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

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

print(format_report(results))       # Pretty output matching CLI

Filtering for Failed Channels

To isolate only the channels requiring attention:

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

failures = {k: v for k, v in check_all(Config()).items()
            if v["status"] in ("warn", "off", "error")}
print(f"Problematic channels: {list(failures)}")

This pattern is useful for building custom alerting systems that monitor specific authentication states.

Security and Post-Check Actions

The doctor performs two critical housekeeping tasks:

• Permission Validation: Detects if config.yaml is world-readable and warns the user to restrict file permissions.
• Skill Auto-Installation: Runs _install_skill() after every health check to ensure the local Agent Reach skill is synchronized with the current environment configuration.

Summary

• Entry point: Use agent-reach doctor or the _cmd_doctor handler in agent_reach/cli.py.
• Core logic: The check_all() function in agent_reach/doctor.py validates every channel's check() method.
• Output formats: Human-readable tables via format_report(), or JSON with --json.
• Configuration: Reads from ~/.agent-reach/config.yaml and warns on insecure permissions.
• Automation: Call check_all(Config()) programmatically to integrate health data into custom workflows.

Frequently Asked Questions

What does the "need login" status mean?

This indicates a configured channel is enabled but lacks valid authentication credentials. Tier 1 channels (like Reddit) require manual login or API key configuration in ~/.agent-reach/config.yaml, whereas Tier 0 channels (like Twitter in some modes) work without credentials.

Can I run health checks without the CLI?

Yes. Import check_all from agent_reach.doctor and pass it a Config instance. This returns a dictionary of statuses without triggering the CLI's auto-installation routine, making it ideal for headless server environments.

Why does the doctor command auto-install skills?

The _install_skill() call ensures that any configuration changes detected during the health check are immediately reflected in the installed Agent Reach skill. This keeps the framework's runtime behavior synchronized with its configuration state.

How are channel tiers determined?

Tiers classify setup complexity: Tier 0 channels work out-of-the-box with zero configuration; Tier 1 requires optional keys or login; Tier 2 demands complex setup (e.g., custom endpoints or OAuth flows). The doctor groups output by these tiers to help prioritize configuration efforts.

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