@lapage/codex-telegram-bridge 0.1.0

package/.env.example

@@ -0,0 +1,17 @@
+TELEGRAM_BOT_TOKEN=123456:replace_me
+TELEGRAM_ALLOWED_USER_IDS=123456789
+CODEX_CWD=~
+CODEX_COMMAND=codex
+CODEX_ARGS=--search --yolo
+CODEX_SUBMIT_KEY=Enter
+CODEX_SUBMIT_DELAY_MS=800
+TMUX_SESSION=codex-telegram-bridge
+CODEX_COLS=120
+CODEX_ROWS=40
+FLUSH_INTERVAL_MS=1200
+POLL_INTERVAL_MS=500
+CODEX_STARTUP_DELAY_MS=1500
+STREAM_EDIT_INTERVAL_MS=650
+STREAM_MIN_CHANGE_CHARS=24
+TYPING_INTERVAL_MS=4000
+MAX_TELEGRAM_CHARS=3500

package/README.md

@@ -0,0 +1,204 @@
+# LaPage Codex Telegram Bridge
+
+Control a local **Codex CLI** session from Telegram without opening any inbound ports to the internet.
+
+This package is useful when Codex runs on a home PC, workstation, homelab box, or private server and you want a simple mobile chat interface. The bridge starts Codex inside a detached `tmux` session, receives Telegram messages from an allowlisted user, sends them into Codex, and relays Codex output back to Telegram.
+
+## Why Use This
+
+- No public SSH, HTTP, webhook, tunnel, or reverse proxy is required.
+- Telegram provides the outbound connection path from your machine.
+- Codex keeps running in `tmux`, so the session can survive terminal disconnects.
+- Access is restricted to the Telegram user IDs you allowlist.
+
+## Requirements
+
+- Node.js 22 or newer
+- npm
+- `tmux`
+- Codex CLI available on `PATH`
+- A Telegram bot token from [@BotFather](https://t.me/BotFather)
+- Your numeric Telegram user ID, for example from [@userinfobot](https://t.me/userinfobot)
+
+Check prerequisites:
+
+```sh
+node --version
+npm --version
+tmux -V
+codex --version
+```
+
+Install `tmux` if it is missing:
+
+```sh
+# macOS
+brew install tmux
+
+# Ubuntu / Debian
+sudo apt update && sudo apt install -y tmux
+
+# Fedora
+sudo dnf install -y tmux
+
+# Arch Linux
+sudo pacman -S tmux
+```
+
+## Quick Start
+
+Install the package globally:
+
+```sh
+npm install -g @lapage/codex-telegram-bridge
+```
+
+Create the default config file:
+
+```sh
+codex-telegram-bridge init
+```
+
+This creates:
+
+```text
+~/.lapage-codex-telegram-bridge/.env
+```
+
+Edit the config file:
+
+```sh
+$EDITOR ~/.lapage-codex-telegram-bridge/.env
+```
+
+At minimum, set these values:
+
+```sh
+TELEGRAM_BOT_TOKEN=123456:your_real_bot_token
+TELEGRAM_ALLOWED_USER_IDS=123456789
+CODEX_CWD=~/Code/your-project
+```
+
+Start the bridge:
+
+```sh
+codex-telegram-bridge
+```
+
+Open your Telegram bot chat and send `/status`. Any normal message after that is sent to Codex as a prompt.
+
+## Configuration File
+
+By default, the CLI reads:
+
+```text
+~/.lapage-codex-telegram-bridge/.env
+```
+
+A local `.env` in the current working directory is also supported, which is useful for development or per-project overrides.
+
+Use a custom config file with:
+
+```sh
+CODEX_TELEGRAM_BRIDGE_ENV=/path/to/.env codex-telegram-bridge
+```
+
+## Configuration Options
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `TELEGRAM_BOT_TOKEN` | required | Telegram bot token from BotFather. |
+| `TELEGRAM_ALLOWED_USER_IDS` | required | Comma-separated numeric Telegram user IDs allowed to use the bot. |
+| `CODEX_CWD` | current directory | Working directory where Codex starts. `~` is supported. |
+| `CODEX_COMMAND` | `codex` | Codex command or binary path. |
+| `CODEX_ARGS` | `--search --yolo` | Extra Codex startup arguments. |
+| `CODEX_SUBMIT_KEY` | `Enter` | tmux key used to submit a prompt to Codex. |
+| `CODEX_SUBMIT_DELAY_MS` | `800` | Delay after pasting text before pressing submit. |
+| `CODEX_STARTUP_DELAY_MS` | `1500` | Delay before first prompt if Codex has not produced output yet. |
+| `TMUX_SESSION` | `codex-telegram-bridge` | Detached tmux session name. |
+| `CODEX_COLS` | `120` | tmux pane width. |
+| `CODEX_ROWS` | `40` | tmux pane height. |
+| `POLL_INTERVAL_MS` | `500` | How often the bridge polls tmux output. |
+| `FLUSH_INTERVAL_MS` | `1200` | Delay before flushing non-stream fallback output. |
+| `STREAM_EDIT_INTERVAL_MS` | `650` | Minimum interval between Telegram message edits. |
+| `STREAM_MIN_CHANGE_CHARS` | `24` | Minimum text growth before editing mid-response. |
+| `TYPING_INTERVAL_MS` | `4000` | How often to send Telegram typing action. |
+| `MAX_TELEGRAM_CHARS` | `3500` | Max response chunk size below Telegram's message limit. |
+
+## Telegram Commands
+
+- `/status` — show bridge state, tmux session, working directory, and Codex command.
+- `/flush` — force-read and relay the latest Codex response.
+- `/interrupt` — send Ctrl-C to Codex.
+- `/restart` — restart the Codex tmux session.
+- `/stop` — stop the Codex tmux session.
+- Any other text is sent directly to Codex as a prompt.
+
+## Running as a Background Service
+
+For a long-running home server setup, run the bridge with your preferred process manager, for example `systemd`, `pm2`, `launchd`, or a persistent `tmux` session.
+
+Example with `tmux`:
+
+```sh
+tmux new -s codex-telegram-bridge-runner 'codex-telegram-bridge'
+```
+
+Detach from tmux with:
+
+```text
+Ctrl-b, then d
+```
+
+## Debugging Codex
+
+The bridge itself runs Codex inside another detached `tmux` session. Attach to it with:
+
+```sh
+tmux attach -t codex-telegram-bridge
+```
+
+If `TMUX_SESSION` is changed in the config file, use that session name instead.
+
+## Install From Source
+
+Use source install if you want to modify or contribute to the bridge:
+
+```sh
+git clone https://github.com/zhuylanz/lapage-codex-telegram-bridge.git
+cd lapage-codex-telegram-bridge
+npm install
+cp .env.example .env
+npm run dev
+```
+
+Build and run locally:
+
+```sh
+npm run build
+npm start
+```
+
+## Development
+
+```sh
+npm run typecheck
+npm run build
+npm run dev
+```
+
+## Security Notes
+
+This bridge exposes a local Codex CLI session through Telegram. Treat the bot as remote control for your machine.
+
+Recommended safeguards:
+
+- Only allow trusted Telegram user IDs in `TELEGRAM_ALLOWED_USER_IDS`.
+- Do not share your Telegram bot token.
+- Run the bridge under a user account with appropriate file permissions.
+- Point `CODEX_CWD` at a workspace you are comfortable controlling remotely.
+- Understand that `CODEX_ARGS=--yolo` allows Codex to act with fewer confirmations.
+
+## Repository
+
+GitHub: <https://github.com/zhuylanz/lapage-codex-telegram-bridge>

package/dist/codex-session.js

@@ -0,0 +1,76 @@
+import { capturePane, runTmux, shellCommand, tmuxSessionExists } from './tmux.js';
+export class CodexSession {
+    config;
+    running = false;
+    startPromise = null;
+    constructor(config) {
+        this.config = config;
+    }
+    get isRunning() {
+        return this.running;
+    }
+    async start() {
+        if (this.startPromise) {
+            return this.startPromise;
+        }
+        this.startPromise = this.startSession().finally(() => {
+            this.startPromise = null;
+        });
+        return this.startPromise;
+    }
+    async stop() {
+        if (await this.exists()) {
+            await runTmux(['kill-session', '-t', this.config.tmuxSession]).catch(() => undefined);
+        }
+        this.running = false;
+    }
+    async restart() {
+        await this.stop();
+        await this.start();
+    }
+    async sendText(text) {
+        await runTmux(['set-buffer', '-b', 'codex-telegram-input', text]);
+        await runTmux(['paste-buffer', '-b', 'codex-telegram-input', '-t', this.config.tmuxSession]);
+        await sleep(this.config.codexSubmitDelayMs);
+        await runTmux(['send-keys', '-t', this.config.tmuxSession, this.config.codexSubmitKey]);
+    }
+    async interrupt() {
+        if (await this.exists()) {
+            await runTmux(['send-keys', '-t', this.config.tmuxSession, 'C-c']);
+        }
+    }
+    async waitUntilReady(hasOutput) {
+        if (this.config.startupDelayMs > 0 && !hasOutput) {
+            await sleep(this.config.startupDelayMs);
+        }
+    }
+    async exists() {
+        return tmuxSessionExists(this.config.tmuxSession);
+    }
+    async capturePane() {
+        return capturePane(this.config.tmuxSession, this.config.rows);
+    }
+    async startSession() {
+        if (this.running && await this.exists()) {
+            return;
+        }
+        await runTmux(['kill-session', '-t', this.config.tmuxSession]).catch(() => undefined);
+        await runTmux([
+            'new-session',
+            '-d',
+            '-s',
+            this.config.tmuxSession,
+            '-c',
+            this.config.codexCwd,
+            '-x',
+            String(this.config.cols),
+            '-y',
+            String(this.config.rows),
+            shellCommand([this.config.codexCommand, ...this.config.codexArgs]),
+        ]);
+        this.running = true;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/config.js

@@ -0,0 +1,52 @@
+export function readConfig() {
+    const token = requireEnv('TELEGRAM_BOT_TOKEN');
+    const allowedUserIds = new Set(requireEnv('TELEGRAM_ALLOWED_USER_IDS')
+        .split(',')
+        .map((value) => Number(value.trim()))
+        .filter((value) => Number.isInteger(value)));
+    if (allowedUserIds.size === 0) {
+        throw new Error('TELEGRAM_ALLOWED_USER_IDS must contain at least one numeric user ID.');
+    }
+    return {
+        token,
+        allowedUserIds,
+        codexCommand: process.env.CODEX_COMMAND || 'codex',
+        codexArgs: parseArgs(process.env.CODEX_ARGS || '--search --yolo'),
+        codexSubmitKey: process.env.CODEX_SUBMIT_KEY || 'Enter',
+        codexSubmitDelayMs: readNumber('CODEX_SUBMIT_DELAY_MS', 800),
+        codexCwd: expandHome(process.env.CODEX_CWD || process.cwd()),
+        tmuxSession: process.env.TMUX_SESSION || 'codex-telegram-bridge',
+        cols: readNumber('CODEX_COLS', 120),
+        rows: readNumber('CODEX_ROWS', 40),
+        flushIntervalMs: readNumber('FLUSH_INTERVAL_MS', 1200),
+        pollIntervalMs: readNumber('POLL_INTERVAL_MS', 500),
+        startupDelayMs: readNumber('CODEX_STARTUP_DELAY_MS', 1500),
+        streamEditIntervalMs: readNumber('STREAM_EDIT_INTERVAL_MS', 650),
+        streamMinChangeChars: readNumber('STREAM_MIN_CHANGE_CHARS', 24),
+        typingIntervalMs: readNumber('TYPING_INTERVAL_MS', 4000),
+        maxTelegramChars: Math.min(readNumber('MAX_TELEGRAM_CHARS', 3500), 3900),
+    };
+}
+function parseArgs(value) {
+    return value.split(' ').map((part) => part.trim()).filter(Boolean);
+}
+function readNumber(name, fallback) {
+    const value = Number(process.env[name]);
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function requireEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`${name} is required.`);
+    }
+    return value;
+}
+function expandHome(value) {
+    if (value === '~') {
+        return process.env.HOME || value;
+    }
+    if (value.startsWith('~/')) {
+        return `${process.env.HOME || '~'}${value.slice(1)}`;
+    }
+    return value;
+}

package/dist/env.js

@@ -0,0 +1,64 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { config as loadDotenv } from 'dotenv';
+const configDirName = '.lapage-codex-telegram-bridge';
+const envFileName = '.env';
+export function defaultConfigDir() {
+    return join(homedir(), configDirName);
+}
+export function defaultEnvPath() {
+    return join(defaultConfigDir(), envFileName);
+}
+export function loadEnvironment() {
+    const loaded = [];
+    const explicitEnvPath = process.env.CODEX_TELEGRAM_BRIDGE_ENV;
+    const candidates = explicitEnvPath
+        ? [resolve(explicitEnvPath)]
+        : [resolve(process.cwd(), envFileName), defaultEnvPath()];
+    for (const path of candidates) {
+        if (!existsSync(path)) {
+            continue;
+        }
+        loadDotenv({ path, override: false });
+        loaded.push(path);
+    }
+    return loaded;
+}
+export function createDefaultEnvFile() {
+    const targetPath = defaultEnvPath();
+    if (existsSync(targetPath)) {
+        return targetPath;
+    }
+    mkdirSync(defaultConfigDir(), { recursive: true, mode: 0o700 });
+    writeFileSync(targetPath, readEnvTemplate(), { mode: 0o600 });
+    return targetPath;
+}
+function readEnvTemplate() {
+    const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+    const templatePath = join(packageRoot, '.env.example');
+    if (existsSync(templatePath)) {
+        return readFileSync(templatePath, 'utf8');
+    }
+    return [
+        'TELEGRAM_BOT_TOKEN=123456:replace_me',
+        'TELEGRAM_ALLOWED_USER_IDS=123456789',
+        'CODEX_CWD=~',
+        'CODEX_COMMAND=codex',
+        'CODEX_ARGS=--search --yolo',
+        'CODEX_SUBMIT_KEY=Enter',
+        'CODEX_SUBMIT_DELAY_MS=800',
+        'TMUX_SESSION=codex-telegram-bridge',
+        'CODEX_COLS=120',
+        'CODEX_ROWS=40',
+        'FLUSH_INTERVAL_MS=1200',
+        'POLL_INTERVAL_MS=500',
+        'CODEX_STARTUP_DELAY_MS=1500',
+        'STREAM_EDIT_INTERVAL_MS=650',
+        'STREAM_MIN_CHANGE_CHARS=24',
+        'TYPING_INTERVAL_MS=4000',
+        'MAX_TELEGRAM_CHARS=3500',
+        '',
+    ].join('\n');
+}

package/dist/index.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { readConfig } from './config.js';
+import { createDefaultEnvFile, defaultEnvPath, loadEnvironment } from './env.js';
+import { TelegramCodexBridge } from './telegram-bridge.js';
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    printHelp();
+    process.exit(0);
+}
+if (process.argv.includes('init')) {
+    const envPath = createDefaultEnvFile();
+    console.log(`Config file ready: ${envPath}`);
+    console.log('Edit it, then run: codex-telegram-bridge');
+    process.exit(0);
+}
+loadEnvironment();
+const bridge = new TelegramCodexBridge(readConfig());
+void bridge.start();
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);
+async function shutdown() {
+    await bridge.stop();
+    process.exit(0);
+}
+function printHelp() {
+    console.log(`LaPage Codex Telegram Bridge
+
+Usage:
+  codex-telegram-bridge init       Create ${defaultEnvPath()}
+  codex-telegram-bridge            Start the bridge
+
+Environment:
+  CODEX_TELEGRAM_BRIDGE_ENV=/path/to/.env  Use a custom config file
+`);
+}

