MCP tools

bridge_start, bridge_send, bridge_await, bridge_send_and_await, bridge_stop, bridge_status.

Channels at a glance

MIT licensed. See the repository README for full configuration, per-platform setup, the wait loop, ntfy push, and how to write a new adapter.

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

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.

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": [] }
  }
}

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