agent-feishu-channel

Claude and Codex, natively in Feishu / Lark.
A full coding-agent workflow — right inside your Feishu group chat.

English | 中文

Migrating from claude-feishu-channel? The project was renamed to reflect multi-provider support (Claude + Codex). Run pnpm remove claude-feishu-channel && pnpm add agent-feishu-channel (or the npm equivalent). Command is now afc instead of cfc. On first run, the state directory at ~/.claude-feishu-channel/ will be auto-renamed to ~/.agent-feishu-channel/ — session history is preserved. Config keys are unchanged.

Features

• Dual providers — switch between Claude and Codex per config or per session
• Full coding 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
• Staged context mitigation — warn, then hard 50MB fallback
• Runtime config — /config set to tune behavior without restart

Quick Start

Install

npm install -g agent-feishu-channel

Initialize config

afc init
# Creates ~/.agent-feishu-channel/config.toml from template

Edit the config with your Feishu credentials:

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

To discover your Feishu open_id on first run, temporarily set allowed_open_ids = [] and unauthorized_behavior = "reject", then send the bot a message. It will reply with your open_id; add that value to allowed_open_ids and switch back to "ignore" for normal use.

Run

afc

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

CLI Options

afc [options]            Start the service
afc init                 Create config template at ~/.agent-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 when using the Claude provider
• Codex CLI + SDK — codex binary in $PATH plus @openai/codex-sdk when using the Codex provider
• 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, reasoning effort, token usage
/cost	Show token usage totals (input / output / total) for this session
/context	Show context window usage and mitigation status
/compact	Reset the current session to free context (idle-only)
/sessions	List all known sessions
/projects	List all configured project aliases
/resume <id>	Resume a previous session
/cd <path>	Change working directory (with confirm card)
/project <alias>	Switch to a configured project alias
/provider <claude|codex>	Switch the current session provider
/mode <mode>	Set permission mode: default, acceptEdits, plan, bypassPermissions
/model <name>	Switch the current provider model
/effort <level>	Switch the current provider reasoning effort
/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
/memory	Show current provider memory files (CLAUDE.md for Claude, AGENTS.md for Codex)
/memory add <text>	Append <text> as a bullet to the current provider's project memory file
/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
[agent]	default_provider, default_cwd, default_permission_mode, permission_timeout_seconds, permission_warn_before_seconds	Shared defaults and legacy fallbacks
[claude]	default_permission_mode, default_model, default_effort, permission_timeout_seconds, permission_warn_before_seconds, cli_path	Claude provider defaults
[codex]	default_permission_mode, default_model, default_effort, cli_path	Codex provider 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
[[mcp]] (array)	name, type (stdio/sse), command/args/env or url	Custom MCP servers exposed to the active provider

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, agent.default_provider, agent.default_cwd, agent.default_permission_mode, agent.permission_timeout_seconds, agent.permission_warn_before_seconds, claude.default_model, claude.default_effort, claude.default_permission_mode, claude.permission_timeout_seconds, claude.permission_warn_before_seconds, codex.default_model, codex.default_effort, codex.default_permission_mode

Upgrading old configs

Existing Claude-only configs continue to load. Legacy [claude] values are used as shared fallbacks when [agent] is absent or only partially present, and Codex receives safe defaults (gpt-5.5, high effort, shared permission mode). Users can move to the new layout gradually with /config set ... --persist; no one-time manual migration is required.

Architecture

Feishu WebSocket
      │
      ▼
FeishuGateway (event decryption, dedup, access control)
      │
      ├─ onMessage ──▶ parseInput (router)
      │                    │
      │                    ├─ /command ──▶ CommandDispatcher
      │                    │
      │                    └─ plain text ──▶ ClaudeSession.submit
      │                                        │
      │                                        ▼
      │                           provider queryFn (Claude or Codex)
      │                                        │
      │                                        ├─ 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 — shared session state machine (idle → generating → idle) with message queue, drives the selected provider runtime
• ClaudeSessionManager — chat_id → ClaudeSession map with persistence, provider selection, and crash recovery
• FeishuPermissionBroker — posts permission cards, tracks pending approvals, handles timeouts
• CommandDispatcher — handles slash commands (/new, /cd, /config set, etc.)

Context Handling

The bot now applies staged mitigation before it hits Claude's 50MB hard request limit:

1. warn — notify that the session is getting large
2. hard reset fallback — keep the backend-driven Request too large / max 50MB reset-and-retry path as the last fallback

Use /context to inspect current window usage and see the mitigation order reflected in user-facing output.

Development

# Clone and install
git clone https://github.com/Blackman99/agent-feishu-channel.git
cd agent-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
AGENT_FEISHU_CONFIG	Override config file path (default: ~/.agent-feishu-channel/config.toml)
CLAUDE_FEISHU_CONFIG	Legacy alias for AGENT_FEISHU_CONFIG (still honored)
ANTHROPIC_BASE_URL	Custom API endpoint for Claude SDK
ANTHROPIC_AUTH_TOKEN	Auth token for custom endpoint

Current Codex Limits

• Mid-turn acceptEdits escalation is still a provider-specific downgrade on Codex: setPermissionMode() is a safe no-op in the current adapter.

License

MIT