chord-gateway

README

chord-gateway

chord-gateway connects IM platforms such as WeChat and Feishu to local chord headless processes. It lets you control Chord from chat while keeping the agent process, workspace access, credentials, and state on your own machine or server.

• Chinese version: README_CN.md
• Documentation site: https://keakon.github.io/chord-gateway/
• Full documentation: docs/index.md
• Requires: Go 1.27.0+ and a chord build supporting the current headless contract

Features

• WeChat iLink support with QR-code login and token persistence (<state_dir>/wechat/token.json by default)
• Feishu bot support with long-lived connection mode, owner allowlist, and event deduplication
• Multiple IM adapters can run together
• Per-chat and per-workspace session isolation
• Session pinning and resume commands (/new, /resume, /sessions)
• Cross-IM login notification (for example, when one channel expires, use another channel to prompt re-login)
• Local chord headless subprocess lifecycle management and cleanup
• Configurable visibility for optional control-plane events
• Generated images are forwarded to the originating chat; images at or above Feishu's upload limit are sent as a reduced preview while Chord keeps the original

Install

Install from source with Go:

go install github.com/keakon/chord-gateway@latest

Or build from a local checkout:

go build -o chord-gateway .

Install Chord separately and make sure chord is available in PATH, or set chord_path in the gateway config. Shell aliases are not supported for chord_path because the gateway executes the binary directly.

Verify the installation:

chord-gateway --version
chord --version

Quickstart

Create a minimal config and point workspaces.default.path at the project you want Chord to operate on. Workspace paths must start with /, ~, a Windows drive prefix, or a UNC prefix. Here is a WeChat example:

ims:
  wechat:
    base_url: https://ilinkai.weixin.qq.com
workspaces:
  default:
    path: /path/to/project
chord_path: chord
idle_timeout: 30m

Run the gateway:

chord-gateway -f config.yaml

Only YAML config files are supported (.yaml or .yml).

After the gateway is running, send /status from the connected IM chat to verify the route, then send a normal text message to talk to Chord.

Notes: WeChat routes to a single workspace; Feishu inbound handling currently accepts text messages only. See “Support scope / known limitations” for details.

For Feishu setup and multi-workspace routing, see QUICKSTART.md.

Support scope / known limitations

• Source builds require Go 1.27.0+ and a separate chord binary. chord-gateway does not bundle Chord itself.
• CI currently builds these targets: darwin/amd64, darwin/arm64, linux/amd64, linux/arm64, and windows/amd64.
• WeChat always routes to one workspace. When multiple workspaces exist, set ims.wechat.workspace_id to choose the workspace used by WeChat.
• Feishu multi-workspace routing uses ims.feishu.chat_bindings to map chat IDs to workspace IDs. Inbound Feishu handling currently accepts text messages only; non-text messages are ignored.
• /login [platform] is only useful for adapters that support interactive login renewal. Today that flow is available for WeChat, not Feishu.

Common IM commands

Command	Description
/status	Show current Chord state
/cancel	Cancel the current turn
/allow / /deny [reason]	Approve or deny a pending confirmation
/answer @<id> <text>	Answer or revise a question by ID; numeric shortcuts are supported
/role [number|name]	Show the current main-agent role and the switchable roles, or switch to a target role by list number or name
/todos	Show the current todo list
/new	Start a fresh session for the current binding
/resume <id>	Resume and pin a session
/sessions	List recent sessions
/login [platform]	Show supported login-renewal platforms, or start one when a platform is provided (for example /login wechat)

See docs/usage.md for full command behavior and session semantics.

Documentation

• Quickstart
• Cookbook
• IM integration overview
• Usage
• Configuration reference
• Operations
• Event visibility
• Permissions & safety
• Troubleshooting
• Changelog
• Chinese docs: docs/index_CN.md

Security notes

chord-gateway routes IM messages to a local chord headless process that can interact with the configured workspace. Treat IM access as control-plane access to that workspace.

Except during brief testing in a controlled chat, configure a Feishu allowlist (owner_open_id and/or allowed_open_ids). Running the gateway locally does not restrict who can message the bot through Feishu. Keep Feishu secrets, WeChat token files (<state_dir>/wechat/token.json unless ims.wechat.token_path is set), and the gateway state directory out of version control. See docs/permissions-and-safety.md and SECURITY.md.

License

MIT License. See LICENSE.

Documentation

Overview

Package main defines the IM adapter interface.

Package main is the chord gateway — a lightweight control plane that connects IM platforms (WeChat, Feishu, etc.) to chord headless processes via stdio JSON protocol.

Package main implements a lightweight deduplication store for Feishu messages. It uses an in-memory hot cache with file-backed persistence for TTL survival across restarts.

Package main implements the Feishu IM adapter for chord-gateway.

Package main: Feishu wire-format helpers shared between handlers.

Package main is the chord gateway — a lightweight control plane that connects IM platforms (WeChat, Feishu, etc.) to chord headless processes via stdio JSON protocol.

Package main defines the gateway ControlState and event types.

Package main implements the WeChat iLink Bot IM adapter for chord-gateway.