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

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"
  "tryLocalSttFirst": false,// true = force the local transcriber even if a cloud provider is set
  "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). The configured provider is always respected — the bridge never silently falls back to local. To force the local transcriber even when a cloud provider is set, use "tryLocalSttFirst": true (or BRIDGE_STT_TRY_LOCAL_FIRST=1).
• 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.

Read receipts (acknowledgments)

Without this, sending a message from your phone is silent until the agent finishes a whole turn — you can't tell whether it arrived at all. Turn it on and the daemon replies the moment a message lands, before any slow work (attachment downloads, transcription). Off by default:

"ack": {
  "enabled": true,
  "language": "auto",                     // "auto" matches you; force with "en" or "he"
  "adapters": ["discord", "telegram"],    // bot-identity channels only (see below)
  "echoTranscript": true,                 // repeat back what a voice note said
  "maxTranscriptChars": 200
}

What you get, per message kind:

The ack comes from the daemon, not the agent — the agent doesn't even see your message until its next turn begins, so an agent-authored ack would cost an LLM turn and arrive late.

On "auto" the reply matches the language you wrote in: Hebrew text gets a Hebrew reply, and for a voice note the transcriber's own detected language decides. Messages with nothing to go on (an uncaptioned image, a bare stop) reuse the last language you used in that session, defaulting to English.

Timing: the daemon only reads the channel while a poll is in flight — that is, while the agent is awaiting a reply or the stop hook is waiting. Messages sent while the agent is mid-turn aren't seen (and so aren't acked) until it finishes. They're never lost, just delayed.

Why not GitHub: there the agent comments under your own account, so an ack would read as you replying to yourself. You can still opt in by adding "github" to adapters.

Configuration

~/.cursor/chat-bridge/config.json (edits to this file are picked up automatically on the next poll — no daemon restart needed; only mcp.json env changes and adapter credentials need a restart):

{
  "activeAdapter": "telegram",
  "pollIntervalMs": 10000,   // check for replies every N ms (lower = snappier, more API calls)
  "minPollIntervalMs": 2000, // floor for the above; lower it if you set pollIntervalMs < 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,
  "stopRemoteChatOnLocalMessage": true, // typing in Cursor turns remote mode off (set false to keep it on)
  "adapters": {
    "github": {
      "owner": "you",
      "repo": "cursor-bridge-inbox",
      "tokenCommand": "gh auth token --user you"
    },
    "discord":  { "botToken": "", "channelId": "", "allowedUserIds": [] },
    "telegram": { "botToken": "", "chatId": "", "allowedUserIds": [] }
  },
  "ack": { "enabled": false, "language": "auto" } // read receipts; see above
}

caCertPath is usually empty — leave it unless things fail. Some corporate networks intercept HTTPS with their own root cert that Node doesn't trust, so requests fail with TypeError: fetch failed while curl works. If you hit that, point caCertPath (or BRIDGE_CA_CERT) at your machine's CA bundle (PEM); doctor, the daemon, and the update check all honor it.

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. ³ Any existing text channel in your server; used to locate the server + category — a fresh channel is created per session alongside it (For example #General).}

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.

Permissions — what the daemon needs (and why scanners flag it)

Driving an agent from a chat app inherently needs some powerful capabilities. This package uses:

• Child processes — to spawn the daemon, run your tokenCommand (e.g. gh auth token), the local whisper binary (only if you choose local STT), and npm install inside the installer.
• Network access — a loopback-only control server plus outbound calls to your chosen channel (Telegram/Discord/GitHub), speech-to-text upload (if enabled), and an npm update check.
• Filesystem access — read/write ~/.cursor/chat-bridge/ for config, media, and logs.

Because of these, supply-chain scanners (Socket, Snyk, etc.) show a lower Supply Chain Security score than a pure-logic library — even though there are no known vulnerabilities. That score reflects capability + package age (this project is new, single-maintainer), not a detected exploit. For transparency: there is no postinstall/install script — the only lifecycle script is prepublishOnly (a build that runs on the publisher's machine, never on your install). Everything network/filesystem/process happens only when you run the daemon, and the control API is loopback-only and token-guarded. The source is MIT and auditable in this repo.

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