agentsync (remote)

agentsync-remote

xylem スタックの一部です。

Cloudflare Worker の MCP サーバーです。スマートフォンの claude.aiを agentsync の連携メッシュに参加させます — ローカルの agentsync と同じ claims.json、同じ agentsync ブランチ、同じ競合判定と 比較交換ルールを使用し、git もローカルクローンも必要ありません。

ノートパソコン上の Claude Code（ローカルの agentsync）と、スマートフォン上の claude.ai （agentsync-remote）は、共有された1つの claims.json に対して作業を申告します。 2つのトランスポートで、1つのメッシュです。ローカルピアとこのリモートピアは、エージェント ID を除き、 claims.json 上では区別できません。

フォークではなく、兄弟プロジェクトです。 ローカルの agentsync と同じ連携ファイルを使う、2つ目のトランスポートです — その派生版ではありません。 git push による CAS が GitHub Contents API による CAS になる仕組みについては、DESIGN.md をご覧ください。

利用できる機能

Streamable HTTP MCP 経由で7つのツールを提供します。

ツール	機能
survey	ボード全体を表示します。すべてのピアの申告、自分の競合、メールボックスを確認できます。
claim	作業を申告します。有効なピアと重複する場合はブロックされます（CAS セーフ）。
check_conflicts	必要に応じてブランチを指定し、自分の申告とピアとの競合を再確認します。
update_status	自分の申告を planning / in-progress / done に変更します。
release	自分の申告を完了にします（完了した申告がピアをブロックすることはありません）。
history	連携ブランチの最近のコミットを表示します（ローカルとリモートを交互に表示）。
mailbox	人が介在するメモ機能です。デスクトップから質問し、スマートフォンから回答できます。

自分の環境にデプロイする（ワンクリック、コマンドライン不要）

この Worker をご自身の Cloudflare アカウントにセルフホストします。すべてクリック操作で完了し、 ターミナルを使う必要はありません。

1. Cloudflare にデプロイをクリックします

上のボタンをクリックします。Cloudflare によって、次の処理が行われます。

• agentsync-remote がご自身の GitHub アカウントにフォークされます。
• Worker がご自身の Cloudflare アカウントに作成されます。
• Workers Builds が接続され、今後フォーク先にプッシュすると自動で再デプロイされます。

データベースなどのリソースをプロビジョニングする必要はありません。この Worker は独自の状態を保持せず （すべてご自身の GitHub リポジトリに保存されます）、Worker 本体をデプロイするだけです。

デプロイのダイアログに Worker の変数が表示されます。次のように設定してください。

変数	設定値
REPO	ご自身の連携リポジトリを owner/name 形式で指定します（agentsync ブランチに claims.json が保存されるリポジトリです）。変更が必要なのはこの値だけです。
AGENT_ID	jonny-mobile のままにするか、このピア用の ID を選択します。
BRANCH	別の連携ブランチを使う場合を除き、agentsync のままにします。
CLAIMS_PATH	claims.json のままにします。

デプロイを完了します。（ここで REPO の設定を省略した場合は、後からダッシュボードで設定できます。下記をご覧ください。）

2. GitHub トークンを作成し、2 つの Worker シークレットを追加する

Worker は 2 つのシークレットを読み込みます。これらはデプロイダイアログには含まれません。初回デプロイ後に、ダッシュボードで一度追加します。

まず、GitHub トークンを作成します（これが GH_PAT の値です）。

GitHub → Settings → Developer settings → Fine-grained personal access tokens → Generate new token：

• Repository access： Only select repositories → REPO に指定した調整用リポジトリのみを選択します。
• Permissions → Repository permissions → Contents： Read and write。
• それ以外は何も設定しません。トークンを生成してコピーします。

次に、Worker に両方のシークレットを追加します。

Cloudflare ダッシュボード → Workers & Pages → your Worker → Settings → Variables and Secrets → Add → Secret と入力 → それぞれ追加し、Deploy：

シークレット	値
AUTH_TOKEN	自分で作成した長いランダム文字列です。エンドポイントを保護するため、パスワードと同様に扱ってください。
GH_PAT	先ほど作成した、きめ細かく設定された GitHub トークンです。

この画面で、REPO 変数が調整用リポジトリを指していることも確認します（デプロイダイアログで設定しなかった場合は、ここで設定してください）。

