lark-channel-bridge

A lightweight bot that bridges Feishu / Lark messenger with your local Claude Code or Codex CLI. Run one command, scan a QR code to bind a PersonalAgent app, and talk to your local coding agent from chat.

中文 README

For a product walkthrough, see the Feishu document.

What it does

• Forwards Feishu / Lark messages to local Claude Code or Codex CLI. Send a DM directly, or @bot in a group.
• Streaming card: text replies and tool calls update on one Lark card in real time.
• COT process messages: optionally send a process message with agent progress text and tool calls, then send the final answer separately.
• Session continuity: each chat, topic, or document comment thread keeps its own session.
• Queueing and batching: messages sent in quick succession are handled together; messages sent during a run are queued for the next turn, while commands like /new, /cd, /ws use, and /stop can interrupt the current task.
• Multiple workspaces: use /cd to switch the current project, and /ws to save and reuse common project directories.
• Images and files: send them to the bot directly, and the bridge downloads them locally for the agent.
• Interactive cards: /help, /ws list, and /status return cards with clickable buttons.

Prerequisites

• Node.js >= 20.12.0
• At least one local agent installed and logged in:
  • Claude Code: claude, see https://docs.anthropic.com/en/docs/claude-code/quickstart
  • Codex CLI: codex, see https://developers.openai.com/codex/cli
• A Feishu / Lark PersonalAgent app. The first-run QR wizard can create and bind one for you.

Install

npm i -g lark-channel-bridge
# or
pnpm add -g lark-channel-bridge

First run

lark-channel-bridge run

The first run opens a QR-code wizard:

1. A QR code renders in your terminal.
2. Scan it with the Feishu / Lark app.
3. Pick or create a PersonalAgent app.
4. If prompted, choose which agent to initialize.
5. Config is written to ~/.lark-channel/config.json.

You do not need to choose a project directory up front. The bridge creates a profile-managed default working directory; after startup, send /cd <path> in Feishu / Lark to switch to a real project.

If you already have a PersonalAgent app, pass --app-id during initialization to skip app creation. The command prompts for the App Secret.

lark-channel-bridge run --app-id cli_xxx
# or initialize and start the background service directly
lark-channel-bridge start --app-id cli_xxx

For Lark global apps, add --tenant lark.

Background service

Use run for first-run setup and foreground debugging. After the bot can send and receive messages, stop the foreground process with Ctrl-C, then use an OS-managed service for background operation:

lark-channel-bridge start
lark-channel-bridge status
lark-channel-bridge stop

Install globally before using service commands. The daemon's launchd plist / systemd unit / Windows task records the bridge CLI path; if that path comes from an npm temp cache through npx, the daemon can break when the cache is cleaned. run is fine through npx as a one-shot foreground process.

Service commands install a per-profile service:

lark-channel-bridge start [--profile <name>]
lark-channel-bridge stop [--profile <name>]
lark-channel-bridge restart [--profile <name>]
lark-channel-bridge status [--profile <name>]
lark-channel-bridge unregister [--profile <name>]

Platform mapping:

• macOS: launchd user agent ai.lark-channel-bridge.bot.<profile>
• Linux: systemd user unit lark-channel-bridge.bot.<profile>.service
• Windows: Task Scheduler task LarkChannelBridge.Bot.<profile>, launched through a .cmd wrapper

Daemon logs are under ~/.lark-channel/profiles/<profile>/logs/daemon/.

Multiple profiles: Claude and Codex

By default, the bridge starts with the currently selected profile. Use profile use <name> to change it. Each profile keeps its own app credentials, sessions, working directories, and logs. Create multiple profiles only when you need to connect multiple PersonalAgent apps, or run Claude and Codex as separate bots:

lark-channel-bridge start --profile claude --agent claude
lark-channel-bridge start --profile codex --agent codex

For example, to restart only the Codex bot:

lark-channel-bridge restart --profile codex
lark-channel-bridge status --profile codex

Commands

Host CLI

lark-channel-bridge run [--profile <name>] [--agent claude|codex] [--workspace <path>] [-c <config>]
lark-channel-bridge migrate [--profile <name>] [--agent claude|codex]
lark-channel-bridge ps
lark-channel-bridge kill <id|#>
lark-channel-bridge --help

profile use <name> changes the profile used by later default starts. Use these profile management commands when running separate Claude / Codex bots, connecting multiple PersonalAgent apps, or doing scripted deployment:

