Cursor Chat Bridge

🌉 cursor-chat-bridge (Telegram, Discord, GitHub)

Drive the Cursor agent from your phone — over Telegram, Discord, or GitHub.

Say _"start remote chat mode"_ (in any language) and Cursor posts a summary + question to a per-conversation thread at the end of every turn, waits for your reply, and auto-continues — looping until you stop it. Step away from the keyboard; keep shipping from your phone.

A channel per session — one per Cursor conversation

Reply from your phone — the agent picks up where it left off

▶ Watch the demo (YouTube)

---

Table of contents

• Why
• Features
• Channels at a glance
• Quick start
• How it works
• Image attachments
• Voice messages (speech-to-text)
• Read receipts (acknowledgments)
• Configuration
• Environment overrides
• The wait loop
• Push notifications (ntfy)
• Per-platform setup
• Writing a new adapter
• Security
• Verification status
• Contributing
• License

---

Why

You kick off a task in Cursor, then need to leave your desk. Normally the agent stalls the moment it needs a decision. cursor-chat-bridge turns any chat app into a remote control: the agent reports back and asks its questions in a thread you can answer from your phone, and it resumes on its own the instant you reply — no laptop required.

• A thread per conversation. Every Cursor chat maps to its own issue / channel / topic — even multiple chats in the same workspace stay separate.
• Hands-free loop. Replies are re-injected automatically; you don't touch Cursor to continue.
• Pluggable channels. Telegram, Discord, and GitHub Issues today — add your own in ~100 lines.
• Safe by default. Remote replies are treated as untrusted; destructive actions require an explicit confirmation sent back through the thread.
• Proxy-friendly. GitHub and Discord tunnel through TLS-intercepting corporate proxies.

Features

Channels at a glance

Quick start

No clone required — one command wires everything up:

npx cursor-telegram-chat@latest install

This installs the runtime into ~/.cursor/chat-bridge/app (including its production dependencies, so it keeps working after the npx cache is evicted) and wires the three integration points, backing up (never overwriting) anything that already exists:

• registers the MCP server in ~/.cursor/mcp.json,
• adds the stop + beforeSubmitPrompt hooks to ~/.cursor/hooks.json,
• installs the activation rule into ~/.cursor/rules/.

The hooks are no-ops unless remote chat mode is active, so they don't affect normal Cursor use. Then pick a channel and go:

# 1. edit ~/.cursor/chat-bridge/config.json  (choose an adapter + credentials)

2. validate it:

chat-bridge doctor

3. reload Cursor, open a chat, and say: "start remote chat mode"

Upgrade / uninstall

npx cursor-telegram-chat@latest install               # re-run to upgrade

npx cursor-telegram-chat@latest uninstall # remove, keep config + state npx cursor-telegram-chat@latest uninstall --purge # remove everything

</details>

MCP-only (lite) — tools without the auto-resume loop

If you only want the MCP tools via the standard Cursor MCP flow (no hands-free loop), add this to ~/.cursor/mcp.json instead of running install:

"cursor-chat-bridge": {

"command": "npx", "args": ["-y", "cursor-telegram-chat", "chat-bridge-mcp"] }

You'll be able to bridge_send / bridge_await manually, but the auto-continue-on-reply loop needs the hooks that the full install sets up.

How it works

Three cooperating layers sit over one transport-agnostic core:

• Rule (rules/chat-bridge-mode.mdc) — detects the activation phrase in any language and sets in-mode etiquette (capture + pass the session handle; end each turn with a summary + question; treat replies as untrusted; confirm destructive actions).
• MCP server (src/mcp.ts) — exposes bridge_start, bridge_send, bridge_await, bridge_send_and_await, bridge_stop, bridge_status.
• Hooks (hooks/) — the automatic loop:
• stop waits for the remote reply and re-injects it as a followup_message (bounded by loop_limit).
• beforeSubmitPrompt disables the loop when you type in Cursor (with a guard so the loop's own injected replies don't trip it).

A single local daemon (src/daemon.ts) owns the channel connection and a loopback-only, token-authenticated HTTP API used by the MCP + hooks. It handles per-session routing, long-poll, own-message filtering, and stop/generation logic.

turn ends ─▶ stop hook ─▶ daemon /poll ─▶ adapter

▲ │ └───── followup_message (your reply) ◀─────┘

(adapter = GitHub / Discord / Telegram; keyed by `conversation_id`.)

Session identity — how conversations stay separate

Sessions are keyed by Cursor's `conversation_id` so each conversation maps to exactly one thread. Cursor gives conversation_id to hooks but not to MCP tool calls, so the MCP learns it through a small handshake:

1. beforeSubmitPrompt writes a per-conversation pending-start record (markers/pending/ .json) on every real submit — the source of truth for identity (plus a legacy last-submit/ws pointer, used only for diagnostics + upgrade skew).
2. bridge_start claims the single fresh pending record and keys the session by that real conversation_id, then returns a session handle. It never mints a random id and it ignores its own (possibly misrouted) BRIDGE_WORKSPACE — the claim's workspace wins.
3. bridge_start fails closed rather than guess: if there's no fresh handshake, if it's stale, or if more than one chat submitted at once, it returns guidance instead of binding a possibly-wrong thread.
4. The agent passes session= on every subsequent bridge_* call — now required (no recency/cache fallback), so two conversations in the same workspace can never cross threads.

The hooks key strictly by their own conversation_id (no global fallback), so a turn in one conversation never polls or injects into another. Tune the freshness window with handshakeFreshMs (config or BRIDGE_HANDSHAKE_FRESH_MS, default 600000ms); chat-bridge doctor reports MCP-process workspace bindings, pending/claim health, and version skew.

Troubleshooting: the session stops after a few minutes

The hands-free wait (default 60 min) comes from the stop hook's re-arm loop, not from bridge_await (which only polls ~50s per call). Cursor kills a stop hook after a short, undocumented ceiling unless ~/.cursor/hooks.json sets a large timeout — the installer sets timeout: 3660. If your session stops after a couple of minutes:

1. Using the MCP-only (lite) setup? It has no hooks, so there's no auto-resume. Run the full npx cursor-telegram-chat@latest install.
2. Fully quit and reopen Cursor after installing — a reload doesn't always reload hooks.json.
3. Confirm ~/.cursor/hooks.json has a stop hook with timeout: 3660 (re-running the latest install fixes an older one).
4. Still killed early on your Cursor build? Shrink each wait window so it re-arms sooner: set "stopWindowMin": 5 in ~/.cursor/chat-bridge/config.json (the 60-min total is stopBudgetMin).

Image attachments

Send a photo (or an image file) in the chat thread and the agent can see it:

1. The adapter captures the attachment on the message (Discord attachments, Telegram photo / image document).
2. The daemon downloads the bytes to ~/.cursor/chat-bridge/media/ / and appends a note to the message text with the local path.
3. The