# panniantong/agent-reach architecture

> Architecture diagram of the GitHub repository panniantong/agent-reach, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/panniantong/agent-reach
- Repository: https://github.com/panniantong/agent-reach
- Video tour (about a minute): https://gitdiagram.com/panniantong/agent-reach/video

## Overview

Agent Reach is a command-line bridge that lets AI agents search and read supported web platforms through normalized channel actions. The main workflow is an agent command entering the CLI, dispatching to a channel action, trying its declared backend choices, and returning a unified result. Separate capabilities cover browser-backed sessions, channel/tool setup and maintenance, and video or podcast transcription. Relationships involving unsampled channel modules are limited to those documented by the README or visible in the source index.

Main entry points: [`agent_reach/runtime/dispatch.py`](https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/dispatch.py) (Action dispatcher), [`agent_reach/channels/base.py`](https://github.com/panniantong/agent-reach/blob/main/agent_reach/channels/base.py) (Channel actions), [`agent_reach/channels/bilibili.py`](https://github.com/panniantong/agent-reach/blob/main/agent_reach/channels/bilibili.py) (Bilibili), [`agent_reach/runtime/cli.py`](https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/cli.py) (Command handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command and dispatch"]
  node_cli["CLI entry<br/>[cli.py]"]
  node_runtime_cli["Command handlers<br/>[cli.py]"]
  node_dispatch["Action dispatcher<br/>[dispatch.py]"]
  node_result["Result envelope<br/>[result.py]"]
end

subgraph group_channels["Platform channels"]
  node_channel_base["Channel actions<br/>[base.py]"]
  node_bilibili["Bilibili<br/>[bilibili.py]"]
  node_web["Web search/read<br/>[web.py]"]
  node_v2ex["V2EX<br/>[v2ex.py]"]
  node_xueqiu["Xueqiu<br/>[xueqiu.py]"]
  node_other_channels["Other platforms"]
end

subgraph group_runtime["Execution and browser"]
  node_opencli["OpenCLI backend<br/>[opencli.py]"]
  node_browser["Owned browser<br/>[browser.py]"]
  node_binding["Browser binding<br/>[browser_binding.py]"]
  node_session_reuse["Session reuse<br/>[session_reuse.py]"]
  node_run["Tool runner<br/>[run.py]"]
end

subgraph group_ops["Setup and state"]
  node_manage["Channel management<br/>[manage.py]"]
  node_tools["Tool installer<br/>[tools.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_state[("State ledger<br/>[state.py]")]
  node_paths["Private paths<br/>[paths.py]"]
end

subgraph group_media["Media transcription"]
  node_transcribe["Transcription<br/>[transcribe.py]"]
end

node_agent(("AI agent"))
node_external_tools{{"Upstream tools"}}
node_platforms{{"Web platforms"}}
node_agent_result["Agent result"]

node_agent -->|"invokes"| node_cli
node_cli -->|"delegates to"| node_runtime_cli
node_runtime_cli -->|"dispatches actions"| node_dispatch
node_runtime_cli -->|"runs management"| node_manage
node_dispatch -->|"uses definitions"| node_channel_base
node_dispatch -->|"uses public web"| node_web
node_dispatch -->|"normalizes errors"| node_result
node_agent -->|"selects action"| node_bilibili
node_agent -->|"reads URL"| node_web
node_channel_base -.->|"declares actions"| node_bilibili
node_channel_base -.->|"declares actions"| node_v2ex
node_channel_base -.->|"declares actions"| node_xueqiu
node_channel_base -.->|"declares actions"| node_other_channels
node_bilibili -->|"runs tools"| node_run
node_web -->|"runs fallback"| node_run
node_xueqiu -->|"uses browser"| node_browser
node_run -->|"executes"| node_external_tools
node_opencli -->|"drives browser"| node_browser
node_opencli -->|"maps rows"| node_result
node_binding -->|"prepares session"| node_session_reuse
node_binding -->|"binds profile"| node_browser
node_session_reuse -->|"exports cookies"| node_opencli
node_manage -->|"installs tools"| node_tools
node_manage -->|"tracks status"| node_state
node_config -->|"reads state"| node_state
node_state -->|"uses private paths"| node_paths
node_bilibili -->|"transcribes media"| node_transcribe
node_transcribe -.->|"uses speech services"| node_external_tools
node_dispatch -.->|"queries platforms"| node_platforms
node_result -->|"returns envelope"| node_agent_result

click node_cli "https://github.com/panniantong/agent-reach/blob/main/agent_reach/cli.py"
click node_runtime_cli "https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/cli.py"
click node_dispatch "https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/dispatch.py"
click node_result "https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/result.py"
click node_channel_base "https://github.com/panniantong/agent-reach/blob/main/agent_reach/channels/base.py"
click node_bilibili "https://github.com/panniantong/agent-reach/blob/main/agent_reach/channels/bilibili.py"
click node_web "https://github.com/panniantong/agent-reach/blob/main/agent_reach/channels/web.py"
click node_v2ex "https://github.com/panniantong/agent-reach/blob/main/agent_reach/channels/v2ex.py"
click node_xueqiu "https://github.com/panniantong/agent-reach/blob/main/agent_reach/channels/xueqiu.py"
click node_other_channels "https://github.com/panniantong/agent-reach/tree/main/agent_reach/channels"
click node_opencli "https://github.com/panniantong/agent-reach/blob/main/agent_reach/backends/opencli.py"
click node_browser "https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/browser.py"
click node_binding "https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/browser_binding.py"
click node_session_reuse "https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/session_reuse.py"
click node_run "https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/run.py"
click node_manage "https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/manage.py"
click node_tools "https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/tools.py"
click node_config "https://github.com/panniantong/agent-reach/blob/main/agent_reach/config.py"
click node_state "https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/state.py"
click node_paths "https://github.com/panniantong/agent-reach/blob/main/agent_reach/utils/paths.py"
click node_transcribe "https://github.com/panniantong/agent-reach/blob/main/agent_reach/transcribe.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_runtime_cli,node_dispatch,node_result toneBlue
class node_channel_base,node_bilibili,node_web,node_v2ex,node_xueqiu,node_other_channels toneAmber
class node_opencli,node_browser,node_binding,node_session_reuse,node_run toneMint
class node_manage,node_tools,node_config,node_state,node_paths toneRose
class node_transcribe,node_agent,node_external_tools,node_platforms,node_agent_result toneIndigo
```

## Components

### Command and dispatch

- [CLI entry](https://github.com/panniantong/agent-reach/blob/main/agent_reach/cli.py): `agent_reach/cli.py`
- [Command handlers](https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/cli.py): `agent_reach/runtime/cli.py`
- [Action dispatcher](https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/dispatch.py): `agent_reach/runtime/dispatch.py`
- [Result envelope](https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/result.py): `agent_reach/runtime/result.py`

### Platform channels

- [Channel actions](https://github.com/panniantong/agent-reach/blob/main/agent_reach/channels/base.py): `agent_reach/channels/base.py`
- [Bilibili](https://github.com/panniantong/agent-reach/blob/main/agent_reach/channels/bilibili.py): `agent_reach/channels/bilibili.py`
- [Web search/read](https://github.com/panniantong/agent-reach/blob/main/agent_reach/channels/web.py): `agent_reach/channels/web.py`
- [V2EX](https://github.com/panniantong/agent-reach/blob/main/agent_reach/channels/v2ex.py): `agent_reach/channels/v2ex.py`
- [Xueqiu](https://github.com/panniantong/agent-reach/blob/main/agent_reach/channels/xueqiu.py): `agent_reach/channels/xueqiu.py`
- [Other platforms](https://github.com/panniantong/agent-reach/tree/main/agent_reach/channels): `agent_reach/channels`

### Execution and browser

- [OpenCLI backend](https://github.com/panniantong/agent-reach/blob/main/agent_reach/backends/opencli.py): `agent_reach/backends/opencli.py`
- [Owned browser](https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/browser.py): `agent_reach/runtime/browser.py`
- [Browser binding](https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/browser_binding.py): `agent_reach/runtime/browser_binding.py`
- [Session reuse](https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/session_reuse.py): `agent_reach/runtime/session_reuse.py`
- [Tool runner](https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/run.py): `agent_reach/runtime/run.py`

### Setup and state

- [Channel management](https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/manage.py): `agent_reach/runtime/manage.py`
- [Tool installer](https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/tools.py): `agent_reach/runtime/tools.py`
- [Configuration](https://github.com/panniantong/agent-reach/blob/main/agent_reach/config.py): `agent_reach/config.py`
- [State ledger](https://github.com/panniantong/agent-reach/blob/main/agent_reach/runtime/state.py): `agent_reach/runtime/state.py`
- [Private paths](https://github.com/panniantong/agent-reach/blob/main/agent_reach/utils/paths.py): `agent_reach/utils/paths.py`

### Media transcription

- [Transcription](https://github.com/panniantong/agent-reach/blob/main/agent_reach/transcribe.py): `agent_reach/transcribe.py`

### Other components

- **AI agent**
- **Upstream tools**
- **Web platforms**
- **Agent result**

## Connections

- AI agent → CLI entry: invokes (evidence: `README.md`)
- CLI entry → Command handlers: delegates to (evidence: `agent_reach/cli.py`)
- Command handlers → Action dispatcher: dispatches actions (evidence: `agent_reach/runtime/cli.py`)
- Command handlers → Channel management: runs management (evidence: `agent_reach/runtime/cli.py`)
- Action dispatcher → Channel actions: uses definitions (evidence: `agent_reach/runtime/dispatch.py`)
- Action dispatcher → Web search/read: uses public web (evidence: `agent_reach/runtime/dispatch.py`)
- Action dispatcher → Result envelope: normalizes errors (evidence: `agent_reach/runtime/dispatch.py`)
- AI agent → Bilibili: selects action (evidence: `README.md`)
- AI agent → Web search/read: reads URL (evidence: `README.md`)
- Channel actions → Bilibili: declares actions (evidence: `agent_reach/channels/bilibili.py`)
- Channel actions → V2EX: declares actions (evidence: `agent_reach/channels/v2ex.py`)
- Channel actions → Xueqiu: declares actions (evidence: `agent_reach/channels/xueqiu.py`)
- Channel actions → Other platforms: declares actions (evidence: `agent_reach/channels/xueqiu.py`)
- Bilibili → Tool runner: runs tools (evidence: `agent_reach/channels/bilibili.py`)
- Web search/read → Tool runner: runs fallback (evidence: `agent_reach/channels/web.py`)
- Xueqiu → Owned browser: uses browser (evidence: `agent_reach/channels/xueqiu.py`)
- Tool runner → Upstream tools: executes (evidence: `agent_reach/runtime/run.py`)
- OpenCLI backend → Owned browser: drives browser (evidence: `agent_reach/backends/opencli.py`)
- OpenCLI backend → Result envelope: maps rows (evidence: `agent_reach/backends/opencli.py`)
- Browser binding → Session reuse: prepares session (evidence: `agent_reach/runtime/browser_binding.py`)
- Browser binding → Owned browser: binds profile (evidence: `agent_reach/runtime/browser_binding.py`)
- Session reuse → OpenCLI backend: exports cookies (evidence: `agent_reach/runtime/session_reuse.py`)
- Channel management → Tool installer: installs tools (evidence: `agent_reach/runtime/manage.py`)
- Channel management → State ledger: tracks status (evidence: `agent_reach/runtime/manage.py`)
- Configuration → State ledger: reads state (evidence: `agent_reach/config.py`)
- State ledger → Private paths: uses private paths (evidence: `agent_reach/runtime/state.py`)
- Bilibili → Transcription: transcribes media
- Transcription → Upstream tools: uses speech services
- Action dispatcher → Web platforms: queries platforms
- Result envelope → Agent result: returns envelope (evidence: `README.md`)
