cursor-chat-bridge

🌉 cursor-chat-bridge _{^{（Telegram、Discord、GitHub）}}

スマートフォンから Telegram、Discord、または GitHub 経由で Cursor エージェントを操作できます。

（どの言語でも）「リモートチャットモードを開始して」と伝えると、Cursor は各ターンの終了時に会話ごとのスレッドへ要約と質問を投稿し、返信を待ってから自動で続行します。停止するまでこれを繰り返します。キーボードから離れても、スマートフォンから開発を続けられます。

セッションごとのチャンネル — Cursor の会話ごとに1つ

スマートフォンから返信 — エージェントは中断したところから再開します

_{▶ デモを見る（YouTube）}

目次

• 概要
• 機能
• チャンネルの概要
• クイックスタート
• 仕組み
• 画像添付
• 音声メッセージ（音声からテキストへの変換）
• 既読通知（確認応答）
• 設定
• 環境変数による上書き
• 待機ループ
• プッシュ通知（ntfy）
• プラットフォームごとのセットアップ
• 新しいアダプターの作成
• セキュリティ
• 検証状況
• コントリビューション
• ライセンス

理由

Cursor でタスクを開始したあと、席を離れる必要が出てきます。通常、エージェントは判断が必要になると、その時点で作業を止めてしまいます。cursor-chat-bridge は、あらゆるチャットアプリをリモート操作用に変えます。エージェントはスレッドで状況を報告し、質問を投げかけます。スマートフォンから返信すれば、ノートパソコンが手元になくても、返信した瞬間にエージェントが自動で作業を再開します。

• 会話ごとにスレッドを作成。 Cursor のチャットごとに専用の issue／チャンネル／トピックが割り当てられます。同じワークスペース内の複数のチャットも、それぞれ分離されます。
• ハンズフリーのループ。 返信は自動で再投入されるため、作業を続けるために Cursor を操作する必要はありません。
• チャンネルを追加可能。 現在は Telegram、Discord、GitHub Issues に対応しており、約 100 行で独自のチャンネルを追加できます。
• デフォルトで安全。 リモートからの返信は信頼できないものとして扱われ、破壊的な操作にはスレッド経由で明示的な確認を返す必要があります。
• プロキシに対応。 GitHub と Discord は、TLS インターセプトを行う企業プロキシ経由で接続できます。

機能

チャンネル一覧

クイックスタート

クローンは不要です。1 つのコマンドですべてを設定できます。

npx cursor-telegram-chat@latest install

ランタイムを ~/.cursor/chat-bridge/app にインストールし（本番用の依存関係も含まれるため、npx のキャッシュが削除されたあとも動作します）、3 つの連携ポイントを設定します。すでに存在するものはバックアップし、決して上書きしません。

• MCP サーバーを ~/.cursor/mcp.json に登録します。
• stop と beforeSubmitPrompt フックを ~/.cursor/hooks.json に追加します。
• 有効化ルールを ~/.cursor/rules/ にインストールします。

フックはリモートチャットモードが有効なとき以外は何もしないため、通常の Cursor の使用には影響しません。次に、チャンネルを選んで開始します。

# 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"]
}

トランスポートに依存しないコアの上に、連携する3つのレイヤーがあります。

• ルール（rules/chat-bridge-mode.mdc）— どの言語でも起動フレーズを検出し、モード中のエチケットを設定します（セッションハンドルを取得して渡す、各ターンの最後に要約と質問を添える、返信を信頼できないものとして扱う、破壊的な操作は確認する）。
• MCP サーバー（src/mcp.ts）— bridge_start、bridge_send、bridge_await、 bridge_send_and_await、bridge_stop、bridge_statusを公開します。
• フック（hooks/）— 自動ループを構成します。
  • stopはリモートからの返信を待ち、followup_messageとして再注入します（loop_limitで上限を設定）。
  • beforeSubmitPromptはCursorで入力したときにループを無効にします（ループ自身が注入した返信では無効にならないようガードします）。

