# sgaofen/cli-in-wechat architecture

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

- Interactive diagram: https://gitdiagram.com/sgaofen/cli-in-wechat
- Repository: https://github.com/sgaofen/cli-in-wechat

## Overview

1. This repository is a TypeScript/Node.js bridge service, not a standalone AI app. It runs on the user’s computer and connects WeChat ClawBot messages to locally installed AI coding CLIs. The computer is the execution boundary; WeChat is only the remote control surface.

2. The system has two major external dependencies: the official WeChat iLink Bot API and a set of locally spawned command-line tools (Claude Code, Codex CLI, Gemini CLI, Kimi Code, OpenCode). The bridge translates between WeChat message events and each tool’s own CLI invocation style.

3. The entrypoint is `src/index.ts`, which wires together configuration, the iLink client, the message router, and the adapter registry. This is the orchestration layer that starts the long-polling loop and dispatches incoming messages into the bridge pipeline.

4. `src/ilink/` is the WeChat-facing transport layer. `auth.ts` handles QR-code login and token acquisition, `client.ts` handles long polling, sending messages, typing indicators, and token renewal, and `types.ts` defines the API contract. This layer isolates all network interaction with `ilinkai.weixin.qq.com`.

5. `src/bridge/router.ts` is the central message dispatcher. It interprets `@tool` prefixes, `/` commands, `>>` result-chaining, chained tool syntax like `@claude>codex`, session-resume flows, and the Claude-specific AskUserQuestion round-trip back to WeChat. This is where message intent is converted into executable actions.

6. `src/adapters/` is the tool abstraction boundary. `base.ts` defines shared adapter behavior and spawn helpers, while `claude.ts`, `codex.ts`, `gemini.ts`, `kimi.ts`, and `opencode.ts` each encode one CLI’s invocation model, permissions flags, stdin/stdout handling, and output parsing. `registry.ts` detects which tools are installed and available for routing.

7. The adapter layer is intentionally heterogeneous because each CLI behaves differently. Some tools are driven through stdin, some through flags like `--print` or `-p`, and Claude can also use an Agent SDK-style interaction for richer turns. The bridge hides these differences so the router can treat them as interchangeable tool backends.

8. `src/bridge/session.ts` provides conversation persistence and continuity. It stores session metadata locally with atomic writes, enabling `/resume`, `/session set <id>`, `/fork`, `/new`, and continuity across WeChat and terminal-originated sessions. This is the state boundary that preserves context between messages.

9. `src/bridge/formatter.ts` is the output-shaping layer. It converts adapter responses into WeChat-friendly message content, including formatting for summaries, streamed or multi-part outputs, and command feedback. This prevents raw CLI output from leaking directly into the chat experience.

10. `src/utils/` contains cross-cutting infrastructure. `http.ts` wraps fetch with timeout, retries, jitter, and optional proxy support; `media.ts` handles attachment download, AES decryption, and safe filenames; `crypto.ts` provides signing/encryption helpers; `logger.ts` standardizes diagnostics. These utilities support robustness but are not business logic themselves.

11. `src/config.ts` centralizes local configuration such as default tool, working directory, CLI timeout, allowed users, and per-tool arguments. The README makes clear that `allowedUsers` is a key security boundary: if left empty, any private-chat user can trigger fully privileged local CLI execution.

12. The main data flow is: WeChat message arrives via iLink long polling → router classifies it → session/context is loaded or updated → matching adapter spawns or drives the chosen CLI → output is formatted → response is sent back through iLink. For AskUserQuestion, the flow temporarily reverses: Claude asks a question, the bridge relays it to WeChat, then the reply is fed back into the same session.

13. Reliability is a visible architectural concern. The bridge tolerates transient network failures with retries, handles token expiry by forcing re-login, and avoids shell-injection risks in tool adapters by preferring stdin or structured arguments where possible. That makes the service resilient because both the chat transport and the local CLI processes can fail independently.

14. The repository also includes tests under `test/` that cover routing, session behavior, media handling, HTTP resilience, and adapter-specific behavior. `.github/workflows/ci.yml` suggests automated validation in CI, which is important because the architecture depends on several external tools and network-bound integrations that can regress independently.

