acp-bridge 1.2.0

Bridge Feishu to ACP-compatible agents with automatic session management for non-developers.

ACP Bridge

ACP Bridge is a bridge service that connects Feishu (Lark) group chats to ACP-compatible AI agents (such as Kiro CLI).

Core features:

• Auto session creation — @mention the bot in group chats, or just send a message in DM
• Message threading via reply chains — reply to any message in a thread to continue the conversation
• LRU + TTL session management — automatic eviction of idle sessions to control resource usage
• Message buffering — messages sent while the agent is busy are queued and delivered in order

Installation

Prerequisites

• Python 3.11+
• uv package manager
• Kiro CLI — the default ACP agent

Feishu App Setup

1. Go to the Feishu Open Platform and create a new app.

2. Under Credentials, copy the App ID and App Secret.

3. Under Event Subscriptions, enable WebSocket (long connection) mode, then add the im.message.receive_v1 event.

4. Under Permissions, enable:

   • im:message — send and update messages
   • im:message:send_as_bot — send messages as bot
   • im:message.group_at_msg:readonly — receive group chat messages with @mention
   • im:message.group_msg — receive all group messages (required for reply-chain routing)
   • im:message.p2p_msg:readonly — receive P2P messages
   • im:resource — download file resources from messages
   • im:chat:readonly — read chat info
   • contact:contact.base:readonly — get user name (optional, for identifying sender in prompts)
   • contact:user.email:readonly — get user email (optional, for matching accounts in external systems)

   For contact permissions to work, ensure the Data Permission (数据权限) contact scope includes all bot users.

Steps

1. Install dependencies:

   uv sync
   

2. Generate a config file:

   uv run python -m acp_bridge.main init
   

3. Edit bridge.toml with your Feishu app credentials:

   [feishu]
   app_id = "your_app_id"
   app_secret = "your_app_secret"
   
   [bridge]
   default_workspace = "~"
   attachment_dir = "tmp/attachments"
   auto_approve = false
   max_sessions = 10
   session_ttl_minutes = 60
   show_thinking = false
   show_intermediate = false
   
   [agent]
   name = "kiro"
   description = "Kiro CLI - https://kiro.dev/cli/"
   command = "kiro-cli"
   args = ["acp"]
   auto_approve = false
   

4. Start the service:

   uv run python -m acp_bridge.main run
   

Tip: It's recommended to run in tmux so it persists in the background:

tmux new -s acp-bridge "uv run python -m acp_bridge.main run"

Commands

Command	Description
#mode	Show available modes and current mode
#mode <value>	Switch to a different mode
#model	Show available models and current model
#model <value>	Switch to a different model
#cancel	Cancel ongoing agent operation
#end	End current agent session
#read <file_path>	Read local file content
#diff [args]	Show git diff
#session	Show current agent session info
#sessions	Show all active sessions
#help	Show help message

License

MIT License. See LICENSE for details.

This project is derived from Juan by DiscreteTom.