単一のローカルデーモン（src/daemon.ts）が、チャネル接続と、MCPおよびフックが使用するループバック専用のトークン認証付きHTTP APIを管理します。セッションごとのルーティング、ロングポーリング、自分自身が送信したメッセージのフィルタリング、停止／生成ロジックを処理します。

turn ends ─▶ stop hook ─▶ daemon /poll ─▶ adapter
   ▲                                          │
   └───── followup_message (your reply) ◀─────┘

（アダプターはGitHub／Discord／Telegram。conversation_idをキーとして使用します。）

チャットスレッドに写真（または画像ファイル）を送信すると、エージェントが画像を確認できます。

1. アダプターがメッセージの添付ファイル（Discord の attachments、Telegram の photo／画像の document）を取得します。
2. デーモンがバイトデータを ~/.cursor/chat-bridge/media/<session>/ にダウンロードし、ローカルパスを記載したメモをメッセージ本文に追加します。
3. エージェントが Read ツールでそのパスを開くため、画像はビジョン入力としてモデルに渡されます。

企業の TLS プロキシ経由の場合： Discord の cdn.discordapp.com はブロックされ、media.discordapp.net は許可されていることがよくあります。Discord アダプターは添付ファイルの URL を自動的に media ホストに書き換えるため、このようなネットワークでもダウンロードできます。

音声メッセージ（音声テキスト変換）

ボイスメモ（Telegram）または音声添付ファイル（Discord）を送信すると、入力したテキストと同じようにエージェントに文字起こしが届きます。デフォルトでは無効です。 設定の stt で有効にします。

"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 プロバイダー（オフライン。機密性の高い音声におすすめ）：文字起こしを stdout に出力する CLI を localBin／localArgs に設定します（例：whisper.cpp）。設定された provider は常に優先されます。ブリッジが暗黙に local へフォールバックすることはありません。クラウドプロバイダーが設定されている場合でもローカルの文字起こしを強制するには、"tryLocalSttFirst": true（または BRIDGE_STT_TRY_LOCAL_FIRST=1）を使用します。
• 文字起こしはデーモン内で非同期に実行されるため、ポーリングウィンドウをブロックしません。文字起こし結果は次の返信サイクルで送信されます。設計の詳細は docs/stt-plan.md を参照してください。

既読通知（確認応答）

この機能がない場合、スマートフォンからメッセージを送信しても、エージェントが一連の処理を完了するまで何も応答がなく、メッセージが届いたかどうかもわかりません。有効にすると、メッセージが届いた時点で、時間のかかる処理（添付ファイルのダウンロードや文字起こし）を始める前にデーモンが返信します。デフォルトでは無効です。

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

メッセージの種類ごとの応答は次のとおりです。

確認応答はエージェントではなくデーモンから送信されます。エージェントがメッセージを見るのは次のターンが始まってからなので、エージェントが確認応答を作成すると LLM のターンを消費し、返信も遅れます。

"auto" に設定すると、返信は入力した言語に合わせられます。ヘブライ語のテキストにはヘブライ語で返信し、ボイスメモの場合は文字起こしサービスが検出した言語に従います。判断材料のないメッセージ（キャプションのない画像や、単独の stop）には、そのセッションで最後に使用した言語が使われます。初期設定は英語です。

タイミング： デーモンがチャネルを読み取るのは、ポーリングが実行中の場合のみです。つまり、エージェントが返信を待っている間、または stop フックが待機している間です。エージェントがターンの途中に送信されたメッセージは、エージェントが処理を終えるまで確認されず、確認応答も送られません。メッセージが失われることはありませんが、遅れて処理されます。

GitHub を対象外とする理由： GitHub ではエージェントがあなた自身のアカウントでコメントするため、確認応答を送ると自分自身に返信したように見えてしまいます。それでも利用したい場合は、adapters に "github" を追加してください。

設定

