How to Install Agent Reach for Python: Complete Setup Guide

Agent Reach installs via pipx or pip directly from GitHub, then runs agent-reach install --env=auto to configure core channels and optional platform backends like Twitter, Reddit, and XiaoHongShu.

Agent Reach is a lightweight Python router that enables AI agents to read and search content from more than a dozen internet platforms. Developed in the Panniantong/Agent-Reach repository, this tool acts as glue between your agent and various upstream tools rather than a monolithic wrapper. When you install Agent Reach for Python, you get a command-line interface that automatically detects your environment and wires together necessary dependencies.

Prerequisites

Before running the installer, ensure your system meets these baseline requirements:

• Python 3.8+ installed and available in your PATH
• pipx (strongly recommended for isolated installs) or pip with virtual environment support
• GitHub CLI (gh) and Node.js (optional but required for certain channels; the installer can auto-download these)

Installation Steps

1. Install the Package

The recommended method uses pipx to create an isolated environment and automatically add the agent-reach command to your PATH:

pipx install https://github.com/Panniantong/agent-reach/archive/main.zip

If you prefer a traditional virtual environment, use this alternative:

python3 -m venv ~/.agent-reach-venv
source ~/.agent-reach-venv/bin/activate
pip install https://github.com/Panniantong/agent-reach/archive/main.zip

2. Run the Core Installer

Execute the installation command with auto-detection mode to configure the minimal core plus zero-config channels (Web, YouTube, GitHub, RSS, Exa, and Bilibili):

agent-reach install --env=auto

According to the source code in agent_reach/cli.py, the _cmd_install function performs three deterministic phases:

1. System-level prerequisites – Checks for GitHub CLI, Node.js, and proxy support, auto-installing missing components unless running in safe mode.
2. mcporter & Exa search – Installs the mcporter Node package required for free Exa search and configures the default exa endpoint.
3. Optional channel back-ends – Pulls upstream tools like twitter-cli, opencli, rdt-cli, or bili-cli based on your --channels selection.

3. Configure Credentials

Many platforms require authentication tokens or browser cookies. The configuration manager in agent_reach/config.py persists settings to ~/.agent-reach/config.json.

Extract cookies automatically from Chrome or Firefox:

agent-reach configure --from-browser chrome

Or set credentials manually for specific services:

agent-reach configure twitter-cookies "auth_token=AAA; ct0=BBB"
agent-reach configure groq-key gsk_XXXXXXXXXXXXXXXX

4. Validate the Installation

Run the built-in diagnostics to verify each channel's health:

agent-reach doctor

The doctor routine, implemented in agent_reach/doctor.py, iterates over all channel classes and calls their check() method, aggregating results into a machine-readable report. Status indicators display as ✅ (ok), ⚠️ (warning), or ❌ (failed).

Installation Modes and Options

Auto-Detect vs. Manual Environment

The --env=auto flag detects whether you are running on a local desktop or headless server, adjusting the installation profile accordingly. Desktop environments receive additional Chrome extension guidance for platforms requiring browser automation.

Safe and Dry-Run Modes

Preview changes without modifying your system using these flags:

agent-reach install --env=auto --dry-run
agent-reach install --env=auto --safe

--dry-run reports what would be installed without executing changes. --safe mode performs read-only system checks and lists missing prerequisites without attempting auto-installation.

Adding Optional Channels

Extend Agent Reach beyond core platforms by specifying additional channels during installation:

agent-reach install --env=auto --channels=twitter,xiaohongshu,reddit

For a complete installation including all supported platforms:

agent-reach install --env=auto --channels=all

Note that desktop-only channels (like those requiring the OpenCLI Chrome extension) will print setup guides rather than auto-installing binaries.

Architecture Overview

Understanding the codebase structure helps troubleshoot installation issues:

• agent_reach/cli.py – Contains the CLI entry point and _cmd_install logic that orchestrates the three-phase installation flow.
• agent_reach/core.py – Implements the core router that dispatches read and search requests to appropriate channels.
• agent_reach/channels/base.py – Defines the abstract base class enforcing channel contracts (can_handle(), read(), search(), check()).
• agent_reach/config.py – Handles persistent JSON configuration storage in ~/.agent-reach/config.json.

The installer is pure Python; all external binaries are obtained via system package managers (apt, brew) or by invoking npm/pipx, making Agent Reach a router rather than a wrapper that preserves upstream tool performance.

Summary

• Install Agent Reach for Python using pipx install https://github.com/Panniantong/agent-reach/archive/main.zip for isolated, PATH-available execution.
• Run agent-reach install --env=auto to execute the three-phase installation (system prerequisites, mcporter/Exa setup, and optional channels).
• Use --dry-run or --safe flags to preview changes without system modification.
• Configure authentication via agent-reach configure commands, storing data in ~/.agent-reach/config.json.
• Validate setup using agent-reach doctor, which leverages agent_reach/doctor.py to check each channel's check() method.
• The architecture relies on agent_reach/cli.py for orchestration and agent_reach/core.py for routing, with channel contracts defined in agent_reach/channels/base.py.

Frequently Asked Questions

What is the difference between --dry-run and --safe mode?

--dry-run simulates the entire installation process and reports what actions would be taken without executing any system changes. --safe mode performs actual read-only system checks to identify missing prerequisites (like GitHub CLI or Node.js) but stops before auto-installing anything, providing a compatibility report instead.

Where does Agent Reach store configuration files?

Agent Reach stores persistent settings in ~/.agent-reach/config.json, managed by the Config class in agent_reach/config.py. This JSON file contains user-provided tokens, proxy settings, and extracted browser cookies. The CLI provides commands like agent-reach configure to modify these values without manual file editing.

Can I install Agent Reach without root privileges?

Yes. When using pipx, Agent Reach installs into a user-level isolated environment without requiring sudo or root access. The agent-reach command becomes available in your user PATH. Even when using pip with a virtual environment, the installation remains within your user directory, though some optional channel dependencies (like system-wide Node.js) may require elevated permissions if not already present.

How do I add support for additional platforms after initial installation?

Simply re-run the installer with the new channels specified: agent-reach install --env=auto --channels=twitter,xiaohongshu. The installer is idempotent and will only fetch and configure the missing upstream tools (like twitter-cli or opencli) without breaking existing functionality. For desktop platforms requiring Chrome extensions, follow the printed one-click guide after installation.

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