# What Are the Core Components of Agent-Reach? A Complete Architecture Guide

> Explore the core components of Agent-Reach. Learn about its modular CLI, YAML config manager, doctor system, pluggable channels, and utility layers in this architecture guide.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: architecture
- Published: 2026-06-18

---

**Agent-Reach consists of a modular CLI interface, YAML-backed configuration manager, health-checking doctor system, pluggable channel architecture for web platforms, and utility layers for probing and transcription.**

Agent-Reach is a lightweight "glue" layer that gives AI agents direct read and search access to a dozen web platforms without embedding proprietary APIs. According to the Panniantong/Agent-Reach source code, its architecture is intentionally modular, with each component living in its own Python module to expose clean contracts shared by the CLI, health-checker, and channel implementations. Understanding these core components helps developers extend the tool or integrate it programmatically into agent workflows.

## Command-Line Interface (cli.py)

The **Command-Line Interface** serves as the primary entry point for user interaction. Located at [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), it parses user commands—including `install`, `doctor`, `configure`, and `transcribe`—and delegates execution to the appropriate handler functions.

The `main()` function orchestrates argument parsing, while specialized handlers like `_cmd_doctor` instantiate the shared `Config` object and invoke health-check routines. The CLI also embeds the skill installer logic (`_install_skill`), which copies the [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) file into common agent skill directories such as OpenClaw, Claude Code, and generic `.agents` folders.

## Core Library (core.py)

For programmatic access, **Agent-Reach exposes a minimal public API** through the `AgentReach` class in [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py). This wrapper class allows agents to import the library directly and run health checks without shelling out to the CLI.

The class provides two key methods:

- `doctor()` – Returns a dictionary of per-channel health information
- `doctor_report()` – Returns a formatted Rich-styled string suitable for logs or UI display

This design enables seamless integration into automated agent workflows where direct Python invocation is preferred over subprocess calls.

## Configuration Management (config.py)

The **Configuration Manager** in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) handles persistent user settings. It stores configuration data—including proxy settings, API keys, and cookies—in `~/.agent-reach/config.yaml` and provides a uniform access API with environment-variable fallback support.

The `Config` class abstracts file I/O operations, ensuring that channel implementations and the doctor system can retrieve settings consistently without directly manipulating the filesystem.

## Health Checking System (doctor.py)

The **Doctor** component acts as the health-check orchestrator. Implemented in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), it aggregates status reports from all registered channels and renders readable Rich-styled output.

Key functions include:

- `check_all(config)` – Iterates over every channel returned by `get_all_channels()`, calling each channel's `check()` method
- `format_report(results)` – Pretty-prints aggregated results using Rich markup

When invoked via `python -m agent_reach.cli doctor`, the system probes each platform to confirm that required external tools (like `twitter-cli` or `rdt-cli`) are not merely present on `$PATH` but actually functional.

## Channel Architecture (channels/)

The **Channel Registry and Base Class** form the extensible backbone of Agent-Reach. Located in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) and [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py), these modules define the contract that all platform implementations must follow.

The abstract `Channel` base class specifies three critical methods:

- `can_handle(url)` – Determines if the channel can process a given URL
- `check(config)` – Validates that backend tools are installed and configured
- `ordered_backends()` – Respects user overrides via the `<channel>_backend` config key to select active backends

The registry in [`channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/channels/__init__.py) maintains `ALL_CHANNELS`, a list of instantiated channel objects, and exposes `get_all_channels()` for iteration.

## Platform-Specific Channels

Each supported platform lives as a **separate Python module** within `agent_reach/channels/`, isolating platform logic from core infrastructure. For example:

- [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py) – Handles Twitter/X URL detection and backend probing
- [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) – Manages YouTube-specific formatting and health checks
- [`agent_reach/channels/reddit.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/reddit.py) – Implements Reddit access patterns

Each file inherits from the base `Channel` class and implements platform-specific versions of `can_handle`, `check`, and backend handling. This modular approach allows developers to add support for new platforms without modifying core code.

## Backend Abstraction (backends/)