~/.cursor/chat-bridge/config.json（このファイルの変更は次回のポーリング時に自動的に反映されるため、デーモンの再起動は不要です。再起動が必要なのは mcp.json の環境変数の変更とアダプターの認証情報のみです）：

{
  "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 は空のままで構いません。問題が起きない限り変更しないでください。一部の企業ネットワークでは、Node が信頼していない独自のルート証明書を使って HTTPS を傍受するため、curl は動作するのに TypeError: fetch failed が発生してリクエストが失敗します。その場合は、caCertPath（または BRIDGE_CA_CERT）にマシンの CA バンドル（PEM）を指定してください。doctor、デーモン、更新チェックはいずれもこの設定を使用します。

ntfy プッシュ通知はデフォルトでは無効で、このファイルでは設定できません。有効にするには BRIDGE_NTFY_* 環境変数のみを使用してください（下記を参照）。

環境変数による上書き

config.json を編集せずに上書きするには、~/.cursor/mcp.json の cursor-chat-bridge エントリーにある env ブロック（またはシェル）で設定します。すべての名前空間付き変数は BRIDGE_* です。実行中のデーモンに変更を反映するには、デーモンを再起動する必要があります（chat-bridge shutdown）。

_{¹ config.json の stopBudgetMin も設定できます。フックは MCP エントリーの環境変数を引き継がないため、こちらが確実な設定方法です。 ² config.json の stopWindowMin も設定できます。~/.cursor/hooks.json の stop フックの timeout より短くしてください。 ³ サーバー内に既存のテキストチャンネルがあれば使用できます。サーバーとカテゴリの特定に使われ、セッションごとにその横に新しいチャンネルが作成されます（例：#General）。}

会話ごとに使用するプラットフォームを実行時に選ぶこともできます。「Telegram でリモートチャットを開始」と伝えると、エージェントはその会話に限り bridge_start(adapter: "telegram") を渡します。

待機ループ（stop フック）

リモートモードが有効な間、各ターンの終了時に stop フックがブロックし、返信を待ちます。これを制御する設定は 2 つあります。

• stopWindowMin（デフォルトは 60）— 1 回のフック呼び出しがブロックする時間です。時間が経過すると、サイレントなキープアライブを返して再度待機を開始します。Cursor は ~/.cursor/hooks.json の timeout（デフォルトは 3660s / 61 min）で stop フックの実行時間を制限します。検証したところ、それより短い隠れた上限は確認されませんでした。そのため、約 60 分のウィンドウを 1 回設定すれば、離席中の有料キープアライブターンは1 時間に 1 回だけになります。
• stopBudgetMin（デフォルトは 60）— 再待機を繰り返す際の合計待機時間です。返信のたびにリセットされるため、実際には「最後のメッセージから最大 N 分間待機する」という設定です。

返信する、Cursor に入力する、スレッドで stop を送信する、または bridge_stop を呼び出すと、ループは終了します。

プッシュ通知（ntfy）

GitHub は、自分自身のアクティビティについては通知しません。エージェントはあなたとして投稿するため、自分自身へのメンションや自分自身のアサインでも通知されません。そこで、2 つ目のアカウントを使わずに GitHub チャンネルの通知をスマートフォンで受け取れるよう、cursor-chat-bridge は各サマリーの送信時に ntfy 経由で別経路のプッシュ通知を送信できます。無料で、アカウント不要、オープンソース、セルフホスト可能で、課題へのディープリンクにも対応しています。

デフォルトでは無効です。MCP エントリの環境変数で有効にします。

1. ntfy アプリ（iOS／Android）をインストールするか、ウェブアプリを使用します。
2. 長く推測されにくいトピック（トピックは推測されにくいことを前提に公開されています）を選び、購読します。
3. ~/.cursor/mcp.json の cursor-chat-bridge エントリにある env ブロックに、BRIDGE_NTFY_TOPIC=cursor-bridge-<random> を設定します。

BRIDGE_NTFY_PRIORITY は有効／無効を切り替える設定です。0 = オフ（デフォルト）、1 が最低、5 が最高です。プッシュ通知は、優先度が 1 以上かつトピックが設定されている場合にのみ送信されます。ネイティブ通知に対応しているTelegramとDiscordでは、プッシュ通知はスキップされます。

プラットフォーム別のセットアップ

新しいアダプターの作成

TransportAdapter（src/types.ts）を実装し、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>;
}

セキュリティ

• ループバック制御 API はトークン認証されています — トークンを持つローカルプロセス（MCP およびフック）のみがデーモンを操作できます。
• 受信メッセージは、allowedUserIds の許可リストでフィルタリングされます（Telegram／Discord）。
• リモートからの返信はすべてラップされ、信頼できないものとしてマークされます。スレッドへの明示的な確認の返信がない限り、破壊的な操作を行わないようルールで定められています。
• トークンは ~/.cursor/chat-bridge/config.json（chmod 600）に保存され、コミットされることはありません。可能であれば、保存済みトークンより tokenCommand を優先してください。

権限 — デーモンが必要とする権限と、スキャナーが警告を出す理由

チャットアプリからエージェントを操作するには、本質的に強力な機能が必要です。このパッケージでは、以下を使用します。

• 子プロセス — デーモンの起動、tokenCommand（例：gh auth token）の実行、ローカルの whisper バイナリ（ローカル STT を選択した場合のみ）の実行、およびインストーラー内での npm install の実行に使用します。
• ネットワークアクセス — ループバック限定の制御サーバー、および選択したチャネル（Telegram／Discord／GitHub）への外部呼び出し、音声テキスト変換のアップロード（有効にした場合）、npm の更新確認に使用します。
• ファイルシステムアクセス — 設定、メディア、ログのために ~/.cursor/chat-bridge/ を読み書きします。

このため、サプライチェーンスキャナー（Socket、Snyk など）では、純粋なロジックライブラリよりも サプライチェーンセキュリティ のスコアが低く表示されます。ただし、これは既知の脆弱性がないにもかかわらずです。このスコアが反映しているのは、検出されたエクスプロイトではなく、機能とパッケージの公開期間（このプロジェクトは新しく、メンテナーは 1 人です）です。透明性のために説明すると、postinstall／install スクリプトはありません。唯一のライフサイクルスクリプトは prepublishOnly（公開者のマシン上で実行されるビルドで、インストール時には実行されません）です。ネットワーク／ファイルシステム／プロセスに関する処理は、ご自身がデーモンを実行したときにのみ行われます。また、制御 API はループバック限定で、トークンによって保護されています。ソースは MIT ライセンスで、このリポジトリで監査できます。

検証状況

マシン上でエンドツーエンドの検証済みです（Cursor の再起動は不要です）。

• GitHub アダプター — イシューの作成、送信、ポーリング、自分のメッセージのフィルタリング、stop キーワード、クローズ検出。
• デーモン — トークン認証、ロングポーリング、停止／世代管理、永続化。
• MCP サーバー — 実際の stdio JSON-RPC ハンドシェイクを介したすべてのツール。
• フック — stop-loop の followup_message 注入、送信前のオフスイッチと注入ガード、非アクティブ時の即時 no-op。
• 会話ごとのルーティング（node scripts/e2e-conv.mjs）— 別々の会話で別々のイシューを開きます。同じワークスペース内の 2 つの会話も個別に保たれます。停止したセッションを再アクティブ化すると新しいスレッドが開きます。未設定のチャネルにはオンボーディングの案内が返されます。
• ユニットテスト — npm test（ルーティング、ストアのセマンティクス、メッセージのフィルタリング）。

コントリビューション

イシューや PR を歓迎します。ローカルでの開発方法：

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

新しいチャネルの追加は、最も簡単なコントリビューションです。TransportAdapter を 1 つ実装してください（上記を参照）。

ライセンス

MIT