feishu

Feishu Channel for Claude Code

A Feishu (Lark) channel plugin for Claude Code, built on Claude Code's native Channel interface. Send messages to a Feishu bot and interact with Claude — right in your chat.

Uses the MCP Channel protocol to integrate Feishu as a first-class messaging channel for Claude Code, with WebSocket persistent connection mode requiring no public HTTPS endpoint.

npx feishuchannel-for-claudecode   # one-command install

Multi-Group Router — One Bot, Many Projects

The killer feature: route different Feishu groups to different Claude Code instances, each working in its own project directory. A single Feishu bot serves your entire team — each group gets its own isolated Claude with full project context.

                             ┌─ Claude Code (project-a)
Feishu Bot ──→ Router ───────┤─ Claude Code (project-b)
           (single WebSocket)└─ Claude Code (project-c)
                                  ▲ auto-connect via Unix socket

How it works:

• The router holds the single Feishu WebSocket connection and routes messages by chat_id → workdir → worker
• Each worker (server.ts) runs inside a Claude Code instance, registered by its working directory
• The first claude-feishu launch auto-spawns the router — no manual setup needed
• When all workers disconnect, the router auto-shuts down after a grace period

Zero-config startup — just run claude-feishu in each project directory:

cd /path/to/project-a && claude-feishu   # spawns router + connects as worker
cd /path/to/project-b && claude-feishu   # connects to existing router
cd /path/to/project-c && claude-feishu   # connects to existing router

Map Feishu groups to project directories in ~/.claude/channels/feishu/access.json:

{
  "groups": {
    "oc_groupA": { "workdir": "/path/to/project-a", ... },
    "oc_groupB": { "workdir": "/path/to/project-b", ... }
  },
  "defaultWorkdir": "/path/to/default-project"  // DMs route here
}

See Multi-Group Router Setup for full configuration details.

Features

• Multi-group routing — One Feishu bot serves multiple Claude Code instances, each in its own project
• Auto-managed router — Router spawns on first launch, shuts down when all workers disconnect
• Direct messages — Chat with Claude through Feishu DMs
• Group chats — Add the bot to group chats with @mention support
• Access control — Pairing-based onboarding, allowlists, and per-group policies
• Confirm cards — Interactive confirmation cards for risky actions
• Permission cards — Interactive approve/deny cards for tool permission requests
• Unanswered reminders — Auto-nudges Claude if a message goes unanswered for 30+ minutes (up to 3 times, escalating intervals)
• Attachments — Send and receive files and images
• Reactions — Configurable emoji reactions on message receipt
• Smart connection — Only connects when launched as a channel, skipping unnecessary connections
• Graceful shutdown — Detects parent process exit via ppid polling, preventing orphaned processes

Prerequisites

• Bun runtime
• Claude Code CLI installed
• A Feishu (or Lark) workspace with admin access to create apps

Quick Start

1. Create a Feishu App

1. Go to Feishu Open Platform (or Lark Open Platform for international)

2. Create a Custom App (enterprise internal app)

3. Note the App ID (cli_...) and App Secret

4. Under Events & Callbacks, configure two separate tabs:

   Event Configuration tab:

   • Switch connection method to Using persistent connection (WebSocket mode) at the top of the page
   • Add event: im.message.receive_v1

   Callback Configuration tab:

   • Also switch to Using persistent connection (WebSocket mode)
   • Add callback: card.action.trigger (Card interaction callback) — required for confirm card buttons to work

5. Under Permissions & Scopes, add:

   Permission	Purpose
   im:message	Send messages
   im:message.receive_v1	Receive messages
   im:message.p2p_msg:readonly	Read DM messages
   im:message.group_at_msg:readonly	Read group @mentions
   im:chat:readonly	Read chat metadata
   im:resource	Download attachments

6. Publish the app version so permissions take effect

2. Install the Plugin

One command:

npx feishuchannel-for-claudecode