AUTH_TOKEN が設定されるまでは、Worker はすべてのリクエストに 404 で応答します（フェイルクローズします）。GH_PAT が設定されるまでは、ツールは不足しているシークレット名を示す明確なエラーを返します。これは意図した動作です。未設定のエンドポイントは、存在しないように見えます。

3. claude.ai にコネクターを追加する

Worker の URL を確認します。Workers & Pages → your Worker に、https://<your-worker-name>.<your-subdomain>.workers.dev の形式で表示されています。

claude.ai（ウェブ）→ Settings → Connectors → Add custom connector。Worker の URL に /mcp/ と AUTH_TOKEN を付けて貼り付けます。

https://<your-worker-name>.<your-subdomain>.workers.dev/mcp/<AUTH_TOKEN>

パス内のトークンが認証情報です。別途ログインする必要はありません。

4. テストする

Claude に 「survey を呼び出して」 と尋ねます。調整ボードが返されます（新しいメッシュでは claims は空です。Worker がブランチとファイルを自動で作成するため、まったく新しい空のリポジトリでも手動設定は不要です）。

🔒 セキュリティ — コネクター URL は認証情報です

コネクター URL のパスには AUTH_TOKEN が含まれます （…/mcp/<AUTH_TOKEN>）。この URL を知っている人は誰でも、Worker を呼び出して調整ファイルを読み書きできます。 URL 全体をパスワードと同様に扱ってください。

• スクリーンショット、イシュー、チャット、コミットに貼り付けないでください。
• URL を知っている人はメッシュのピアになります。信頼できるエージェントや人にのみ共有してください。
• トークンをローテーションすると、古い URL は無効になります。 アクセスを取り消すには、Settings → Variables and Secrets で AUTH_TOKEN を変更して再デプロイします。古い …/mcp/<old-token> URL はすべて、直ちに 404 を返すようになります。claude.ai のコネクターも新しい URL に更新してください。

GH_PAT も同様に認証情報です。漏えいしても他のものにアクセスできないよう、対象を調整用リポジトリのみに限定し、権限も Contents の Read and write のみにしてください。

トークンを URL パスに含める理由と、その代償

これは見落としではなく、意図的な設計上の選択です。claude.ai のカスタムコネクターはカスタムヘッダーを確実に送信できないため、明白な代替手段である Authorization: ヘッダーには頼れません。認証情報をパスに含めることで、コネクターが機能します。

ヘッダーの場合とは事情が異なるため、その代償を理解しておいてください。