lark-channel-bridge profile create claude --agent claude
lark-channel-bridge profile create codex --agent codex
lark-channel-bridge profile list
lark-channel-bridge profile use <name>
lark-channel-bridge profile remove <name>
lark-channel-bridge profile remove <name> --purge --yes
lark-channel-bridge profile export <name> [--output ./profile.json] [--force]
lark-channel-bridge profile export <name> --include-secrets --yes

profile remove archives local state by default, including the active profile. If other profiles remain, the bridge switches to the next one; if it was the last profile, the root config is cleared so the same name can be created again. --purge --yes permanently deletes local state. profile export redacts app secrets by default; --include-secrets --yes includes sensitive config.

If a profile was created with the wrong agent kind, stop or unregister any matching background service first, then run profile remove <name> and recreate it with the intended --agent.

Slash commands inside Feishu / Lark

DMs do not require an @ mention. Groups and topic groups require @bot by default; @all is ignored. Cloud-doc comments in supported document types run when the bot is mentioned.

Reply Display and COT

/config controls three presentation settings:

• Message reply mode: message card streams the final reply; plain text sends once after the run finishes.
• Tool-call display: controls whether tool blocks appear in the final card / markdown reply.
• COT process message: off sends only the final reply; brief first sends a COT message with agent progress text and tool summaries; detailed also includes tool args and truncated output.

When COT is enabled, the bridge splits the process view and final answer into two messages. The COT message is for tracing what the agent did; the final answer is still generated from the agent's raw text, without heuristic bridge-side filtering. If an agent emits final-answer text as ordinary stream text, that text can also appear in the COT process message.

lark-cli identity policy

Each profile uses a profile-local lark-cli directory at ~/.lark-channel/profiles/<profile>/lark-cli. The agent process receives LARKSUITE_CLI_CONFIG_DIR for that directory, so personal authorization in one profile is not shared with another profile.

The default policy is bot-only: lark-cli uses the app/bot identity and does not access personal resources. When a user authorizes personal resources such as calendar, mail, or drive, the current profile can switch to user-default, which keeps app identity available and also allows the authorized user identity. Owner/admin users can inspect or change this policy in /config; /status shows the current summary as lark-cli: app or lark-cli: user-ready.

Working directories

Each profile may define a default working directory through workspaces.default. New profiles may be created with --workspace <path>; if omitted, the bridge creates a profile-managed default working directory.

This is a profile-field snippet. Do not replace the whole config.json with it; edit the matching profile's workspaces field.

{
  "workspaces": {
    "default": "/Users/me/.lark-channel-workspaces/claude/default"
  }
}

The bridge checks that a selected directory exists, is a directory, and is not an overly broad location such as /, the home root, a system directory, or a temp root. The working directory is only the current directory for an agent run. It is not a filesystem sandbox; actual file access still depends on the local agent process and its permission mode.

Permission modes

The recommended user-facing profile config is permissions.defaultAccess and permissions.maxAccess. New profiles default to full for both values so the bridge can keep local tools, authorization flows, file writes, and other agent features fully usable. To tighten a profile, set one or both values to workspace or read-only; stricter modes can limit local tool execution, login/authorization flows, file writes, and similar capabilities.

This is a profile-field snippet. Do not replace the whole config.json with it; edit the matching profile's permissions field.

{
  "permissions": {
    "defaultAccess": "full",
    "maxAccess": "full"
  }
}

Mode mapping:

The legacy sandbox field is still readable for old configs. After the bridge saves the profile, it migrates that setting to canonical permissions.

Data directories

Set LARK_CHANNEL_HOME=/path/to/state to move all local bridge state. LARK_CHANNEL_LOG_DAYS overrides log retention.

Access control

Chat access is private by default: out of the box, only you can use the bot in DMs and groups. "You" = whoever created / owns the Feishu app (the person who scanned the QR to set it up). The bot figures out who the app owner is automatically from Feishu, so solo chat use needs zero configuration — you can DM it and @-mention it in any group, and everyone else's chat messages are silently ignored (no "permission denied" reply, which would only confirm the bot exists). Cloud-doc comments are document-scoped; see below.

To let other people or groups in, add them to one of three lists:

/invite and /remove can only be run by you (the creator) and admins. The @ in the command points at the target person (not the bot) — the bot resolves the mention to their identity, so you never deal with raw IDs.

Two identities that bypass everything

