EchoLoop

한국어 · English

Receive AI results on Telegram and reply to the notification to continue the same session.

One Telegram bot can serve multiple AI sessions on the same computer. EchoLoop routes your reply using the original notification. It runs locally without a public server or inbound port.

Install

Requires Node.js 20+, npm, and Codex or Claude Code available on PATH. Windows, macOS, and Linux use the same commands.

From a checkout of this repository:

npm ci
npm pack
npm install -g ./echoloop-mcp-0.1.0.tgz

npm pack builds the TypeScript output. Install the generated package globally once; other projects do not need a copy of the repository. For source development, use npm run build followed by npm link instead.

After a registry release is published, the equivalent installation is npm install -g echoloop-mcp. This repository does not itself establish that a registry release is available.

Installation prints a short setup guide. It does not prompt for credentials or change client settings. npm may hide lifecycle output; run echoloop setup directly if no guide appears. On Windows, use npm.cmd / echoloop.cmd if PowerShell blocks the npm-generated .ps1 launchers.

Related MCP server: Chat Human MCP Server

First setup

Run from the project you want to enable:

cd "path/to/your-project"
echoloop setup

1. Choose English or 한국어. EchoLoop remembers the CLI language.

2. Open BotFather, send /newbot, and choose a display name and a unique username ending in bot.

3. Paste the API token at the hidden-input prompt. EchoLoop checks it with Telegram.

4. Open the generated bot link and press Start within two minutes. EchoLoop discovers and saves your private chat ID; you do not need to look it up.

5. EchoLoop installs integrations for detected clients, turns notifications ON for the current project, and displays command help. Restart those clients once.

Setup currently supports Telegram only. Discord onboarding and platform selection are in the backlog.

Existing credentials and language are reused on subsequent setup runs. Run setup again after installing another supported client or moving the package. Environment variables TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID can migrate an existing configuration on the first setup; saved credentials take precedence for CLI integrations.

Commands and everyday use

These are terminal commands, not messages you must prepend to every AI request.

Use it in another project without copying any files:

cd "path/to/another-project"
echoloop on
echoloop status
# Work normally in Codex or Claude Code.
echoloop off

Subfolders inherit the nearest configured parent. An explicit OFF on a subfolder overrides its parent's ON. Projects without a matching setting are OFF. ON/OFF applies to subsequent hook invocations; it does not cancel a question already waiting for a reply.

Important: reply to the notification to continue working

1. Find the Telegram result notification for the session you want to continue.

2. Press and hold that message, then select Reply.

3. Type and send your next instruction, such as Run the tests too and report the results.

Your instruction goes to the same AI session linked to that notification. No /echoloop prefix is needed. Even when notifications from several sessions share one chat, the original message identifies the destination, so always reply to the intended notification.

For a selection question, reply with an option number, comma-separated numbers for multiple choices, or a free-text instruction. An unanswered or expired question never counts as approval.

Client support and limits

Codex must support codex queue; setup checks availability. Codex's MCP instructions request remote questions when enabled, but do not intercept every native client dialog. Claude Code must support exec-form hooks and asyncRewake. Keep its interactive session open; noninteractive claude -p is not supported for this completion/reply loop. Completion replies wait up to about 24 hours; selection and permission hooks wait up to nine minutes, then fall back to local interaction.

Keep the computer awake and connected. EchoLoop does not install an OS boot service. Use one computer and one OS user per bot; another bot program or computer polling the same token can conflict. An existing Telegram webhook must be removed before pairing. Text replies are supported; Telegram messages longer than 4,096 characters are truncated.

Process structure

flowchart LR
    A[Codex completion] --> B[Notify hook]
    B --> T[Telegram bot]
    T --> R[Shared receiver]
    R --> Q[Codex queue: original task]
    C[Claude completion or question] --> H[Claude hook waiting for reply]
    H <--> T
    H --> C
    M[MCP ask / choose] <--> T

Telegram polling state is shared across local processes using a file lock. Original message IDs select the destination session. Codex replies stay in a persistent inbox until queue submission succeeds. Queue submission and local acknowledgement are separate operations, so a crash between them can cause duplicate delivery.

Settings and troubleshooting

Settings are stored in the OS user's home directory: %USERPROFILE%/.echoloop/config.json on Windows, ~/.echoloop/config.json on macOS/Linux. This includes the language, bot token, chat ID, and project ON/OFF map. Credentials are stored locally, not encrypted. POSIX installations create the settings directory/file with permissions 700/600.

Setup updates Codex's ~/.codex/config.toml (or CODEX_HOME) and Claude's ~/.claude/settings.json (or CLAUDE_CONFIG_DIR). It preserves other settings, chains the previous Codex notify command, and registers EchoLoop's Codex MCP server if that name is unused. Existing custom MCP registrations are retained; adjust their paths yourself if necessary.

• No chat ID: open the link from the current setup run and press Start, rather than sending a greeting. After timeout, rerun setup.

• No notification: check echoloop status in the actual project folder, client availability on PATH, and restart the client after setup.

• No supported client found: install Codex or Claude Code and rerun setup; the saved Telegram pairing is retained.

• Codex reply not delivered: inspect ~/.echoloop/codex-replies/status.json; recent send metadata is in ~/.echoloop/codex-notify/last-sent.json.

• Reconfigure the bot: stop connected clients/receivers, remove only the telegram entry from the settings JSON, then rerun setup. Keep project and language settings.

MCP and manual transports

Standalone MCP clients can launch echoloop-mcp over stdio. It reads saved Telegram credentials when channel environment variables are absent. Manual configuration supports TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID, ECHOLOOP_TIMEOUT, and ECHOLOOP_CHANNEL (telegram or discord). Existing Discord transports use DISCORD_BOT_TOKEN plus DISCORD_CHANNEL_ID, or DISCORD_WEBHOOK_URL for sending only. Discord does not yet route replies to multiple sessions.

Development and license

npm ci
npm test
npm pack --dry-run

Tests mock Telegram and launch real child processes to check pairing, settings, session routing, concurrent replies, timeouts, and client hooks. CI is configured for Windows/macOS/Linux with Node.js 20 and 22. A passing local test run does not establish live client compatibility on all three systems.

Released under Apache License 2.0.