claude-feishu-channel

Bridge between Claude Code and Feishu / Lark group chat.
Send messages in Feishu → Claude processes with full tool access → results stream back as interactive cards.

node version

Features

Full Claude Code agent — file editing, shell commands, search, planning
Permission brokering — tool calls post interactive approval cards in Feishu
Session persistence — survives process restarts, auto-resumes conversations
Queue & interrupt — messages queue during generation; ! prefix interrupts
Interactive cards — streaming status, tool activity, thinking blocks, permissions
Runtime config — /config set to tune behavior without restart

Quick Start

Install

npm install -g claude-feishu-channel

Initialize config

cfc init
# Creates ~/.claude-feishu-channel/config.toml from template

Edit the config with your Feishu credentials:

vim ~/.claude-feishu-channel/config.toml

Run

cfc

The bot connects to Feishu via WebSocket and starts listening for messages.

CLI Options

cfc [options]            Start the service
cfc init                 Create config template at ~/.claude-feishu-channel/config.toml

Options:
  -c, --config <path>    Path to config.toml (overrides default location)
  -v, --version          Show version number
  -h, --help             Show help

Prerequisites

Node.js >= 20
Claude CLI — claude binary in $PATH (or set claude.cli_path in config)
Feishu bot app — created at open.feishu.cn

Commands

Command	Description
`/new`	Start a new session (clear context)
`/stop`	Interrupt current generation
`/status`	Show session state, model, token usage
`/sessions`	List all known sessions
`/resume <id>`	Resume a previous session
`/cd <path>`	Change working directory (with confirm card)
`/project <alias>`	Switch to a configured project alias
`/mode <mode>`	Set permission mode: `default`, `acceptEdits`, `plan`, `bypassPermissions`
`/model <name>`	Switch Claude model
`/config show`	Display current configuration
`/config set <key> <value>`	Change a config value at runtime
`/config set <key> <value> --persist`	Change and write back to config.toml
`/help`	Show available commands

Special inputs:

Input	Effect
`!<text>`	Interrupt current turn + run `<text>` as new turn
Plain text	Queue as next turn (or start immediately if idle)

Configuration

See config.example.toml for all options with comments.

Sections

Section	Keys	Description
`[feishu]`	`app_id`, `app_secret`, `encrypt_key`, `verification_token`	Feishu bot credentials
`[access]`	`allowed_open_ids`, `unauthorized_behavior`	Who can talk to the bot
`[claude]`	`default_cwd`, `default_permission_mode`, `default_model`, `cli_path`, `permission_timeout_seconds`, `permission_warn_before_seconds`	Claude agent defaults
`[render]`	`inline_max_bytes`, `hide_thinking`, `show_turn_stats`	Card rendering options
`[persistence]`	`state_file`, `log_dir`, `session_ttl_days`	State and log paths
`[logging]`	`level`	Log level: `trace`, `debug`, `info`, `warn`, `error`
`[projects]`	`<alias> = "<path>"`	Project aliases for `/project` command

Runtime-settable keys

These keys can be changed via /config set without restart:

render.hide_thinking, render.show_turn_stats, render.inline_max_bytes,
logging.level, claude.default_model, claude.default_cwd,
claude.default_permission_mode, claude.permission_timeout_seconds,
claude.permission_warn_before_seconds

Architecture

Feishu WebSocket
      │
      ▼
FeishuGateway (event decryption, dedup, access control)
      │
      ├─ onMessage ──▶ parseInput (router)
      │                    │
      │                    ├─ /command ──▶ CommandDispatcher
      │                    │
      │                    └─ plain text ──▶ ClaudeSession.submit
      │                                        │
      │                                        ▼
      │                                  SDK query (claude-agent-sdk)
      │                                        │
      │                                        ├─ tool_use ──▶ PermissionBroker ──▶ Feishu card
      │                                        ├─ thinking ──▶ Feishu card (streaming)
      │                                        └─ text ──▶ Feishu answer card
      │
      └─ onCardAction ──▶ PermissionBroker.resolveByCard
                          QuestionBroker.resolveByCard
                          CommandDispatcher.resolveCdConfirm

Key components:

FeishuGateway — receives WebSocket events, verifies signatures, deduplicates, enforces access control
ClaudeSession — state machine (idle → generating → idle) with message queue, drives the SDK query loop
ClaudeSessionManager — chat_id → ClaudeSession map with persistence and crash recovery
FeishuPermissionBroker — posts permission cards, tracks pending approvals, handles timeouts
CommandDispatcher — handles slash commands (/new, /cd, /config set, etc.)

Development

# Clone and install
git clone https://github.com/Blackman99/claude-feishu-channel.git
cd claude-feishu-channel
pnpm install

# Run in dev mode
pnpm dev

# Run tests
pnpm test

# Type check
pnpm typecheck

# Build
pnpm build

Environment Variables

Variable	Description
`CLAUDE_FEISHU_CONFIG`	Override config file path (default: `~/.claude-feishu-channel/config.toml`)
`ANTHROPIC_BASE_URL`	Custom API endpoint for Claude SDK
`ANTHROPIC_AUTH_TOKEN`	Auth token for custom endpoint

License

MIT