Main entry points: [`src/bridge/router.ts`](https://github.com/sgaofen/cli-in-wechat/blob/main/src/bridge/router.ts) (Router), [`src/index.ts`](https://github.com/sgaofen/cli-in-wechat/blob/main/src/index.ts) (Main), [`src/adapters/base.ts`](https://github.com/sgaofen/cli-in-wechat/blob/main/src/adapters/base.ts) (Base Adapter), [`src/ilink/client.ts`](https://github.com/sgaofen/cli-in-wechat/blob/main/src/ilink/client.ts) (Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_entry["Entry & CLI"]
  node_node_index["Main<br/>bootstrap<br/>[index.ts]"]
  node_node_send_cli["Send CLI<br/>local command<br/>[send.ts]"]
  node_node_config["Config<br/>[config.ts]"]
end

subgraph group_group_ilink["WeChat Transport"]
  node_node_auth["Auth<br/>iLink login<br/>[auth.ts]"]
  node_node_client["Client<br/>iLink transport<br/>[client.ts]"]
  node_node_ilink_types["API Types<br/>contracts<br/>[types.ts]"]
end

subgraph group_group_bridge["Bridge Core"]
  node_node_router{{"Router<br/>message dispatch<br/>[router.ts]"}}
  node_node_session[("Session Store<br/>conversation state<br/>[session.ts]")]
  node_node_formatter["Formatter<br/>response shaping<br/>[formatter.ts]"]
end

subgraph group_group_adapters["Tool Adapters"]
  node_node_registry["Registry<br/>tool detection<br/>[registry.ts]"]
  node_node_base["Base Adapter<br/>adapter core<br/>[base.ts]"]
  node_node_claude["Claude<br/>adapter<br/>[claude.ts]"]
  node_node_codex["Codex<br/>adapter<br/>[codex.ts]"]
  node_node_gemini["Gemini<br/>adapter<br/>[gemini.ts]"]
  node_node_kimi["Kimi<br/>adapter<br/>[kimi.ts]"]
  node_node_opencode["OpenCode<br/>adapter<br/>[opencode.ts]"]
end

subgraph group_group_utils["Utilities"]
  node_node_http["HTTP<br/>network helper<br/>[http.ts]"]
  node_node_media["Media<br/>attachment helper<br/>[media.ts]"]
  node_node_crypto["Crypto<br/>security helper<br/>[crypto.ts]"]
  node_node_logger["Logger<br/>diagnostics<br/>[logger.ts]"]
end

node_node_index -->|"loads"| node_node_config
node_node_index -->|"auths"| node_node_auth
node_node_index -->|"starts"| node_node_client
node_node_index -->|"wires"| node_node_router
node_node_index -->|"wires"| node_node_registry
node_node_client -->|"uses"| node_node_http
node_node_client -->|"uses"| node_node_ilink_types
node_node_router -->|"loads/saves"| node_node_session
node_node_router -->|"selects"| node_node_registry
node_node_router -->|"formats"| node_node_formatter
node_node_router -->|"handles"| node_node_media
node_node_router -->|"dispatches"| node_node_claude
node_node_router -->|"dispatches"| node_node_codex
node_node_router -->|"dispatches"| node_node_gemini
node_node_router -->|"dispatches"| node_node_kimi
node_node_router -->|"dispatches"| node_node_opencode
node_node_registry -->|"extends"| node_node_base
node_node_claude -->|"builds on"| node_node_base
node_node_codex -->|"builds on"| node_node_base
node_node_gemini -->|"builds on"| node_node_base
node_node_kimi -->|"builds on"| node_node_base
node_node_opencode -->|"builds on"| node_node_base
node_node_send_cli -->|"uses"| node_node_client
node_node_send_cli -->|"uses"| node_node_router
node_node_client -->|"logs"| node_node_logger
node_node_router -->|"logs"| node_node_logger
node_node_http -->|"supports"| node_node_crypto

click node_node_index "https://github.com/sgaofen/cli-in-wechat/blob/main/src/index.ts"
click node_node_send_cli "https://github.com/sgaofen/cli-in-wechat/blob/main/src/cli/send.ts"
click node_node_auth "https://github.com/sgaofen/cli-in-wechat/blob/main/src/ilink/auth.ts"
click node_node_client "https://github.com/sgaofen/cli-in-wechat/blob/main/src/ilink/client.ts"
click node_node_ilink_types "https://github.com/sgaofen/cli-in-wechat/blob/main/src/ilink/types.ts"
click node_node_router "https://github.com/sgaofen/cli-in-wechat/blob/main/src/bridge/router.ts"
click node_node_session "https://github.com/sgaofen/cli-in-wechat/blob/main/src/bridge/session.ts"
click node_node_formatter "https://github.com/sgaofen/cli-in-wechat/blob/main/src/bridge/formatter.ts"
click node_node_registry "https://github.com/sgaofen/cli-in-wechat/blob/main/src/adapters/registry.ts"
click node_node_base "https://github.com/sgaofen/cli-in-wechat/blob/main/src/adapters/base.ts"
click node_node_claude "https://github.com/sgaofen/cli-in-wechat/blob/main/src/adapters/claude.ts"
click node_node_codex "https://github.com/sgaofen/cli-in-wechat/blob/main/src/adapters/codex.ts"
click node_node_gemini "https://github.com/sgaofen/cli-in-wechat/blob/main/src/adapters/gemini.ts"
click node_node_kimi "https://github.com/sgaofen/cli-in-wechat/blob/main/src/adapters/kimi.ts"
click node_node_opencode "https://github.com/sgaofen/cli-in-wechat/blob/main/src/adapters/opencode.ts"
click node_node_http "https://github.com/sgaofen/cli-in-wechat/blob/main/src/utils/http.ts"
click node_node_media "https://github.com/sgaofen/cli-in-wechat/blob/main/src/utils/media.ts"
click node_node_crypto "https://github.com/sgaofen/cli-in-wechat/blob/main/src/utils/crypto.ts"
click node_node_logger "https://github.com/sgaofen/cli-in-wechat/blob/main/src/utils/logger.ts"
click node_node_config "https://github.com/sgaofen/cli-in-wechat/blob/main/src/config.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_node_index,node_node_send_cli,node_node_config toneBlue
class node_node_auth,node_node_client,node_node_ilink_types toneAmber
class node_node_router,node_node_session,node_node_formatter toneMint
class node_node_registry,node_node_base,node_node_claude,node_node_codex,node_node_gemini,node_node_kimi,node_node_opencode toneRose
class node_node_http,node_node_media,node_node_crypto,node_node_logger toneIndigo
```

## Components

### Entry & CLI

Process startup and local command entrypoints

- [Main](https://github.com/sgaofen/cli-in-wechat/blob/main/src/index.ts): bootstrap · Wires config, transport, router, and adapter registry; starts polling loop · `src/index.ts`
- [Send CLI](https://github.com/sgaofen/cli-in-wechat/blob/main/src/cli/send.ts): local command · Command-line entry for sending or relaying messages · `src/cli/send.ts`
- [Config](https://github.com/sgaofen/cli-in-wechat/blob/main/src/config.ts): runtime config · Local configuration for default tool, working directory, users, timeouts, and tool args · `src/config.ts`

### WeChat Transport

Official iLink API integration

- [Auth](https://github.com/sgaofen/cli-in-wechat/blob/main/src/ilink/auth.ts): iLink login · QR login and token acquisition for WeChat iLink · `src/ilink/auth.ts`
- [Client](https://github.com/sgaofen/cli-in-wechat/blob/main/src/ilink/client.ts): iLink transport · Long polling, message send, typing indicators, and token renewal · `src/ilink/client.ts`
- [API Types](https://github.com/sgaofen/cli-in-wechat/blob/main/src/ilink/types.ts): contracts · WeChat iLink request and response type definitions · `src/ilink/types.ts`

### Bridge Core

Message routing, session state, and response shaping

- [Router](https://github.com/sgaofen/cli-in-wechat/blob/main/src/bridge/router.ts): message dispatch · Classifies commands, tool routing, chained flows, and AskUserQuestion round-trips · `src/bridge/router.ts`
- [Session Store](https://github.com/sgaofen/cli-in-wechat/blob/main/src/bridge/session.ts): conversation state · Persistent session metadata, resume, fork, and continuity handling · `src/bridge/session.ts`
- [Formatter](https://github.com/sgaofen/cli-in-wechat/blob/main/src/bridge/formatter.ts): response shaping · Converts adapter output into WeChat-friendly message content · `src/bridge/formatter.ts`

### Tool Adapters

Per-CLI execution backends and availability detection

- [Registry](https://github.com/sgaofen/cli-in-wechat/blob/main/src/adapters/registry.ts): tool detection · Detects installed adapters and exposes available backends · `src/adapters/registry.ts`
- [Base Adapter](https://github.com/sgaofen/cli-in-wechat/blob/main/src/adapters/base.ts): adapter core · Shared adapter behavior and process spawn helpers · `src/adapters/base.ts`
- [Claude](https://github.com/sgaofen/cli-in-wechat/blob/main/src/adapters/claude.ts): adapter · Claude Code invocation, permissions, and richer turn handling · `src/adapters/claude.ts`
- [Codex](https://github.com/sgaofen/cli-in-wechat/blob/main/src/adapters/codex.ts): adapter · Codex CLI execution model and output parsing · `src/adapters/codex.ts`
- [Gemini](https://github.com/sgaofen/cli-in-wechat/blob/main/src/adapters/gemini.ts): adapter · Gemini CLI invocation and output handling · `src/adapters/gemini.ts`
- [Kimi](https://github.com/sgaofen/cli-in-wechat/blob/main/src/adapters/kimi.ts): adapter · Kimi Code CLI invocation and output handling · `src/adapters/kimi.ts`
- [OpenCode](https://github.com/sgaofen/cli-in-wechat/blob/main/src/adapters/opencode.ts): adapter · OpenCode CLI invocation and model selection · `src/adapters/opencode.ts`

### Utilities

Cross-cutting helpers for networking, media, crypto, and logging

- [HTTP](https://github.com/sgaofen/cli-in-wechat/blob/main/src/utils/http.ts): network helper · Fetch wrapper with timeout, retries, jitter, and proxy support · `src/utils/http.ts`
- [Media](https://github.com/sgaofen/cli-in-wechat/blob/main/src/utils/media.ts): attachment helper · Attachment download, AES decryption, and safe filename handling · `src/utils/media.ts`
- [Crypto](https://github.com/sgaofen/cli-in-wechat/blob/main/src/utils/crypto.ts): security helper · Signing and encryption helpers · `src/utils/crypto.ts`
- [Logger](https://github.com/sgaofen/cli-in-wechat/blob/main/src/utils/logger.ts): diagnostics · Standardized logging and diagnostics · `src/utils/logger.ts`

## Connections

- Main → Config: loads · Reads runtime configuration before startup
- Main → Auth: auths · Initializes iLink login/token acquisition
- Main → Client: starts · Creates the long-polling transport client
- Main → Router: wires · Connects incoming messages to the dispatcher
- Main → Registry: wires · Registers available tool backends
- Client → HTTP: uses · Network requests and retries rely on HTTP helper
- Client → API Types: uses · Implements the iLink API contract
- Router → Session Store: loads/saves · Resumes and persists conversation state
- Router → Registry: selects · Chooses an available tool backend
- Router → Formatter: formats · Shapes replies for WeChat delivery
- Router → Media: handles · Processes attachments and downloaded media
- Router → Claude: dispatches · Routes Claude-specific turns and AskUserQuestion flows
- Router → Codex: dispatches · Routes Codex sessions
- Router → Gemini: dispatches · Routes Gemini sessions
- Router → Kimi: dispatches · Routes Kimi sessions
- Router → OpenCode: dispatches · Routes OpenCode sessions
- Registry → Base Adapter: extends · Adapter implementations share common spawn helpers
- Claude → Base Adapter: builds on · Specialized adapter behavior on top of shared base
- Codex → Base Adapter: builds on · Specialized adapter behavior on top of shared base
- Gemini → Base Adapter: builds on · Specialized adapter behavior on top of shared base
- Kimi → Base Adapter: builds on · Specialized adapter behavior on top of shared base
- OpenCode → Base Adapter: builds on · Specialized adapter behavior on top of shared base
- Send CLI → Client: uses · CLI entry reuses the iLink transport path
- Send CLI → Router: uses · Shares routing and session semantics where applicable
- Client → Logger: logs · Emits operational diagnostics
- Router → Logger: logs · Records command and routing diagnostics
- HTTP → Crypto: supports · Security-sensitive transport and media helpers rely on crypto utilities