• URL は、リクエスト本文には記録されない場所にも記録されます。 ブラウザー履歴、シェル履歴、プロキシや CDN のアクセスログ、クラッシュレポート、バグレポート、スクリーンショット、「リンクをコピー」ボタン、そしてエージェントのセッション記録などです。このセクションの作成につながった監査では、これらの Worker のコネクター URL が、1 台のマシン上にある13 件のローカルセッション記録で約 54 か所見つかりました。意図的に貼り付けられたものはなく、エージェントがそのまま返したツール設定に含まれていただけでした。
• Worker 自体はトークンをログに記録しません。 すべてのログ行では、ルートは /mcp/*** と記録されます。漏えいの可能性があるのは Worker の周辺にあるすべてのもので、まさに監査できない部分です。
• トークンが漏えいすると、その保有者はメッシュ内で完全な対等者になります。 追加認証も呼び出し元ごとの識別情報もないまま、クレームの取得、あなたのクレームの強制取得、あなたのクレームの解放、メールボックスへの投稿が可能になります。無効化できるのはトークンだけで、誰が使用したかを知らせるログもありません。

実践的なガイダンス：

1. 疑わしいときだけでなく、定期的にローテーションしてください。 管理できない場所に URL が記録されていると想定してください。ローテーションは簡単です。AUTH_TOKEN を変更し、コネクターを更新します。
2. コネクターが設定されたマシンから、ターミナルの録画、セッション記録、画面キャプチャ、バグレポートを共有した場合は、直ちにローテーションしてください。
3. 長くランダムなトークン（32 バイト以上。例：openssl rand -hex 32）を使用してください。比較は内容と長さの両方で定数時間で行われるため、長さは観測できません。ただし、推測に対する防御手段は依然としてエントロピーだけです。
4. ヘッダーや OAuth を使える機会があれば、必ず利用してください。このトレードオフはクライアントの制約によるもので、望ましい選択ではありません。

トランスポートをまたぐウォークスルー — 2 つのトランスポート、1 つのメッシュ

これがすべてです。ノート PC とスマートフォンは、1 つのファイルを介して連携します。

PC 上（ローカルの agentsync、Claude Code）：

> agentsync claim --task "refactor auth" --touches src/auth --branch feature/auth
{"status": "claimed", ...}          # writes claims["laptop"] on the agentsync branch

スマートフォン上（claude.ai + agentsync-remote）：

You: call survey
Claude: laptop is active — task "refactor auth", touches src/auth, branch feature/auth.

You: claim task "tidy auth helpers", touches src/auth/helpers.ts
Claude: blocked. Overlap with an active peer claim:
        laptop — "refactor auth" — shared_files: ["src/auth/helpers.ts"]
        Narrow `touches`, wait, or re-call with force=true.

You: mailbox "Taking src/auth/helpers.ts once you land the refactor — ok?" to "laptop"
Claude: posted.

PC に戻り、デスクトップエージェント（またはあなた）が survey / mailbox でメモを読み、返信して、解放します。

> agentsync mailbox "go for it, helpers are stable now"
> agentsync release --note "refactor landed"
{"status": "released"}              # laptop's claim -> status "done"

⚠️ 既知の制約：メールボックスは現在、階層をまたいで書き込み専用です

上記の「PC に戻り」の手順は、まだ機能しません。 この Worker の mailbox() は claims.json にトップレベルの notes[] 配列を書き込みますが、 ローカルの Python 製 agentsync サーバーには notes の概念がありません。mailbox ツールを公開しておらず、 survey() が返すのも me、branch、partners、 stale_claims のみです。スマートフォンから投稿されたメモはファイルには正しく書き込まれますが、 デスクトップのピアには一切表示されません。

リポジトリレベルのエージェント指示では、判断を要する事柄を このメールボックス経由で伝えるようエージェントに指示しているため、これは通常の機能不足よりも重大です。 質問をひそかに飲み込む逃げ道は、逃げ道がないよりも悪いものです。エージェントは質問したと思って返事を待つか、 誰にも見られない質問への対応を続けてしまいます。

ローカル側の実装が反映されるまでは、リモートのピアからメールボックスを読み取る （message なしで mailbox を呼び出すか、survey を使う）か、 調整ブランチ上の claims.json を直接読んでください。

必要なローカル側の変更（Python の agentsync パッケージ内 — 別のリポジトリのため、意図的にここでは変更していません）：

1. notes を解析して保持する。 claims ファイルのリーダーは、トップレベルの notes キーを読み書きできる必要があります。現在は、認識されないキーが次のローカル書き込み時に削除されるおそれがあり、リモートのピアのメモが消えてしまいます。不明なトップレベルキーを保持することが、安全を確保するための最低限の変更です。まずはこれを単独で反映してください。
2. survey() でメモを表示する — partners／stale_claims と並べて notes フィールドを追加し、デフォルト値を [] にします。
3. ローカルの mailbox(message=None, to=None) ツールを追加する。このツールを参考にして、ローカルの claim 書き込みですでに使用されている同じ compare-and-swap の中で {from, to, message, at} を追記し、保持するメモを直近 200 件に制限します（この Worker は上限に達すると古いものから削除します。ファイルをめぐって両側が競合しないよう、両者で一致させてください）。

ディスク上の形式は、すでに双方向で互換性があります。この Worker は notes が空でない場合にのみ出力するため、メールボックスの利用がなければ claims.json のバイト単位の形式は、ローカルのみの出力と同じままです。

再びスマートフォン上：

You: claim task "tidy auth helpers", touches src/auth/helpers.ts
Claude: claimed.                    # laptop is "done" now, so it no longer blocks

You: (later) release note "helpers tidied"
Claude: released.

これらの手順はすべて、同じブランチ上の同じ claims.json に対する compare-and-swap でした。ノート PC がリモートピアを見ることはなく、スマートフォンが Git リポジトリを見ることもありません。それでも、同じメッシュです。

設定

シークレットではない設定は wrangler.toml にあります。すべての変数にはデフォルト値が設定されているため、編集しなくても Deploy ボタンを使用できます。REPO を自分のリポジトリに変更してください。

変数	デフォルト	意味
REPO	jarmstrong158/agentsync-remote	調整リポジトリの owner/name です。
AGENT_ID	jonny-mobile	claims.json 内でのこのピアの ID です。
BRANCH	agentsync	調整ブランチです。
CLAIMS_PATH	claims.json	調整ファイルです。

2 つのシークレットはダッシュボードで設定し、リポジトリには決して保存しません。AUTH_TOKEN（エンドポイントをロックします）と GH_PAT（調整リポジトリに対する GitHub Contents の読み取り／書き込み権限）です。

ローカルの agentsync とこの Worker の REPO、BRANCH、CLAIMS_PATH を同じ値に設定すると、1 つのメッシュを共有できます。

信頼性

競合発生時の調整の正しさは、主張ではなく測定によって確認しています。詳細は docs/RELIABILITY.md をご覧ください。以下のコマンドで再現できます。

• 自動テスト 49 件中 49 件が成功。5 種類の CAS 競合シナリオと、3 種類すべての重複検出モード（完全一致・ディレクトリ包含・glob、それぞれ双方向）を対象としています。
• シミュレーションによる同時競合 1000 件（test/stress-cas.test.ts、シード値 0x5eed）：クレームの喪失 0 件、二重付与 0 件。さらに、すべての競合で実際に 409 リトライが発生しており、単純に逐次処理された実行によって数値が水増しされていません。
• フェイルクローズ認証をテスト済み：トークンの誤り、AUTH_TOKEN の未設定、/mcp 以外のパスはすべて 404 になります。GH_PAT が未設定の場合は、エラーが黙って無視されるのではなく、名前付きのエラーとして通知されます。
• MCP ハンドシェイクを強化済み：initialize はネットワーク呼び出しを行わないため、コールド状態の isolate でも即座に応答します。クライアントが少し先行したバージョンを要求しても拒否せず、要求されたプロトコルバージョンをネゴシエートします。また、予期しない例外がどこで発生しても、適切な形式の JSON-RPC エラーに変換されます。再接続中のクライアントが致命的な失敗と判断するような、単なる 500 を返すことはありません。
• 構造化ログで失敗を可視化：リクエストごとに JSON を 1 行出力します（request／auth／handshake／tool_call／error。パスのトークンは常にマスクされます）。ハンドシェイクの失敗やツール呼び出しの遅延も、Cloudflare Workers Logs（wrangler.toml で [observability] が有効）で絞り込むだけですぐに確認できます。

正直に記しておく点： 1000 件の競合は プロセス内 でシミュレーションしています。GitHub の 409 compare-and-swap は、fetch をモックした偽物（test/helpers.ts）で再現しており、実際の API には接続していません。この結果が検証するのは、本番環境で実行される Worker の調整 ロジック であり、GitHub の API、ネットワーク、実環境でのレイテンシーではありません。

メンテナー／ローカル開発

正規リポジトリ（jarmstrong158/agentsync-remote）は GitHub Actions → Wrangler（.github/workflows/deploy.yml）経由でデプロイされます。 main へのプッシュごとにテストスイートを実行し、すべて成功した場合にのみデプロイします。このワークフローは正規リポジトリに限定されているため、Deploy ボタンで作成したフォークでは実行されません。フォークは代わりに Workers Builds 経由で再デプロイされます。

ローカルでのチェック（Cloudflare の認証情報は不要）：

npm install
npm test          # vitest, fetch-mocked — no live GitHub calls
npm run typecheck
npx wrangler deploy --dry-run --outdir dist   # bundle check

関連項目

• agentsync — ローカルトランスポート（お使いのマシン上の Claude Code）。同じファイル、同じルールを使う兄弟トランスポートです。
• DESIGN.md — CAS の変換、重複の意味、および MCP ハンドラーをステートレスにして手書きで実装した理由。
• docs/RELIABILITY.md — 測定に基づく信頼性レポート：テスト 49 件中 49 件成功、5 種類の CAS 競合シナリオ、シード値を指定した競合シミュレーション 1000 件。
• Cloudflare へのデプロイボタン — 上記で使用しているワンクリックデプロイの流れに関する Cloudflare のドキュメント。

関連

• agentsync — このトランスポートが踏襲する、ローカルの git ネイティブ版のオリジナルです。また、xylem はスタックハブです。