• You (the creator): subject to no list at all — DMs, any group, every command. You can never lock yourself out: even if the lists get messed up, DM the bot and send /config to get back in. Transfer the app's ownership in the Feishu console and the bot follows the new owner automatically.
• Admins: can DM, run management commands like /config, and bypass the allowed-chats list — the bot answers them in any group, listed or not. Good for teammates who co-maintain the bot.

Common setups

• Just me → nothing to do; this is the default.
• Let a teammate DM the bot → /invite user @them
• Open a work group to everyone in it → send /invite group inside that group
• First-time setup, onboard every group the bot is already in → /invite all group pulls them all into the list at once; trim with /remove group afterwards
• Add a co-admin → /invite admin @them

Worth knowing

• Changes take effect on the next message — no restart needed.
• In groups you must @ the bot first (DMs don't need it). That's a separate toggle (/config → "require @ in groups"), independent of the lists above.
• Strangers get pure silence — no reply at all. The one exception: if someone @-mentions the bot in a group that hasn't been opened up, the bot posts a friendly one-liner telling them an admin can run /invite group to enable it.
• Cloud-doc comments are document-scoped: anyone who can comment in a supported document and mention the bot can trigger a reply.

Advanced: editing the config file directly

If you'd rather not do it inside Feishu, /invite and /config write the matching profile's access field in ~/.lark-channel/config.json. Empty lists mean nobody from that list, not open access. This is a profile-field snippet; do not replace the whole config.json with it:

{
  "schemaVersion": 2,
  "profiles": {
    "claude": {
      "agentKind": "claude",
      "access": {
        "allowedUsers": ["ou_xxxxxxxxxxxxx"],
        "allowedChats": ["oc_xxxxxxxxxxxxx"],
        "admins": ["ou_xxxxxxxxxxxxx"],
        "requireMentionInGroup": true
      }
    }
  }
}

allowedUsers / admins take user open_ids; allowedChats takes group chat_ids. The easiest way to find an ID by hand: have the person message the bot (or @ it in the group), then check the active profile's log:

grep '"event":"enter"' ~/.lark-channel/profiles/<profile>/logs/bridge-$(date +%Y%m%d).jsonl | tail -5

Each line carries chatId (group / DM id) and senderId (user open_id). After a manual edit, restart the bridge or send /reconnect from an allowed admin context to apply it. For day-to-day tweaks /invite / /config are easier; direct edits are mainly for deployment scripts that pre-seed access.

Cloud-doc comments

Cloud-doc comments do not need a separate workspace binding or document allowlist. In supported document comments, mention the bot and the bridge replies in the same thread. Comment runs reuse the document session key and fall back to the user home directory when no document cwd was previously recorded.

FAQ

The bot stays silent or the local CLI never replies. Usually the local claude or codex CLI is not logged in, or the current session points to a working directory that no longer exists. Send /status to inspect; /new often fixes it by starting a fresh session.

The agent subprocess looks frozen (card stuck on the last frame). The bridge supports an idle watchdog: if the agent emits nothing for N minutes, the process is killed and the card is annotated with the auto-termination reason. Disabled by default. Enable with /config globally, or /timeout 10 for the current session; /timeout off disables it for the session; /timeout default clears the session override.

The agent says it cannot see an image I sent. Upgrade to the latest version. Releases before 0.1.0 had a filename-dedup bug.

Testing and CI

Local checks:

pnpm test
pnpm typecheck
pnpm build

pnpm test includes unit, integration, and process-level adapter tests. CI runs on macOS, Ubuntu, and Windows with pnpm install --frozen-lockfile, pnpm test, pnpm typecheck, and pnpm build.

Optional telemetry

By default the bridge reports nothing: no metrics, no logs leave your machine, and it pulls in zero telemetry dependencies. The hook below is inert unless you opt in.

To wire up your own monitoring, point an environment variable at a module that default-exports (or exports createAdapter) an AdapterFactory:

LARK_CHANNEL_TELEMETRY_MODULE=your-telemetry-package lark-channel-bridge start

That module receives every log.* event plus error/metric hooks and forwards them wherever you like. The interface is exported from the package root:

import type { AdapterFactory, TelemetryAdapter, TelemetryEvent } from 'lark-channel-bridge';

const createAdapter: AdapterFactory = (meta) => ({
  emit(event) {/* ship event */},
  recordError(err, ctx) {/* ship exception */},
  recordMetric(name, value, tags) {/* ship metric */},
  flush(timeoutMs) {/* drain buffered events */},
});
export default createAdapter;

A missing module, a bad factory, or a throwing adapter all degrade to noop — telemetry can never stop the bridge from starting or break logging.

License

MIT