# unlinearity/cli-wechat-bridge architecture

> Architecture diagram of the GitHub repository unlinearity/cli-wechat-bridge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/unlinearity/cli-wechat-bridge
- Repository: https://github.com/unlinearity/cli-wechat-bridge

## Overview

CLI WeChat Bridge connects WeChat or WeCom to locally running Codex, Claude Code, OpenCode, and Pi sessions, keeping the local CLI as the primary workspace. The main flow is remote message → channel transport → bridge routing and adapter → local CLI → output relayed to the channel; a daemon can manage multiple CLI sessions. Setup, approval/input handling, attachments, session resumption, and health checks are additional capabilities. Relationships are limited to README statements and shown source references/calls; several major subsystems are represented by their exact source paths, though their internals were not sampled.

Main entry points: [`src/bridge/bridge-adapters.ts`](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/bridge/bridge-adapters.ts) (Adapter selection), [`src/wechat/wechat-transport.ts`](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/wechat/wechat-transport.ts) (WeChat channel), [`src/channels/wecom/wecom-transport.ts`](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/channels/wecom/wecom-transport.ts) (WeCom channel), [`src/daemon/wechat-daemon.ts`](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/daemon/wechat-daemon.ts) (Multi-CLI daemon)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_channels["Remote channels"]
  node_wechat["WeChat channel"]
  node_wecom["WeCom channel<br/>[wecom-transport.ts]"]
  node_channel_factory["Channel drivers"]
  node_wechat_forward["WeChat forwarding"]
end

subgraph group_runtime["Bridge runtime"]
  node_channel_types["Channel contracts<br/>[channel-types.ts]"]
  node_daemon["Multi-CLI daemon<br/>[wechat-daemon.ts]"]
  node_router["Message router"]
  node_turns["Turn coordination"]
  node_bridge["Bridge orchestration<br/>[wechat-bridge.ts]"]
end

subgraph group_adapters["CLI adapters"]
  node_adapter_factory["Adapter selection<br/>[bridge-adapters.ts]"]
  node_codex["Codex adapter"]
  node_claude["Claude adapter"]
  node_opencode["OpenCode adapter"]
  node_pi["Pi adapter"]
  node_shared["Adapter support"]
  node_companion["Visible CLI companion<br/>[local-companion.ts]"]
end

subgraph group_support["Setup and state"]
  node_endpoint["Companion endpoints"]
  node_state["Bridge state<br/>[bridge-state.ts]"]
  node_config["Channel setup and config<br/>[channel-config.ts]"]
  node_wechat_setup["WeChat setup<br/>[setup.ts]"]
  node_wecom_setup["WeCom setup<br/>[setup.ts]"]
  node_doctor["Environment doctor<br/>[doctor.ts]"]
end

node_user(("Remote user"))
node_local_cli(("Local CLI user"))

node_user -->|"sends messages"| node_wechat
node_user -->|"sends messages"| node_wecom
node_wechat -->|"provides channel"| node_channel_factory
node_wecom -->|"provides channel"| node_channel_factory
node_channel_factory -->|"uses contracts"| node_channel_types
node_wechat_forward -->|"sends replies"| node_wechat
node_daemon -->|"routes messages"| node_router
node_router -->|"uses contracts"| node_channel_types
node_turns -->|"uses contracts"| node_channel_types
node_daemon -->|"selects adapter"| node_adapter_factory
node_adapter_factory -->|"dispatches"| node_codex
node_adapter_factory -->|"dispatches"| node_claude
node_adapter_factory -->|"dispatches"| node_opencode
node_adapter_factory -->|"dispatches"| node_pi
node_codex -->|"uses helpers"| node_shared
node_claude -->|"runs locally"| node_local_cli
node_codex -->|"runs locally"| node_local_cli
node_opencode -->|"runs locally"| node_local_cli
node_pi -->|"runs locally"| node_local_cli
node_local_cli -->|"uses visible terminal"| node_companion
node_companion -->|"publishes endpoint"| node_endpoint
node_config -->|"locates endpoint"| node_endpoint
node_wechat_setup -->|"configures channel"| node_config
node_wecom_setup -->|"configures channel"| node_wecom
node_doctor -->|"checks state"| node_state
node_daemon -->|"reads bridge state"| node_state
node_wechat -->|"relays output"| node_local_cli
node_wecom -->|"relays output"| node_local_cli

