lark-coding-agent-bridge: talk to a local Claude Code or Codex CLI from Feishu / Lark

The gap lark-coding-agent-bridge fills

Claude Code and Codex CLI both run on the machine where your code lives. That is also the machine you are least likely to be sitting at. The bridge exists so that a Feishu / Lark message becomes a prompt for that local process, and the agent's output comes back into the same chat as a streaming card. It is for one developer with one workstation, or a small group that already shares a Lark tenant and wants to reach a coding agent from a phone or a browser tab.

The README lists what it does in concrete terms: forward DMs and `@bot` mentions in groups, keep a separate session per chat, topic, or document comment thread, queue messages that arrive mid-run, and let `/new`, `/cd`, `/ws use` and `/stop` interrupt the current task. Images and files sent to the bot are downloaded locally so the agent can read them. None of that is a hosted product feature. It is a wrapper around a process you already own.

How a message becomes an agent turn

The flow is one-directional and local. A Feishu / Lark event arrives at the bridge, which maps the conversation to a session key, then spawns or continues the configured agent CLI in a working directory. Text replies and tool calls are pushed into a single Lark card that updates while the run proceeds. If the COT option is enabled, progress text and tool calls go out as a separate process message and the final answer follows as its own message.

The session model is the part worth understanding before you deploy. Each chat, topic, or comment thread keeps its own session, so two groups do not share context. `/cd <path>` switches the working directory and resets the session. `/resume` resumes compatible history only when the agent, working directory and permission mode all match. That last condition is a real constraint: change the permission mode and the history is no longer considered compatible.

Profiles are the second axis. Each profile keeps its own app credentials, sessions, working directories and logs, which is how the README suggests running Claude and Codex as two separate bots against two separate PersonalAgent apps. The host CLI exposes `ps` and `kill <id|#>` for in-flight runs, so a stuck turn is recoverable without restarting the daemon.

Installing lark-channel-bridge and binding a PersonalAgent app

Node.js 20.12.0 or newer is required, and at least one agent must already be installed and logged in on the same machine. The package installs globally from npm or pnpm:

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

The first run opens a QR-code wizard. A QR code renders in the terminal, you scan it with the Feishu / Lark app, pick or create a PersonalAgent app, and choose which agent to initialize. Config is written to `~/.lark-channel/config.json`.

lark-channel-bridge run

You do not pick a project directory up front. The bridge creates a profile-managed default working directory, and you switch to a real project from inside the chat. If you already have a PersonalAgent app, pass its id to skip app creation; the command then prompts for the App Secret.

lark-channel-bridge run --app-id cli_xxx

After the bot can send and receive messages, stop the foreground process with Ctrl-C and move to the OS-managed service. Install globally first: the daemon's launchd plist, systemd unit or Windows task records the bridge CLI path, and if that path came from an npm temp cache through `npx`, the daemon breaks when the cache is cleaned. `run` through `npx` is fine as a one-shot foreground process.

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

For Lark global apps, add `--tenant lark`. Service commands accept `--profile <name>`, and `restart`, `status` and `unregister` take the same flag. On macOS the unit is a launchd user agent named `ai.lark-channel-bridge.bot.<profile>`; on Linux a systemd user unit `lark-channel-bridge.bot.<profile>.service`; on Windows a Task Scheduler task `LarkChannelBridge.Bot.<profile>` launched through a `.cmd` wrapper. Daemon logs live under `~/.lark-channel/profiles/<profile>/logs/daemon/`.

Running Claude and Codex as separate bots

The profile system is the answer to a specific annoyance: you want one Lark app for Claude work and another for Codex work, with separate credentials and separate session stores. Create each profile with the intended agent kind, then start them independently.

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

`profile use <name>` changes which profile later default starts use. `profile list` shows what exists. Restarting one bot does not touch the other, which is the practical benefit.

The lifecycle rules have sharp edges. `profile remove` archives local state by default, including the active profile; if other profiles remain the bridge switches to the next one, and 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 unless you pass `--include-secrets --yes`. And if a profile was created with the wrong agent kind, the README says to stop or unregister the matching background service first, then remove and recreate it. There is no in-place fix.

Where the bridge is the wrong tool

The README does not document rollback, and it does not describe a central permission model beyond per-user and per-group invites. Access is granted with `/invite user @name`, `/invite admin @name` and `/invite group`, which is workable for a small trusted set and awkward for anything larger. There is no mention of an audit log, a per-user rate limit, or a policy that restricts which directories an invited user can reach with `/cd`. Anyone who can drive the bot can point it at a path on the host.

The daemon's dependency on the recorded CLI path is the second failure mode. Because the launchd plist, systemd unit and Windows task store that path, a bridge started from an npm temp cache can break when the cache is cleaned. The README's own guidance is to install globally before using service commands, which is a deployment constraint rather than a bug.

Session compatibility is the third. `/resume` only works when the agent, working directory and permission mode match, so changing permission mode mid-project silently costs you the resumable history. And the bridge is a single-user convenience layer by design: if your team needs a shared, hosted coding agent with per-seat billing and central logs, this is not that.

How it differs from cc-connect and other bridges

The closest comparison people search for is cc-connect. Both sit between a chat client and a local coding agent, but the split is in what you install and where the state lives. This project is a single npm package, `lark-channel-bridge`, that runs as an OS-managed per-profile service and writes everything under `~/.lark-channel/`. The README describes local state, local agent processes, and local logs, with the Feishu / Lark PersonalAgent app as the only remote piece.

That shape has consequences. It means no server to host and no data leaving the machine beyond the chat messages themselves, which is the reason to choose it. It also means every user needs their own machine running the daemon, and there is no shared workspace between two people driving the same bot. If your requirement is a shared agent that several people address from one Lark tenant, a hosted or self-hosted server-based bridge fits better, at the cost of moving the agent off your laptop.

Licence, maintenance and upgrade cost

The repository is MIT licensed, which permits commercial use and modification, and the package is published to the public npm registry with `publishConfig.access` set to public. The LICENSE file sits at the repository root alongside README.md and README.zh.md. As with any MIT dependency, you keep the copyright notice; nothing here changes your obligations to the upstream Claude Code or Codex CLI terms, which are separate products.

On maintenance: the last push to the default branch was on 2026-08-31. The repository is not archived. No releases were retrieved, so version 0.7.1 in package.json is the only version signal available, and the README documents a `migrate` command with `--profile` and `--agent` flags, which implies config schema changes have happened before and may happen again.

The upgrade path is ordinary npm for the CLI, but the service layer needs attention. After upgrading, re-run `lark-channel-bridge status --profile <name>` for each profile, because the recorded launchd plist, systemd unit or Windows task still points at the old CLI path. If you used `npx` for the daemon rather than a global install, plan on reinstalling globally first. `profile export <name>` gives you a redacted config snapshot for backup; include `--include-secrets --yes` only if you intend to store the secrets.

Editorial conclusion

Adopt it if you already run Claude Code or Codex locally and want to reach that same machine from Feishu / Lark without opening a terminal. Do not adopt it if you need a shared multi-user service or an audited gateway; the README documents per-user invites but no central permission model, and the daemon is tied to a per-profile CLI path. Before rolling it out, verify that Node.js is at least 20.12.0, that `claude` or `codex` is installed and logged in on the host, and that `lark-channel-bridge status` reports the profile you expect after a restart.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. zarazhangrui/lark-coding-agent-bridge on GitHub