Lark Bridge

Lark Bridge connects Telegram or iMessage to an AI CLI so messages sent from your phone can be answered from your desktop workflow.

The current build is centered on OpenAI Codex CLI as the active AI backend.

What It Does

• Receives messages from Telegram or iMessage
• Forwards them to the configured AI CLI
• Sends the AI response back to the same chat
• Provides basic control commands for pausing, stopping, retrying, and checking status

Current Support

AI Provider

• Codex CLI via @openai/codex

Messaging Platforms

• Telegram on Windows, macOS, and Linux
• iMessage on macOS only

Requirements

• Node.js 16 or newer
• A working installation of the Codex CLI
• Telegram bot credentials if you use Telegram
• macOS with Messages.app signed in if you use iMessage

Install

From npm

npm install -g lark-bridge

From source

git clone https://github.com/AhmadTheTech/lark
cd lark
npm install
npm link

Configure

Run the interactive setup:

lark configure

You will choose:

• The AI provider
• The messaging platform
• Platform-specific settings

Telegram Setup

1. Open Telegram and start a chat with @BotFather
2. Send /newbot and follow the prompts
3. Copy the bot token it returns
4. Find your Telegram user ID with @userinfobot
5. Enter the token and allowed user IDs during lark configure

You can allow multiple users by entering comma-separated numeric IDs.

iMessage Setup

Lark uses AppleScript to interact with Messages.app.

Before starting:

1. Sign in to iMessage on your Mac
2. Allow Terminal to control Messages when prompted
3. If needed, grant Contacts access as well

On iMessage, the bridge checks for new messages on a polling interval selected during setup.

Start

lark start

For verbose logging:

lark start --debug

CLI Commands

lark configure   # Run interactive setup
lark start       # Launch the bridge
lark status      # Show saved configuration
lark reset       # Remove saved configuration

Telegram Commands

Once the bot is running, these commands are available in Telegram:

• /start - show bridge status
• /help - list commands
• /status - show uptime, provider, and message stats
• /ai - show the active AI provider
• /pause - stop forwarding messages
• /resume - resume forwarding
• /stop - cancel the current AI request
• /clear - clear conversation context
• /retry - retry the last failed message
• /ping - check that the bridge is alive
• /version - display the installed Lark version
• /shutdown - stop the bridge process

How It Works

You
  -> Telegram or iMessage
  -> Lark Bridge
  -> Codex CLI
  -> Lark Bridge
  -> Telegram or iMessage
  -> You

Configuration Location

Lark stores its config under:

~/.lark/config

Use lark status to inspect the saved values.

Contributing

• If you found an issue, open an issue.
• If you want to contribute, see contribution.md.

License

For license details, see LICENSE.