click node_wechat "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/wechat/wechat-transport.ts"
click node_wecom "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/channels/wecom/wecom-transport.ts"
click node_channel_factory "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/channels/channel-driver-factory.ts"
click node_channel_types "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/core/channel-types.ts"
click node_wechat_forward "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/channels/wechat/wechat-forwarding.ts"
click node_daemon "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/daemon/wechat-daemon.ts"
click node_router "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/core/bridge-message-router.ts"
click node_turns "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/core/turn-coordinator.ts"
click node_bridge "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/bridge/wechat-bridge.ts"
click node_adapter_factory "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/bridge/bridge-adapters.ts"
click node_codex "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/bridge/bridge-adapters.codex.ts"
click node_claude "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/bridge/bridge-adapters.claude.ts"
click node_opencode "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/bridge/bridge-adapters.opencode.ts"
click node_pi "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/bridge/bridge-adapters.pi.ts"
click node_shared "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/bridge/bridge-adapters.shared.ts"
click node_companion "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/companion/local-companion.ts"
click node_endpoint "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/companion/local-companion-link.ts"
click node_state "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/bridge/bridge-state.ts"
click node_config "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/wechat/channel-config.ts"
click node_wechat_setup "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/wechat/setup.ts"
click node_wecom_setup "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/channels/wecom/setup.ts"
click node_doctor "https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/utils/doctor.ts"

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_wechat,node_wecom,node_channel_factory,node_wechat_forward,node_user,node_local_cli toneBlue
class node_channel_types,node_daemon,node_router,node_turns,node_bridge toneAmber
class node_adapter_factory,node_codex,node_claude,node_opencode,node_pi,node_shared,node_companion toneMint
class node_endpoint,node_state,node_config,node_wechat_setup,node_wecom_setup,node_doctor toneRose
```

## Components

### Remote channels

- [WeChat channel](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/wechat/wechat-transport.ts): `src/wechat/wechat-transport.ts`
- [WeCom channel](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/channels/wecom/wecom-transport.ts): `src/channels/wecom/wecom-transport.ts`
- [Channel drivers](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/channels/channel-driver-factory.ts): `src/channels/channel-driver-factory.ts`
- [WeChat forwarding](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/channels/wechat/wechat-forwarding.ts): `src/channels/wechat/wechat-forwarding.ts`

### Bridge runtime

- [Channel contracts](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/core/channel-types.ts): `src/core/channel-types.ts`
- [Multi-CLI daemon](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/daemon/wechat-daemon.ts): `src/daemon/wechat-daemon.ts`
- [Message router](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/core/bridge-message-router.ts): `src/core/bridge-message-router.ts`
- [Turn coordination](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/core/turn-coordinator.ts): `src/core/turn-coordinator.ts`
- [Bridge orchestration](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/bridge/wechat-bridge.ts): `src/bridge/wechat-bridge.ts`

### CLI adapters

- [Adapter selection](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/bridge/bridge-adapters.ts): `src/bridge/bridge-adapters.ts`
- [Codex adapter](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/bridge/bridge-adapters.codex.ts): `src/bridge/bridge-adapters.codex.ts`
- [Claude adapter](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/bridge/bridge-adapters.claude.ts): `src/bridge/bridge-adapters.claude.ts`
- [OpenCode adapter](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/bridge/bridge-adapters.opencode.ts): `src/bridge/bridge-adapters.opencode.ts`
- [Pi adapter](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/bridge/bridge-adapters.pi.ts): `src/bridge/bridge-adapters.pi.ts`
- [Adapter support](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/bridge/bridge-adapters.shared.ts): `src/bridge/bridge-adapters.shared.ts`
- [Visible CLI companion](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/companion/local-companion.ts): `src/companion/local-companion.ts`

### Setup and state

- [Companion endpoints](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/companion/local-companion-link.ts): `src/companion/local-companion-link.ts`
- [Bridge state](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/bridge/bridge-state.ts): `src/bridge/bridge-state.ts`
- [Channel setup and config](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/wechat/channel-config.ts): `src/wechat/channel-config.ts`
- [WeChat setup](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/wechat/setup.ts): `src/wechat/setup.ts`
- [WeCom setup](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/channels/wecom/setup.ts): `src/channels/wecom/setup.ts`
- [Environment doctor](https://github.com/unlinearity/cli-wechat-bridge/blob/main/src/utils/doctor.ts): `src/utils/doctor.ts`

### Other components

- **Remote user**
- **Local CLI user**

## Connections

- Remote user → WeChat channel: sends messages (evidence: `README.md`)
- Remote user → WeCom channel: sends messages (evidence: `README.md`)
- WeChat channel → Channel drivers: provides channel (evidence: `src/channels/channel-driver-factory.ts`)
- WeCom channel → Channel drivers: provides channel (evidence: `src/channels/channel-driver-factory.ts`)
- Channel drivers → Channel contracts: uses contracts (evidence: `src/channels/channel-driver-factory.ts`)
- WeChat forwarding → WeChat channel: sends replies (evidence: `src/channels/wechat/wechat-forwarding.ts`)
- Multi-CLI daemon → Message router: routes messages (evidence: `src/daemon/wechat-daemon.ts`)
- Message router → Channel contracts: uses contracts (evidence: `src/core/bridge-message-router.ts`)
- Turn coordination → Channel contracts: uses contracts (evidence: `src/core/turn-coordinator.ts`)
- Multi-CLI daemon → Adapter selection: selects adapter (evidence: `src/daemon/wechat-daemon.ts`)
- Adapter selection → Codex adapter: dispatches (evidence: `src/bridge/bridge-adapters.ts`)
- Adapter selection → Claude adapter: dispatches (evidence: `src/bridge/bridge-adapters.ts`)
- Adapter selection → OpenCode adapter: dispatches (evidence: `src/bridge/bridge-adapters.ts`)
- Adapter selection → Pi adapter: dispatches (evidence: `src/bridge/bridge-adapters.ts`)
- Codex adapter → Adapter support: uses helpers (evidence: `src/bridge/bridge-adapters.ts`)
- Claude adapter → Local CLI user: runs locally (evidence: `README.md`)
- Codex adapter → Local CLI user: runs locally (evidence: `README.md`)
- OpenCode adapter → Local CLI user: runs locally (evidence: `README.md`)
- Pi adapter → Local CLI user: runs locally (evidence: `README.md`)
- Local CLI user → Visible CLI companion: uses visible terminal (evidence: `README.md`)
- Visible CLI companion → Companion endpoints: publishes endpoint
- Channel setup and config → Companion endpoints: locates endpoint (evidence: `src/companion/local-companion-link.ts`)
- WeChat setup → Channel setup and config: configures channel (evidence: `src/wechat/setup.ts`)
- WeCom setup → WeCom channel: configures channel (evidence: `README.md`)
- Environment doctor → Bridge state: checks state (evidence: `src/utils/doctor.ts`)
- Multi-CLI daemon → Bridge state: reads bridge state (evidence: `src/daemon/wechat-daemon.ts`)
- WeChat channel → Local CLI user: relays output (evidence: `README.md`)
- WeCom channel → Local CLI user: relays output (evidence: `README.md`)
