Copilot CLI IM Bridge

Connect GitHub Copilot CLI to mobile messaging platforms for remote interaction from phone.

Architecture

Phone IM App → IM Platform API → Bridge Tool → Copilot CLI (ACP protocol) → Response → IM App

Two bridge tools:

• cc-connect — Feishu/Lark, Slack, DingTalk, Telegram (recommended)
• wechat-acp — WeChat only (community, hook-based)

Platform Comparison

Setup: Feishu (cc-connect)

Prerequisites

• Node.js 20+ (Copilot CLI requires it)
• GitHub Copilot CLI installed globally (brew install copilot-cli or npm i -g @github/copilot)
• Copilot CLI authenticated (copilot login, or COPILOT_GITHUB_TOKEN env var)
• A Feishu/Lark tenant with admin access
• cc-connect binary (brew install cc-connect or download from GitHub releases)

Step 1: Install cc-connect

# macOS (Homebrew)
brew install cc-connect

# Linux / Windows: download from https://github.com/nicepkg/cc-connect/releases

Step 2: Create Feishu Bot App

See references/feishu-setup.md for detailed step-by-step with screenshots guidance.

Quick summary:

1. Visit 飞书开放平台 → 创建企业自建应用
2. 添加应用能力: 机器人
3. 权限管理 → 开通以下权限:
• im:message 系列 (接收/发送消息, 约 20 个子权限全选即可)
• im:resource (可选, 仅文件/图片发送需要)
4. 事件与回调 → 选择 使用长连接接收事件 (WebSocket)
5. 添加事件订阅: 接收消息 (im.message.receive_v1) + 用户进入与机器人的会话
6. 凭证与基础信息 → 复制 App ID 和 App Secret
7. 版本管理与发布 → 创建版本 → 确认发布 (小团队免审核)

Step 3: Authenticate Copilot CLI

Copilot CLI requires a valid GitHub authentication. You can choose any of the following public methods:

Option A: Interactive login (recommended for first setup)

copilot login
# Opens browser for OAuth device flow. Token stored in system keychain.

Option B: Environment variable (recommended for headless/service use)

# Checked in order: COPILOT_GITHUB_TOKEN > GH_TOKEN > GITHUB_TOKEN
# Supported: fine-grained PAT with "Copilot Requests" permission, or OAuth tokens
export COPILOT_GITHUB_TOKEN="<your_github_token>"

Option C: Reuse GitHub CLI token (portable, if token has required permission)

gh auth login
export COPILOT_GITHUB_TOKEN="$(gh auth token)"

Option D: Read token from secret manager/CI env (recommended for teams)

# Example pattern (replace with your secret manager command)
export COPILOT_GITHUB_TOKEN="$(<your_secret_manager_command>)"

Option E: Wrapper script (for services that need dynamic tokens)

#!/bin/bash
# ~/.cc-connect/run-copilot.sh
export COPILOT_GITHUB_TOKEN="<your_github_token_or_command_output>"
exec /opt/homebrew/bin/copilot "$@"

Quick compatibility notes:

• copilot login is simplest for personal machines
• gh auth token is convenient but depends on token permission in your org/account
• COPILOT_GITHUB_TOKEN via secret manager is best for shared servers and CI

> ⚠️ CRITICAL: Do NOT use the VS Code shim at ~/Library/Application Support/Code/User/globalStorage/github.copilot-chat/copilotCli/copilot — it only works within VS Code's terminal context. Always use the real binary (e.g., /opt/homebrew/bin/copilot).

Step 4: Configure

Create ~/.cc-connect/config.toml:

language = "zh"

[log]
level = "info"   # use "debug" for troubleshooting

[[projects]]
name = "copilot-feishu"
filter_external_sessions = true
# admin_from = "<your_open_id>"   # Send /whoami to bot to discover; enables admin commands

[projects.agent]
type = "acp"

[projects.agent.options]
work_dir = "/path/to/ascii-only-workspace"   # CRITICAL: no Chinese characters!
command = "/opt/homebrew/bin/copilot"          # or wrapper script path
args = ["--acp", "--stdio", "--yolo"]
display_name = "GitHub Copilot CLI"

[[projects.platforms]]
type = "feishu"

[projects.platforms.options]
app_id = "<feishu_app_id>"
app_secret = "<feishu_app_secret>"
enable_feishu_card = false       # plain text mode is more stable
progress_style = "compact"
allow_from = "*"                 # or "<your_open_id>" for whitelist

macOS with wrapper script example:

[projects.agent.options]
work_dir = "$HOME/.cc-connect/feishu-workspace"
command = "$HOME/.cc-connect/run-copilot.sh"
args = ["--acp", "--stdio", "--yolo"]

Step 5: First Run & Test

cc-connect --config ~/.cc-connect/config.toml

Expected startup logs:

INFO config loaded
INFO feishu: bot identified open_id=ou_xxxxx
INFO platform ready
INFO engine started
INFO cc-connect is running
[Info] [connected to wss://msg-frontier.feishu.cn/ws/v2?...]

Send a message to the bot in Feishu. Look for:

INFO message received
INFO processing message
INFO session spawned        ← Authentication OK!
INFO turn complete          ← Response sent

Step 6: Persist as Service

See references/persistence.md for:

• macOS: LaunchAgent (recommended)
• Windows: Scheduled Task
• Linux: systemd

Setup: WeChat (wechat-acp)

See references/wechat-setup.md for the complete WeChat bridge guide.

Continuous Context Mode (Feishu + Copilot)

When Copilot runs in ACP mode behind cc-connect, each incoming IM message may start an isolated Copilot session. To preserve continuity, use a history-sync pattern:

1. Persist chat history in cc-connect session JSON
2. On each message.sent event, run a hook script to rebuild .github/copilot-instructions.md
3. Let the next Copilot session load the rebuilt instructions as context seed

This gives practical, near-continuous memory in Feishu chat without modifying cc-connect or Copilot source code.

See references/context-persistence.md for:

• End-to-end architecture
• Hook + script implementation template
• Recommended config (hooks, auto_compress, dedicated work_dir)
• Pros/cons and known limitations (including one-turn delay)
• Verification checklist

Enabling File Sending

cc-connect supports sending files/images to chat via its CLI send subcommand. To make Copilot auto-send files, add to .github/copilot-instructions.md in your work_dir:

## File Sending Rules
When you create files for the user or when asked to send files:
- Send files: `cc-connect send --file "<absolute_path>" -p <project_name>`
- Send images: `cc-connect send --image "<absolute_path>" -p <project_name>`
- Always use absolute paths

Key Limitations

1. No shared session — VS Code Copilot and IM Copilot have independent conversation memory
2. File system IS shared — Both can read/write the same project files
3. --yolo recommended — Prevents Copilot from blocking on confirmations when you're away
4. Isolate work_dir — Use different work_dir for IM bridge vs local CLI to avoid session conflicts; or set filter_external_sessions = true

Troubleshooting

See references/troubleshooting.md for:

• Authentication required error — VS Code shim vs real binary
• Chinese path encoding (乱码) — use subst drive mapping
• Bot not responding — permission / TOML hierarchy issues
• Session context loss — work_dir conflict resolution
• Process dies when terminal closes — service persistence