How to Add a Custom Channel for a New Platform in Agent Reach

To add a custom channel for a new platform in Agent Reach, subclass Channel in a new file under agent_reach/channels/, implement the required attributes and methods, and register the instance in the ALL_CHANNELS list inside agent_reach/channels/__init__.py.

Agent Reach treats every supported internet platform as a channel. Adding a custom channel for a new platform requires no changes to the core router or CLI logic; you only need to implement the abstract contract defined in agent_reach/channels/base.py and expose your class through the global registry.

Create a Channel Subclass

Start by adding a new Python module under agent_reach/channels/. For example, agent_reach/channels/myplatform.py. Inside this file, import Channel from .base and create a concrete subclass.

Define Mandatory Attributes

Every channel must declare four class-level attributes that the CLI and doctor command read at runtime:

• name — A short string identifier used on the CLI (for example, "myplatform").
• description — A human-readable summary of the platform.
• backends — A list of external tools required by the channel (for example, ["mytool"]). Leave this empty if no external binary is needed.
• tier — An integer indicating setup complexity: 0 for zero-config, 1 for a free API key, or 2 for full manual setup.

Implement can_handle

The can_handle(self, url: str) -> bool method is the routing gate. It receives a candidate URL and must return True when the hostname or path pattern matches your platform. The core router in agent_reach/core.py iterates over ALL_CHANNELS and delegates the URL to the first channel whose can_handle returns True.

Optionally Override check

Override check(self, config=None) when your channel depends on an external binary or credential file. Return a tuple of (status, message) where status is "ok", "warn", or "error". The doctor command displays this output during diagnostics.

# File: agent_reach/channels/myplatform.py

# -*- coding: utf-8 -*-

"""MyPlatform – example custom channel."""

from urllib.parse import urlparse
from .base import Channel


class MyPlatformChannel(Channel):
    name = "myplatform"
    description = "MyPlatform – custom video & article source"
    backends = ["mytool"]            # external binary that does the heavy lifting

    tier = 1                         # requires a free API key

    def can_handle(self, url: str) -> bool:
        """Accept URLs whose hostname matches myplatform.com."""
        host = urlparse(url).netloc.lower()
        return "myplatform.com" in host

    def check(self, config=None):
        """Verify that the required tool is installed."""
        import shutil
        binary = shutil.which("mytool")
        if binary:
            return "ok", "mytool is available"
        return "warn", (
            "mytool not found. Install with:\n"
            "    pipx install mytool"
        )

Register the Channel

Discovery depends on the global registry inside agent_reach/channels/__init__.py. Import your new class near the existing channel imports, instantiate it, and append it to ALL_CHANNELS. The order of items in the list does not matter.

# File: agent_reach/channels/__init__.py

# Add the import near the top with the other channel imports

from .myplatform import MyPlatformChannel

# Add the instance to the registry list

ALL_CHANNELS.append(MyPlatformChannel())

Once registered, the CLI, doctor, and core router automatically recognize the channel without further configuration.

Verify with the Doctor Command

After saving your files, run the built-in doctor to confirm that Agent Reach detects the new channel and that its dependencies are healthy:

$ python -m agent_reach.cli doctor
...
✅ myplatform – MyPlatform – custom video & article source (ok)

If you authored unit tests for can_handle or check, execute them with pytest:

pytest tests/ -v

Reference Implementation

If you need a production example of a concrete channel, examine agent_reach/channels/twitter.py. It demonstrates the same pattern: mandatory attributes, a hostname check inside can_handle, and optional validation logic inside check. The core routing logic in agent_reach/core.py and the CLI entry point in agent_reach/cli.py remain untouched because they rely entirely on the ALL_CHANNELS registry.

Summary

• Subclass Channel from agent_reach/channels/base.py in a new file under agent_reach/channels/.
• Declare name, description, backends, and tier so the CLI can catalog your platform.
• Implement can_handle to route URLs from your platform to the new channel.
• Optionally override check to surface dependency diagnostics.
• Import and append an instance to ALL_CHANNELS in agent_reach/channels/__init__.py.
• Run python -m agent_reach.cli doctor to verify that the channel is visible and healthy.

Frequently Asked Questions

What methods must I implement to add a custom channel for a new platform?

You must implement can_handle(self, url: str) -> bool. You should also define the four class attributes name, description, backends, and tier. The check method is optional but recommended if your channel relies on external binaries or credentials.

Do I need to modify agent_reach/core.py or agent_reach/cli.py?

No. The core router in agent_reach/core.py and the CLI in agent_reach/cli.py discover channels dynamically through the ALL_CHANNELS registry in agent_reach/channels/__init__.py. You only need to register your subclass there.

What is the purpose of the tier attribute?

The tier attribute signals how much setup the user must perform before the channel works. Use 0 for zero-config platforms, 1 for platforms that need a free API key, and 2 for platforms that require full manual setup or paid credentials.

How does Agent Reach route a URL to my custom channel?

During processing, agent_reach/core.py iterates over every instance in ALL_CHANNELS and calls can_handle(url) until one returns True. Because your registered subclass is part of that list, the router naturally considers it for any matching URL.

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