The **Backend Layer** provides optional cross-platform services that share resources across multiple channels. The primary implementation in [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py) offers a shared browser-session backend (local Chrome session) that several channels can utilize.

Channels specify their compatible backends via the `backends` class attribute, and the base class's `ordered_backends()` method handles selection logic based on user configuration overrides.

## Utility and Transcription Layers

Supporting functionality is organized into **utility modules** and specialized services:

- [`agent_reach/utils/text.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/text.py) and [`agent_reach/utils/process.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/process.py) – Provide text handling and subprocess probing helpers
- [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) – Executes lightweight commands to verify external tool functionality beyond simple path checks
- [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) – Wraps Whisper transcription via Groq or OpenAI for audio/video processing

These utilities are consumed by both the channel implementations and the doctor system to ensure consistent behavior across the codebase.

## Practical Implementation Examples

### Running Health Checks from the CLI

Invoke the doctor command to verify all platform integrations:

```bash
python -m agent_reach.cli doctor

```

This triggers the internal flow:

```python

# In cli.py → _cmd_doctor

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

config = Config()
results = check_all(config)          # ← loops over every channel

print(format_report(results))        # ← pretty Rich output

```

### Using the Library Programmatically

Import the core class for direct Python integration:

```python
from agent_reach.core import AgentReach
from agent_reach.config import Config

cfg = Config()
reach = AgentReach(cfg)

# Returns a dict of per-channel health info

status = reach.doctor()

# Nice formatted string for logs or UI

report = reach.doctor_report()
print(report)

```

### Adding a New Platform Channel

Create a new file in [`agent_reach/channels/myplatform.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/myplatform.py):

```python
from .base import Channel

class MyPlatformChannel(Channel):
    name = "myplatform"
    description = "MyPlatform – custom docs"
    backends = ["myplatform-cli"]
    tier = 1

    def can_handle(self, url: str) -> bool:
        return "myplatform.com" in url

```

Then import the class in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) and append an instance to `ALL_CHANNELS`. The health-checker automatically includes the new channel in its rotation.

## Summary

- **CLI Layer** ([`cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/cli.py)) handles argument parsing and command dispatch, including skill installation
- **Core API** ([`core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/core.py)) exposes the `AgentReach` class for programmatic health checks and configuration management
- **Configuration** ([`config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/config.py)) persists user settings in YAML format with environment-variable support
- **Doctor System** ([`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/doctor.py)) orchestrates health checks across all channels using Rich formatting
- **Channel Architecture** (`channels/`) uses an abstract base class and registry pattern to isolate platform-specific logic
- **Platform Modules** implement URL detection, backend probing, and formatting for individual services like Twitter and YouTube
- **Backend Abstraction** (`backends/`) allows shared resources such as browser sessions to service multiple channels
- **Utilities** ([`probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/probe.py), [`transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/transcribe.py), `utils/`) provide cross-cutting concerns like tool verification and audio transcription

## Frequently Asked Questions

### How does Agent-Reach verify that a platform is working?

Agent-Reach uses the **probe utilities** in [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) to execute lightweight commands that verify external tools (such as `twitter-cli` or `rdt-cli`) are functional, not merely present on `$PATH`. The [`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/doctor.py) module calls each channel's `check(config)` method, which returns a status of `ok`, `warn`, `off`, or `error` based on the probe results.

### Can I use Agent-Reach as a Python library instead of a CLI tool?

Yes. By importing `AgentReach` from [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py), you can instantiate the class with a `Config` object and invoke `doctor()` or `doctor_report()` methods programmatically. This allows seamless integration into agent workflows without subprocess overhead.

### How do I add support for a new web platform?

Create a new Python file in `agent_reach/channels/` that inherits from the `Channel` base class in [`base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/base.py). Implement the `can_handle()`, `check()`, and backend-related methods specific to your platform. Register the new channel by importing it in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) and adding an instance to the `ALL_CHANNELS` list.

### Where does Agent-Reach store user configuration?

Agent-Reach stores configuration data in `~/.agent-reach/config.yaml` via the `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). The system supports environment-variable fallbacks and provides a uniform API for retrieving settings such as proxy configurations, API keys, and cookies.