package/dist/telegram-bridge.js

@@ -0,0 +1,334 @@
+import { Bot } from 'grammy';
+import { CodexSession } from './codex-session.js';
+import { chunkText, formatTelegramMarkdown, isCodexWorking, latestCodexResponse, latestCompletedCodexResponse, plainTelegramText } from './text.js';
+export class TelegramCodexBridge {
+    config;
+    bot;
+    codex;
+    activeChatId = null;
+    outputBuffer = '';
+    lastOutputAt = null;
+    flushTimer = null;
+    pollTimer = null;
+    lastPaneResponse = '';
+    lastSentResponse = '';
+    lastSnapshotSentAt = 0;
+    streamMessageId = null;
+    lastStreamText = '';
+    lastStreamEditAt = 0;
+    typingTimer = null;
+    sendQueue = Promise.resolve();
+    constructor(config) {
+        this.config = config;
+        this.bot = new Bot(config.token);
+        this.codex = new CodexSession(config);
+    }
+    async start() {
+        await this.codex.start();
+        this.startPollingOutput();
+        this.bot.on('message', async (context) => this.handleMessage(context));
+        this.bot.catch((error) => {
+            console.error('Telegram bot error:', error.message);
+        });
+        this.bot.start();
+    }
+    async stop() {
+        this.stopPollingOutput();
+        this.stopTypingIndicator();
+        await this.codex.stop();
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.bot.stop();
+    }
+    async handleMessage(context) {
+        const chatId = context.chat?.id;
+        const userId = context.from?.id;
+        if (!chatId) {
+            return;
+        }
+        if (!userId || !this.config.allowedUserIds.has(userId)) {
+            await context.reply('Not authorized.');
+            return;
+        }
+        this.activeChatId = chatId;
+        const text = context.message?.text ?? '';
+        if (!text.trim()) {
+            await context.reply('Send text to forward it to Codex.');
+            return;
+        }
+        if (await this.handleCommand(context, text.trim())) {
+            return;
+        }
+        if (!this.codex.isRunning) {
+            await this.codex.start();
+        }
+        await this.codex.waitUntilReady(Boolean(this.lastOutputAt));
+        await this.codex.sendText(text);
+        const streamMessage = await context.reply('Codex is working…');
+        this.streamMessageId = streamMessage.message_id;
+        this.lastStreamText = 'Codex is working…';
+        this.lastStreamEditAt = Date.now();
+        this.startTypingIndicator();
+    }
+    async handleCommand(context, text) {
+        switch (text) {
+            case '/start':
+            case '/help':
+                await context.reply(this.helpText());
+                return true;
+            case '/status':
+                await context.reply(this.statusText());
+                return true;
+            case '/flush':
+                await this.readNewOutput(true);
+                await this.flushOutput(true);
+                return true;
+            case '/interrupt':
+                await this.codex.interrupt();
+                await context.reply('Sent Ctrl-C to Codex.');
+                return true;
+            case '/restart':
+                await this.codex.restart();
+                this.resetSnapshots();
+                this.stopTypingIndicator();
+                await context.reply('Restarted Codex.');
+                return true;
+            case '/stop':
+                await this.codex.stop();
+                this.stopTypingIndicator();
+                await context.reply('Stopped Codex. Send any message to start it again.');
+                return true;
+            default:
+                return false;
+        }
+    }
+    startPollingOutput() {
+        this.stopPollingOutput();
+        this.pollTimer = setInterval(() => {
+            void this.readNewOutput();
+            void this.refreshCodexRunningState();
+        }, this.config.pollIntervalMs);
+    }
+    stopPollingOutput() {
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+    }
+    startTypingIndicator() {
+        if (!this.activeChatId) {
+            return;
+        }
+        this.stopTypingIndicator();
+        void this.sendTypingAction();
+        this.typingTimer = setInterval(() => {
+            void this.sendTypingAction();
+        }, this.config.typingIntervalMs);
+    }
+    stopTypingIndicator() {
+        if (this.typingTimer) {
+            clearInterval(this.typingTimer);
+            this.typingTimer = null;
+        }
+    }
+    async sendTypingAction() {
+        if (!this.activeChatId) {
+            return;
+        }
+        await this.bot.api.sendChatAction(this.activeChatId, 'typing').catch(() => undefined);
+    }
+    async readNewOutput(force = false) {
+        if (!this.activeChatId || !await this.codex.exists()) {
+            return;
+        }
+        const pane = await this.codex.capturePane();
+        const response = force ? latestCompletedCodexResponse(pane) : latestCodexResponse(pane);
+        const working = isCodexWorking(pane);
+        if (this.streamMessageId && response) {
+            await this.editStreamMessage(response, !working || force);
+            if (!working || force) {
+                this.stopTypingIndicator();
+            }
+        }
+        if (working && !force) {
+            return;
+        }
+        if (!response || (!force && response === this.lastPaneResponse)) {
+            return;
+        }
+        this.lastPaneResponse = response;
+        if (!force && !this.shouldSendResponse(response)) {
+            return;
+        }
+        this.lastSentResponse = response;
+        this.lastSnapshotSentAt = Date.now();
+        this.outputBuffer = response;
+        this.lastOutputAt = new Date();
+        if (!this.streamMessageId) {
+            this.scheduleFlush();
+        }
+    }
+    async refreshCodexRunningState() {
+        const exists = await this.codex.exists();
+        if (!exists && this.codex.isRunning) {
+            this.outputBuffer = '[Codex tmux session exited]';
+            this.scheduleFlush();
+        }
+    }
+    shouldSendResponse(response) {
+        if (response === this.lastSentResponse) {
+            return false;
+        }
+        return true;
+    }
+    scheduleFlush() {
+        if (this.flushTimer) {
+            return;
+        }
+        this.flushTimer = setTimeout(async () => {
+            this.flushTimer = null;
+            await this.flushOutput(false);
+        }, this.config.flushIntervalMs);
+    }
+    async flushOutput(force) {
+        if (!this.activeChatId) {
+            return;
+        }
+        const trimmed = this.outputBuffer.trimEnd();
+        if (!trimmed) {
+            if (force) {
+                await this.queueTelegramSend(() => this.bot.api.sendMessage(this.activeChatId, 'No buffered output.'));
+            }
+            this.outputBuffer = '';
+            return;
+        }
+        this.outputBuffer = '';
+        for (const chunk of chunkText(trimmed, this.config.maxTelegramChars)) {
+            await this.sendFormattedMessage(chunk);
+        }
+    }
+    async editStreamMessage(text, force) {
+        if (!this.activeChatId || !this.streamMessageId) {
+            return;
+        }
+        const trimmed = text.trim();
+        if (!trimmed || trimmed === this.lastStreamText) {
+            return;
+        }
+        const now = Date.now();
+        if (!force && !this.isMeaningfulStreamChange(trimmed, now)) {
+            return;
+        }
+        const [chunk] = chunkText(trimmed, this.config.maxTelegramChars);
+        await this.editFormattedMessage(chunk);
+        this.lastStreamText = trimmed;
+        this.lastStreamEditAt = now;
+    }
+    async sendFormattedMessage(text) {
+        if (!this.activeChatId) {
+            return;
+        }
+        const markdown = formatTelegramMarkdown(text);
+        const chatId = this.activeChatId;
+        const sent = await this.queueTelegramSend(() => this.bot.api.sendMessage(chatId, markdown, { parse_mode: 'MarkdownV2' }))
+            .then(() => true)
+            .catch(() => false);
+        if (!sent) {
+            await this.queueTelegramSend(() => this.bot.api.sendMessage(chatId, plainTelegramText(text)));
+        }
+    }
+    async editFormattedMessage(text) {
+        if (!this.activeChatId || !this.streamMessageId) {
+            return;
+        }
+        const markdown = formatTelegramMarkdown(text);
+        const edited = await this.bot.api.editMessageText(this.activeChatId, this.streamMessageId, markdown, {
+            parse_mode: 'MarkdownV2',
+        }).then(() => true).catch(() => false);
+        if (!edited) {
+            await this.bot.api.editMessageText(this.activeChatId, this.streamMessageId, plainTelegramText(text)).catch(() => undefined);
+        }
+    }
+    queueTelegramSend(operation) {
+        const run = async () => {
+            await sleep(350);
+            return retryTelegramOperation(operation);
+        };
+        const next = this.sendQueue.then(run, run);
+        this.sendQueue = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    isMeaningfulStreamChange(nextText, now) {
+        if (now - this.lastStreamEditAt < this.config.streamEditIntervalMs) {
+            return false;
+        }
+        if (nextText.length < this.lastStreamText.length) {
+            return true;
+        }
+        return nextText.length - this.lastStreamText.length >= this.config.streamMinChangeChars;
+    }
+    statusText() {
+        return [
+            `Codex: ${this.codex.isRunning ? 'running' : 'stopped'}`,
+            `tmux: ${this.config.tmuxSession}`,
+            `CWD: ${this.config.codexCwd}`,
+            `Command: ${[this.config.codexCommand, ...this.config.codexArgs].join(' ')}`,
+            `Submit key: ${this.config.codexSubmitKey}`,
+            `Submit delay: ${this.config.codexSubmitDelayMs}ms`,
+            `Buffered chars: ${this.outputBuffer.length}`,
+            `Last output: ${this.lastOutputAt?.toISOString() ?? 'none'}`,
+        ].join('\n');
+    }
+    helpText() {
+        return [
+            'Telegram ↔ Codex bridge commands:',
+            '/status - show bridge status',
+            '/flush - send buffered Codex output now',
+            '/interrupt - send Ctrl-C to Codex',
+            '/restart - restart Codex session',
+            '/stop - stop Codex session',
+            '',
+            'Any other text is sent directly to the Codex CLI.',
+        ].join('\n');
+    }
+    resetSnapshots() {
+        this.lastPaneResponse = '';
+        this.lastSentResponse = '';
+        this.lastSnapshotSentAt = 0;
+        this.lastOutputAt = null;
+        this.streamMessageId = null;
+        this.lastStreamText = '';
+        this.lastStreamEditAt = 0;
+        this.stopTypingIndicator();
+    }
+}
+async function retryTelegramOperation(operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        const retryAfter = telegramRetryAfterMs(error);
+        if (retryAfter === null) {
+            throw error;
+        }
+        await sleep(retryAfter);
+        return operation();
+    }
+}
+function telegramRetryAfterMs(error) {
+    const parameters = error.parameters;
+    if (typeof parameters?.retry_after === 'number') {
+        return (parameters.retry_after + 1) * 1000;
+    }
+    const description = error.description;
+    const match = description?.match(/retry after (\d+)/i);
+    if (match) {
+        return (Number(match[1]) + 1) * 1000;
+    }
+    return null;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/text.js

@@ -0,0 +1,272 @@
+import stripAnsi from 'strip-ansi';
+export function normalizeTerminalOutput(data) {
+    return stripAnsi(data)
+        .replace(/\r\n/g, '\n')
+        .replace(/\r/g, '\n')
+        .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '');
+}
+function visibleText(data) {
+    return normalizeTerminalOutput(data);
+}
+export function cleanPaneSnapshot(data) {
+    const lines = paneLines(data);
+    return collapseRepeatedLines(lines).join('\n').trim();
+}
+export function latestCompletedCodexResponse(data) {
+    const lines = paneLines(data);
+    if (isCodexWorking(data)) {
+        return null;
+    }
+    return latestCodexResponse(data);
+}
+export function latestCodexResponse(data) {
+    const lines = paneLines(data);
+    const lastResponseBullet = findLastIndex(lines, (line) => {
+        const trimmed = visibleText(line).trimStart();
+        return trimmed.startsWith('• ') && !/^•\s*Working\s*\(/i.test(trimmed);
+    });
+    if (lastResponseBullet === -1) {
+        return null;
+    }
+    const promptStart = findLastIndex(lines.slice(0, lastResponseBullet), (line) => isUserPromptLine(visibleText(line).trim()));
+    const responseStart = promptStart === -1 ? lastResponseBullet : promptStart + 1;
+    const response = [];
+    for (const line of lines.slice(responseStart)) {
+        const trimmed = visibleText(line).trim();
+        if (response.length > 0 && isPromptOrStatusLine(trimmed)) {
+            break;
+        }
+        if (isIgnorableResponseLine(trimmed)) {
+            continue;
+        }
+        response.push(line);
+    }
+    const cleaned = collapseRepeatedLines(response).join('\n').trim();
+    return cleaned || null;
+}
+export function isCodexWorking(data) {
+    return paneLines(data).some((line) => /esc to interrupt|^\s*•\s*Working\s*\(/i.test(visibleText(line)));
+}
+export function chunkText(text, maxLength) {
+    const chunks = [];
+    let remaining = text;
+    while (remaining.length > maxLength) {
+        const newlineIndex = remaining.lastIndexOf('\n', maxLength);
+        const splitIndex = newlineIndex > maxLength * 0.5 ? newlineIndex : maxLength;
+        chunks.push(remaining.slice(0, splitIndex));
+        remaining = remaining.slice(splitIndex).trimStart();
+    }
+    if (remaining) {
+        chunks.push(remaining);
+    }
+    return chunks;
+}
+export function wrapCodeBlock(text) {
+    return `\`\`\`text\n${escapeMarkdownV2(text)}\n\`\`\``;
+}
+export function formatTelegramMarkdown(text) {
+    return formatTelegramMarkdownLines(text)
+        .join('\n\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+export function formatTelegramMarkdownLines(text) {
+    return normalizeWrappedLines(text)
+        .split('\n')
+        .map(formatTelegramLine)
+        .filter((line) => line.trim().length > 0);
+}
+export function plainTelegramText(text) {
+    return plainTelegramLines(text)
+        .join('\n\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+export function plainTelegramLines(text) {
+    return normalizeWrappedLines(text)
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line) => line.trim().length > 0);
+}
+function isDecorativeLine(line) {
+    const trimmed = visibleText(line).trim();
+    if (/^[╭╮╰╯│─┌┐└┘├┤┬┴┼╞╡═\s]+$/.test(trimmed)) {
+        return true;
+    }
+    if (/^Tip: /.test(trimmed)) {
+        return true;
+    }
+    if (/^model:\s+/.test(trimmed) || /^directory:\s+/.test(trimmed)) {
+        return true;
+    }
+    if (/^>_ OpenAI Codex/.test(trimmed)) {
+        return true;
+    }
+    return false;
+}
+function paneLines(data) {
+    return normalizeTerminalOutput(data)
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line) => visibleText(line).trim().length > 0)
+        .filter((line) => !isDecorativeLine(line))
+        .filter((line) => !isIgnorablePaneLine(visibleText(line).trim()));
+}
+function isPromptOrStatusLine(trimmed) {
+    return isUserPromptLine(trimmed)
+        || /^agentic\s+/.test(trimmed)
+        || /^•\s*Working\s*\(/i.test(trimmed)
+        || /^─\s*Worked for\b/.test(trimmed);
+}
+function isUserPromptLine(trimmed) {
+    return trimmed.startsWith('› ');
+}
+function isIgnorablePaneLine(trimmed) {
+    return /^⚠ Model metadata for `agentic` not found/.test(trimmed)
+        || /^can degrade performance and cause issues\.$/.test(trimmed)
+        || /^fallback metadata;/.test(trimmed)
+        || /^issues\.$/.test(trimmed)
+        || /^─\s*Worked for\b/.test(trimmed)
+        || /^agentic\s+/.test(trimmed)
+        || /^› (Write tests for @filename|Summarize recent commits|Implement \{feature\}|Improve documentation in @filename)/.test(trimmed);
+}
+function isIgnorableResponseLine(trimmed) {
+    return isIgnorablePaneLine(trimmed) || /^⚠ /.test(trimmed);
+}
+function normalizeWrappedLines(text) {
+    const lines = text.split('\n');
+    const normalized = [];
+    for (const line of lines) {
+        const current = line.trimEnd();
+        const previous = normalized[normalized.length - 1];
+        if (previous && shouldJoinSoftWrap(previous, current)) {
+            const separator = previous.trimEnd().endsWith('-') ? '' : ' ';
+            normalized[normalized.length - 1] = `${previous.replace(/\s+$/, '')}${separator}${current.trimStart()}`;
+        }
+        else {
+            normalized.push(current);
+        }
+    }
+    return normalized.join('\n');
+}
+function shouldJoinSoftWrap(previous, current) {
+    const trimmedPrevious = visibleText(previous).trim();
+    const trimmedCurrent = visibleText(current).trim();
+    if (!trimmedCurrent) {
+        return false;
+    }
+    if (/^(•|-|└|↳|›|```)/.test(trimmedCurrent)) {
+        return false;
+    }
+    if (/^(└|↳)/.test(trimmedPrevious)) {
+        return false;
+    }
+    if (/^\//.test(trimmedCurrent)) {
+        return false;
+    }
+    if (/^(•|-|└|↳|›)/.test(trimmedPrevious) && !/[.!?:;)]$/.test(trimmedPrevious)) {
+        return true;
+    }
+    if (/\b(and|or|with|to|from|by|for|including|containing|credential-)$/i.test(trimmedPrevious)) {
+        return true;
+    }
+    if (trimmedPrevious.endsWith('-')) {
+        return true;
+    }
+    return !/[.!?:;)]$/.test(trimmedPrevious) && /^[a-z0-9(/]/i.test(trimmedCurrent);
+}
+function formatTelegramLine(line) {
+    const style = lineStyle(line);
+    const trimmed = visibleText(line).trim();
+    if (!trimmed) {
+        return '';
+    }
+    if (style.hasBold && /(?:^•\s+)?Ran\b/.test(trimmed)) {
+        const command = trimmed.replace(/^•\s+Ran\s+/, '').replace(/^Ran\s+/, '');
+        return blockQuote(`🔧 *Ran* ${inlineCode(command)}`);
+    }
+    if (trimmed.startsWith('• Ran ')) {
+        return blockQuote(`🔧 *Ran* ${inlineCode(trimmed.slice('• Ran '.length))}`);
+    }
+    if (style.hasBold && /background terminal/i.test(trimmed)) {
+        return blockQuote(`🔧 _${escapeMarkdownV2(trimmed.replace(/^•\s+/, ''))}_`);
+    }
+    if (trimmed.startsWith('• Waited for background terminal')) {
+        return blockQuote(`🔧 _${escapeMarkdownV2(trimmed.slice(2))}_`);
+    }
+    if (style.hasDim && isThinkingLine(trimmed)) {
+        return blockQuote(`🧠 _${escapeMarkdownV2(trimmed.slice(2))}_`);
+    }
+    if (trimmed.startsWith('↳ Interacted with background terminal')) {
+        return blockQuote(`🔧 _${escapeMarkdownV2(trimmed)}_`);
+    }
+    if (trimmed.startsWith('└')) {
+        return blockQuote(`   _${escapeMarkdownV2(trimmed)}_`);
+    }
+    if (trimmed.startsWith('• Explored')) {
+        return '*Explored*';
+    }
+    if (trimmed.startsWith('• ')) {
+        return `• ${escapeMarkdownV2(trimmed.slice(2))}`;
+    }
+    if (trimmed.startsWith('- ')) {
+        return `  ◦ ${escapeMarkdownV2(trimmed.slice(2))}`;
+    }
+    if (/^\s{2,}\S/.test(visibleText(line))) {
+        return `   ${escapeMarkdownV2(trimmed)}`;
+    }
+    return escapeMarkdownV2(trimmed);
+}
+function inlineCode(text) {
+    return `\`${text.replace(/[`\\]/g, '\\$&')}\``;
+}
+function lineStyle(line) {
+    const sgrMatches = line.match(/\x1b\[[0-9;]*m/g) ?? [];
+    let hasDim = false;
+    let hasBold = false;
+    for (const match of sgrMatches) {
+        const codes = match.slice(2, -1).split(';').map((code) => Number(code || 0));
+        if (codes.includes(0)) {
+            continue;
+        }
+        if (codes.includes(1)) {
+            hasBold = true;
+        }
+        if (codes.includes(2)) {
+            hasDim = true;
+        }
+    }
+    return { hasDim, hasBold };
+}
+function blockQuote(markdown) {
+    return markdown
+        .split('\n')
+        .map((line) => `> ${line}`)
+        .join('\n');
+}
+function isThinkingLine(trimmed) {
+    return /^•\s+I(?:’|'|`)?m\s+(thinking|considering|checking|looking|trying|wondering|deciding|figuring|reasoning|planning)\b/i.test(trimmed)
+        || /^•\s+I\s+need\s+to\s+think\b/i.test(trimmed)
+        || /^•\s+I\s+need\s+to\s+(provide|answer|decide|figure|check|inspect|verify)\b/i.test(trimmed)
+        || /^•\s+Let\s+me\s+think\b/i.test(trimmed);
+}
+function findLastIndex(items, predicate) {
+    for (let index = items.length - 1; index >= 0; index -= 1) {
+        if (predicate(items[index])) {
+            return index;
+        }
+    }
+    return -1;
+}
+function collapseRepeatedLines(lines) {
+    const collapsed = [];
+    for (const line of lines) {
+        if (collapsed[collapsed.length - 1] !== line) {
+            collapsed.push(line);
+        }
+    }
+    return collapsed;
+}
+function escapeMarkdownV2(text) {
+    return text.replace(/([_*.\[\]()~`>#+\-=|{}!\\])/g, '\\$1');
+}

package/dist/tmux.js

@@ -0,0 +1,25 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export async function runTmux(args) {
+    const { stdout } = await execFileAsync('tmux', args, { env: process.env });
+    return stdout;
+}
+export async function tmuxSessionExists(session) {
+    try {
+        await runTmux(['has-session', '-t', session]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function capturePane(session, rows) {
+    return runTmux(['capture-pane', '-p', '-t', session, '-S', `-${rows}`]);
+}
+export function shellCommand(parts) {
+    return parts.map(shellQuote).join(' ');
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@lapage/codex-telegram-bridge",
+  "version": "0.1.0",
+  "description": "Private Telegram bridge for controlling Codex CLI on a home PC or server without opening inbound ports.",
+  "type": "module",
+  "bin": {
+    "codex-telegram-bridge": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    ".env.example"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhuylanz/lapage-codex-telegram-bridge.git"
+  },
+  "homepage": "https://github.com/zhuylanz/lapage-codex-telegram-bridge#readme",
+  "bugs": {
+    "url": "https://github.com/zhuylanz/lapage-codex-telegram-bridge/issues"
+  },
+  "keywords": [
+    "codex",
+    "codex-cli",
+    "telegram",
+    "telegram-bot",
+    "tmux",
+    "remote-control",
+    "agent"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.7",
+    "grammy": "^1.44.0",
+    "strip-ansi": "^7.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}