codex-im-bridge

codex-im-bridge is a local Node.js bridge that lets Feishu messages control a local Codex runtime.

中文文档: README.zh-CN.md

Runtime path:

Feishu -> local codex-im-bridge process -> local codex app-server -> Feishu cards

Codex state (threads, approvals, run context) stays on your local machine. Feishu is only the remote control UI.

Features

• Feishu long-connection bot runtime
• Bind one Feishu conversation to one or more local workspaces
• Thread management: continue, create, switch, inspect recent messages
• Approval workflow in Feishu cards (approve, approve session, reject)
• Multi-agent support per workspace:
  • list agents and active agent
  • switch active agent
  • run a prompt on a specific agent
  • run one prompt across multiple agents in parallel and return a summary
• Streaming or final-only reply cards

Requirements

• Node.js 18+
• A Feishu self-built app with event subscriptions enabled
• Local Codex CLI/Desktop runtime available on the machine running codex-im-bridge

Quick Start

Install and run directly from TypeScript (no build step required):

npm install
npm run feishu-bot

Run compiled output:

npm run feishu-bot:dist

Install globally as a CLI:

npm run build
npm install -g .
codex-im-bridge feishu-bot

Configuration

Environment variables:

• FEISHU_APP_ID
• FEISHU_APP_SECRET
• CODEX_IM_BRIDGE_CODEX_COMMAND (default: codex)
• CODEX_IM_BRIDGE_CODEX_ENDPOINT (optional websocket endpoint; if set, no local spawn)
• CODEX_IM_BRIDGE_DEFAULT_WORKSPACE_ID (default: default)
• CODEX_IM_BRIDGE_FEISHU_STREAMING_OUTPUT (default: true)
• CODEX_IM_BRIDGE_WORKSPACE_ALLOWLIST (comma-separated absolute path prefixes)
• CODEX_IM_BRIDGE_SESSIONS_FILE (default: ~/.codex-im-bridge/sessions.json)

If codex is not found in PATH, set CODEX_IM_BRIDGE_CODEX_COMMAND to an absolute executable path. On macOS, codex-im-bridge also attempts /Applications/Codex.app/Contents/Resources/codex.

.env loading order

codex-im-bridge loads env files with Next.js-like priority:

1. ~/.codex-im-bridge/.env
2. ./.env
3. ~/.codex-im-bridge/.env.local
4. ./.env.local

Shell environment variables already present at process start always win.

Feishu Commands

• /codex bind /absolute/path
• /codex where
• /codex workspace
• /codex browse [/absolute/path]
• /codex agents
• /codex agent use <agentName>
• /codex agent run <agentName> <prompt>
• /codex parallel <agent1,agent2,...> <prompt>
• /codex message
• /codex switch <threadId>
• /codex remove /absolute/path
• /codex new
• /codex stop
• /codex approve
• /codex approve session
• /codex reject
• /codex help

Project Structure

• src/index.ts: entrypoint and env loading
• src/cli.ts: CLI runner
• src/feishu-bridge-runtime.ts: Feishu event handling + orchestration
• src/codex-gateway.ts: JSON-RPC transport (spawn/websocket)
• src/conversation-store.ts: local conversation/workspace/agent mapping
• src/codex-message-utils.ts: event/message normalization and parsing
• src/feishu-views.ts: interactive card builders
• src/types.ts: shared runtime types

Open Source / Release Checklist

Before pushing a release or publishing to npm:

npm run check
npm run build
NPM_CONFIG_CACHE=/tmp/.npm-cache-codex-im-bridge npm pack --dry-run

Notes:

• build runs clean first, so stale files in dist/ are removed.
• npm package contents are constrained by the files whitelist in package.json.
• prepack automatically runs npm run build.

Security Notes

• Keep CODEX_IM_BRIDGE_WORKSPACE_ALLOWLIST set in production.
• Treat Feishu app credentials as secrets.
• Keep the host machine online and protected: this service is a bridge to local Codex, not a hosted SaaS.