🌉 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.

npm version npm downloads node TypeScript license PRs welcome Made for Cursor

A channel per session — one per Cursor conversation

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

Table of contents

• Why
• Features
• Channels at a glance
• Quick start
• How it works
• Image attachments
• Voice messages (speech-to-text)
• 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 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"

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

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

🛠 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.)

🖼️ 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/<session>/ and appends a note to the message text with the local path.
3. The agent opens that path with its Read tool — so the image reaches the model as vision input.

Behind a corporate TLS proxy: Discord's cdn.discordapp.com is often blocked while media.discordapp.net is allowed. The Discord adapter automatically rewrites attachment URLs to the media host, so downloads work on such networks.

🎙️ Voice messages (speech-to-text)

Send a voice note (Telegram) or an audio attachment (Discord) and the agent receives a text transcription as if you'd typed it — off by default. Enable it under stt in the config:

"stt": {
  "enabled": true,
  "provider": "openai",   // "openai" (OpenAI-compatible via baseUrl) or "local"
  "apiKeyCommand": "…",   // or "apiKey", or env BRIDGE_STT_API_KEY
  "language": "auto",     // auto-detect, or force "he" / "en"
  "keepAudio": true       // false = delete the audio after transcribing
}

• local provider (offline, recommended for sensitive audio): set localBin/localArgs to a CLI that prints the transcript to stdout (e.g. whisper.cpp). On a corporate network (caCertPath set), the default provider automatically flips to local so audio isn't sent off-host unless you explicitly choose a cloud provider.
• Transcription runs asynchronously in the daemon (never blocks the poll window); the transcript is delivered on the next reply cycle. See docs/stt-plan.md for the full design.

⚙️ Configuration

~/.cursor/chat-bridge/config.json:

{
  "activeAdapter": "telegram",
  "pollIntervalMs": 60000,   // check for replies every N ms (min 10000)
  "minPollIntervalMs": 10000,
  "stopBudgetMin": 60,       // wait budget (mins); resets on every reply
  "stopWindowMin": 60,       // mins per window (keep < hooks.json timeout)
  "caCertPath": "",          // corporate CA bundle (PEM) if behind a TLS proxy
  "requireConfirmForDestructive": true,
  "adapters": {
    "github": {
      "owner": "you",
      "repo": "cursor-bridge-inbox",
      "tokenCommand": "gh auth token --user you"
    },
    "discord":  { "botToken": "", "channelId": "", "allowedUserIds": [] },
    "telegram": { "botToken": "", "chatId": "", "allowedUserIds": [] }
  }
}

caCertPath is usually empty. Set it if Node's fetch fails with TypeError: fetch failed while curl works — a tell-tale sign a corporate proxy is intercepting TLS for discord.com / api.github.com.

ntfy push is off by default and isn't part of this file — enable it only via BRIDGE_NTFY_* env vars (see below).

🔧 Environment overrides

Set these in the env block of the cursor-chat-bridge entry in ~/.cursor/mcp.json (or the shell) to override config.json without editing it. All namespaced BRIDGE_*. A change needs a daemon restart (chat-bridge shutdown) to affect a running daemon.

_{¹ Also stopBudgetMin in config.json — the reliable knob, since the hook doesn't inherit the MCP entry's env. ² Also stopWindowMin in config.json. Keep below the stop hook timeout in ~/.cursor/hooks.json. ³ Used only to find the server + category; a fresh channel is created per session.}

Per-conversation platform can also be chosen at runtime: say "start remote chat in Telegram" and the agent passes bridge_start(adapter: "telegram") for that conversation only.

⏱️ The wait loop (stop hook)

While remote mode is active, the stop hook blocks at the end of each turn waiting for your reply. Two knobs control it:

• stopWindowMin (default 60) — how long a single hook invocation blocks before it returns a silent keep-alive and re-arms. Cursor caps stop-hook runtime at the timeout in ~/.cursor/hooks.json (default 3660s / 61 min); probing showed no hidden cap below that, so one ~60-min window means just one paid keep-alive turn per hour while you're away.
• stopBudgetMin (default 60) — the total time to keep waiting across re-arms. It resets on every reply, so it's really "keep waiting up to N minutes since your last message."

The loop ends when you reply, type in Cursor, send stop in the thread, or call bridge_stop.

🔔 Push notifications (ntfy)

GitHub never notifies you about your own activity — and the agent posts as you (self-mentions and self-assignment don't notify either). So to get a phone alert on the GitHub channel without a second account, cursor-chat-bridge can fire an out-of-band push via ntfy on every summary. It's free, account-less, open-source, self-hostable, and deep-links to the issue.

It's off by default. Enable it via env on the MCP entry:

1. Install the ntfy app (iOS/Android) or use the web app.
2. Pick a long, unguessable topic (topics are public-by-obscurity) and subscribe to it.
3. Set BRIDGE_NTFY_TOPIC=cursor-bridge-<random> in the env block of the cursor-chat-bridge entry in ~/.cursor/mcp.json.

BRIDGE_NTFY_PRIORITY is the on/off dial: 0 = off (default), 1=min … 5=max. A push is sent only when priority ≥ 1 and a topic is set. Pushes are skipped for Telegram and Discord, which already notify natively.

📇 Per-platform setup

🧩 Writing a new adapter

Implement TransportAdapter (src/types.ts) and register it in src/adapters/index.ts:

interface TransportAdapter {
  capabilities: { globalIngest: boolean; separateBotIdentity: boolean };
  init(): Promise<void>;
  ensureThread(sessionId: string, title: string, meta?: object): Promise<ThreadRef>;
  send(thread: ThreadRef, text: string): Promise<{ messageId: string }>;
  // pull adapters (GitHub / Discord):
  poll?(thread: ThreadRef, cursor?: string): Promise<PollResult>;
  // push / global adapters (Telegram):
  startIngest?(router: Router): Promise<() => void>;
  stop?(thread: ThreadRef): Promise<void>;
}

🔐 Security

• The loopback control API is token-authenticated — only local processes with the token (the MCP + hooks) can drive the daemon.
• Inbound messages are filtered by an allowedUserIds whitelist (Telegram/Discord).
• Every remote reply is wrapped and marked untrusted; the rule forbids destructive actions without an explicit confirmation sent back through the thread.
• Tokens live in ~/.cursor/chat-bridge/config.json (chmod 600) and are never committed. Prefer tokenCommand over a stored token where possible.

✅ Verification status

Verified end-to-end on-machine (no Cursor restart needed):

• GitHub adapter — create issue, send, poll, own-message filtering, stop keyword, close-detection.
• Daemon — token auth, long-poll, stop/generation, persistence.
• MCP server — all tools over a real stdio JSON-RPC handshake.
• Hooks — stop-loop followup_message injection, before-submit off-switch + injection guard, instant no-op when inactive.
• Per-conversation routing (node scripts/e2e-conv.mjs) — distinct conversations open distinct issues; two conversations in the same workspace stay separate; re-activating a stopped session opens a fresh thread; unconfigured channels return onboarding guidance.
• Unit tests — npm test (routing, store semantics, message filtering).

🤝 Contributing

Issues and PRs welcome. Local dev:

npm install
npm run build        # tsc → dist/
npm run typecheck
npm test             # node --test
npm run dev:daemon   # run the daemon from source (tsx)

New channels are the easiest contribution — implement one TransportAdapter (see above).

📄 License

MIT