lark-coding-agent-bridge

# lark-coding-agent-bridge > Skill by [ara.so](https://ara.so) — AI Agent Skills collection. A lightweight bot that bridges Feishu/Lark messenger with your local Claude Code or Codex CLI. Send messages in Feishu and get streaming responses with tool calls updating in real-time cards. Each chat/topic maintains its own session with support for multiple workspaces, queueing, and file attachments. ## What It Does - **Message forwarding**: DM the bot or `@mention` in groups to talk to your local coding agent - **Streaming cards**: Real-time updates of text replies and tool calls on a single Lark card - **Session continuity**: Each chat, topic, or document comment thread maintains its own session - **Queue management**: Messages sent quickly are batched; commands like `/new`, `/cd`, `/stop` interrupt current runs - **Multiple workspaces**: Switch projects with `/cd` and save common directories with `/ws` - **Media support**: Send images and files directly to the bot - **Access control**: Private by default with granular user/group permissions ## Prerequisites - Node.js >= 20.12.0 - At least one local agent installed and authenticated: - Claude Code: `claude` (https://docs.anthropic.com/en/docs/claude-code/quickstart) - Codex CLI: `codex` (https://developers.openai.com/codex/cli) - A Feishu/Lark PersonalAgent app (QR wizard creates one on first run) ## Installation ```bash # Global installation (recommended for background service) npm i -g lark-channel-bridge # Or with pnpm pnpm add -g lark-channel-bridge # Or run directly with npx (foreground only) npx lark-channel-bridge run ``` ## First-Time Setup ```bash # Start the QR wizard lark-channel-bridge run # With existing app ID lark-channel-bridge run --app-id cli_xxx # For Lark global apps lark-channel-bridge run --app-id cli_xxx --tenant lark # Specify agent type explicitly lark-channel-bridge run --agent claude # Set initial workspace lark-channel-bridge run --workspace /path/to/project ``` The QR wizard: 1. Displays QR code in terminal 2. Scan with Feishu/Lark app 3. Pick/create a PersonalAgent app 4. Choose agent to initialize (claude or codex) 5. Config saved to `~/.lark-channel/config.json` ## Background Service Management ```bash # Start background service (macOS: launchd, Linux: systemd, Windows: Task Scheduler) lark-channel-bridge start # Check status lark-channel-bridge status # Stop service lark-channel-bridge stop # Restart service lark-channel-bridge restart # Remove service registration lark-channel-bridge unregister ``` **Important**: Install globally before using service commands. The daemon records the CLI path, and `npx` temp cache paths break when cleaned. ### Multiple Profiles (Claude + Codex) ```bash # Create separate profiles for different agents lark-channel-bridge profile create claude --agent claude lark-channel-bridge profile create codex --agent codex # List all profiles lark-channel-bridge profile list # Switch active profile lark-channel-bridge profile use claude # Start specific profile lark-channel-bridge start --profile claude lark-channel-bridge start --profile codex # Check specific profile status lark-channel-bridge status --profile codex # Remove profile (archives by default) lark-channel-bridge profile remove codex # Permanently delete profile lark-channel-bridge profile remove codex --purge --yes # Export profile (secrets redacted) lark-channel-bridge profile export claude --output ./claude-profile.json # Export with secrets lark-channel-bridge profile export claude --include-secrets --yes ``` ## In-Chat Slash Commands ### Session Management ``` /new # Clear current session /reset # Alias for /new /cd /path/to/dir # Switch working directory and reset session /resume # Resume compatible history for same agent/directory/permissions /timeout 30 # Set 30-minute idle timeout /timeout off # Disable timeout /timeout default # Restore default timeout /stop # Stop current run ``` ### Workspace Management ``` /ws list # List all named workspaces /ws save myproject # Save current directory as "myproject" /ws use myproject # Switch to "myproject" workspace /ws remove myproject # Delete "myproject" workspace ``` ### Access Control ``` /invite user @username # Allow user to DM the bot /invite admin @username # Add access-control admin /invite group # Allow current group to use bot /invite all group # Allow all groups bot has joined /remove user @username # Remove user access /remove admin @username # Remove admin /remove group # Remove current group access ``` ### Diagnostics & Info ``` /status # Show profile, agent, working directory, session state /config # Adjust preferences and view access panel /help # Display help card /ps # List local bridge processes /exit <id|#> # Stop a bridge process /reconnect # Force WebSocket reconnect /doctor # Run diagnostics (include description for context) ``` ## Configuration ### Profile Structure Config location: `~/.lark-channel/config.json` ```json { "activeProfile": "default", "profiles": { "default": { "name": "default", "agent": "claude", "feishu": { "appId": "cli_xxx", "tenant": "feishu" }, "workspaces": { "default": "/Users/me/.lark-channel-workspaces/claude/default", "named": { "myproject": "/Users/me/projects/myproject", "webapp": "/Users/me/work/webapp" } }, "permissions": { "defaultAccess": "full", "maxAccess": "full" } } } } ``` ### Permission Modes Edit the profile's `permissions` field: ```json { "permissions": { "defaultAccess": "full", "maxAccess": "full" } } ``` Mode mappings: | Bridge Access | Claude Mode | Codex Mode | Capabilities | |--------------|-------------|------------|--------------| | `full` | `bypassPermissions` | `danger-full-access` | All tools, auth flows, file writes | | `workspace` | `acceptEdits` | `workspace-write` | Limited to workspace directory | | `read-only` | `plan` | `read-only` | No file writes or dangerous operations | ### Working Directories The bridge validates directories exist, are actual directories, and aren't overly broad (not `/`, home root, system dirs, temp roots). ```typescript // Profile field snippet - edit matching profile's workspaces { "workspaces": { "default": "/Users/me/projects/default", "named": { "backend": "/Users/me/work/backend-api", "frontend": "/Users/me/work/web-client", "mobile": "/Users/me/work/mobile-app" } } } ``` Switch in chat: ``` /cd /Users/me/work/new-project /ws save new-project /ws use backend ``` ## Process Management ```bash # List all running bridge processes lark-channel-bridge ps # Kill specific process by ID or index lark-channel-bridge kill 12345 lark-channel-bridge kill 1 # First in list ``` In Feishu chat: ``` /ps # List processes /exit 1 # Stop first process /exit 12345 # Stop by PID ``` ## Data Directories ``` ~/.lark-channel/ ├── config.json # Root config with profiles ├── active-profile # Last selected profile ├── profiles/ │ └── <profile>/ │ ├── sessions.json # Session state │ ├── sessions.json.catalog.json # Agent-aware session catalog │ ├── workspaces.json # Workspace bindings │ ├── secrets.enc # Encrypted secrets │ ├── media/ # Attachment cache │ └── logs/ │ ├── daemon/ # Background service logs │ └── <timestamp>/ # Structured run logs └── registry/ ├── processes.json # Process registry └── locks/ # Profile and app locks ``` ### Environment Variables ```bash # Move all local bridge state export LARK_CHANNEL_HOME=/custom/path/to/state # Override log retention (default: 7 days) export LARK_CHANNEL_LOG_DAYS=30 ``` ## Code Examples ### Starting Multiple Agent Profiles ```bash #!/bin/bash # setup-dual-agents.sh - Run both Claude and Codex bridges # Create profiles if they don't exist lark-channel-bridge profile create claude --agent claude --workspace ~/projects lark-channel-bridge profile create codex --agent codex --workspace ~/projects # Start both services lark-channel-bridge start --profile claude lark-channel-bridge start --profile codex # Verify both are running lark-channel-bridge status --profile claude lark-channel-bridge status --profile codex ``` ### Scripted Deployment ```bash #!/bin/bash # deploy-lark-bridge.sh - Automated deployment set -e PROFILE_NAME="${1:-production}" AGENT_TYPE="${2:-claude}" WORKSPACE_PATH="${3:-$HOME/workspace}" APP_ID="${LARK_APP_ID}" # From environment APP_SECRET="${LARK_APP_SECRET}" # From environment if [ -z "$APP_ID" ] || [ -z "$APP_SECRET" ]; then echo "Error: Set LARK_APP_ID and LARK_APP_SECRET" exit 1 fi # Create profile lark-channel-bridge profile create "$PROFILE_NAME" \ --agent "$AGENT_TYPE" \ --workspace "$WORKSPACE_PATH" # Use the new profile lark-channel-bridge profile use "$PROFILE_NAME" # Start with app credentials (will prompt for secret if interactive) lark-channel-bridge start --profile "$PROFILE_NAME" --app-id "$APP_ID" echo "Bridge deployed as profile: $PROFILE_NAME" ``` ### Health Check Script ```bash #!/bin/bash # healthcheck.sh - Monitor bridge health PROFILE="${1:-default}" # Check if service is running if ! lark-channel-bridge status --profile "$PROFILE" | grep -q "running"; then echo "Bridge not running, attempting restart..." lark-channel-bridge restart --profile "$PROFILE" # Wait and verify sleep 5 if lark-channel-bridge status --profile "$PROFILE" | grep -q "running"; then echo "Bridge restarted successfully" exit 0 else echo "Bridge failed to restart" exit 1 fi fi echo "Bridge healthy" exit 0 ``` ### Programmatic Configuration Update ```typescript // update-config.ts - Modify profile settings programmatically import { readFileSync, writeFileSync } from 'fs'; import { homedir } from 'os'; import { join } from 'path'; interface Profile { name: string; agent: 'claude' | 'codex'; permissions?: { defaultAccess: 'full' | 'workspace' | 'read-only'; maxAccess: 'full' | 'workspace' | 'read-only'; }; workspaces?: { default: string; named?: Record<string, string>; }; } interface Config { activeProfile: string; profiles: Record<string, Profile>; } const configPath = join(homedir(), '.lark-channel', 'config.json'); function updateProfilePermissions( profileName: string, mode: 'full' | 'workspace' | 'read-only' ): void { const config: Config = JSON.parse(readFileSync(configPath, 'utf-8')); if (!config.profiles[profileName]) { throw new Error(`Profile ${profileName} not found`); } config.profiles[profileName].permissions = { defaultAccess: mode, maxAccess: mode, }; writeFileSync(configPath, JSON.stringify(config, null, 2)); console.log(`Updated ${profileName} to ${mode} mode`); } function addWorkspace( profileName: string, name: string, path: string ): void { const config: Config = JSON.parse(readFileSync(configPath, 'utf-8')); if (!config.profiles[profileName]) { throw new Error(`Profile ${profileName} not found`); } if (!config.profiles[profileName].workspaces) { config.profiles[profileName].workspaces = { default: path, named: {}, }; } if (!config.profiles[profileName].workspaces!.named) { config.profiles[profileName].workspaces!.named = {}; } config.profiles[profileName].workspaces!.named![name] = path; writeFileSync(configPath, JSON.stringify(config, null, 2)); console.log(`Added workspace ${name}: ${path} to ${profileName}`); } // Example usage updateProfilePermissions('production', 'workspace'); addWorkspace('production', 'api', '/home/user/projects/api'); ``` ## Common Patterns ### Multi-Workspace Development ``` # Start with default workspace lark-channel-bridge run # In Feishu, save current projects /cd ~/work/backend /ws save backend /cd ~/work/frontend /ws save frontend