Pushary: human-in-the-loop for AI agents

Pushary：AI エージェントのための人間参加型ワークフロー

AI エージェント向けのプッシュ通知と人間参加型ワークフロー。スマートフォンから承認できます。
今すぐ始める  ·  スキルディレクトリ  ·  バグを報告

まずはこちら

登録せずに承認を試す → 開いたスマートフォンのページに接続 → 承認または拒否 → エージェントの続行または停止を確認できます。 このブラウザデモでは、実際のプッシュ配信や本番環境の台帳ではなく、ポーリングと一時的な状態を使用します。

作りたいもの	まずはこちら
コーディングエージェント向けの通知と質問	以下のセットアップ手順
Vercel AI SDK で強制されるツール承認	実行可能な AI SDK の例
人間の判断に応じて分岐する LangGraph ワークフロー	実行可能な LangGraph の例
その他のエージェントフレームワーク	Pushary のすべての連携
エージェントが人に確認を求めて停止すべき場面と、あらゆるフレームワークにそのステップを追加する方法	pushary-human-in-the-loop スキル

このスキルとアダプターは MIT ライセンスです。ホスト型のスマートフォン配信には Pushary アカウントが必要です。独自のユーザー向けに承認機能を組み込むには、Partner アクセスが必要です。 2 つのフレームワークの例は、模擬回答を使って認証情報なしでローカル実行することもできます。

Pushary が役に立ったら、このリポジトリにスターを付けてください。 協力したい方は、公開イシューやパッチを歓迎します。

---

Pushary を使うと、コーディングエージェントからスマートフォンにタスクの進捗を送信し、判断を求めることができます。対応するホストフックでは、アクションの実行前に承認を強制することもできます。

ホスト型配信には有料の Pushary プランが必要です。MCP の質問と通知は互換性のある任意のクライアントで利用できます。承認の強制はホスト連携によって異なります。

仕組み

AI Agent  ->  MCP Protocol  ->  Pushary API  ->  Push Notification  ->  Your Phone

Pushary は、AI コーディングエージェントをプッシュ通知に接続する MCP サーバーです。エージェントは Model Context Protocol 経由で Pushary のツールを呼び出し、あらゆるデバイスで通知をすぐに受け取れます。

3 種類の質問 - はい／いいえの確認、選択式、自由記述の入力です。エージェントが状況に応じて適切な種類を選びます。

詳細なコンテキストを含む通知 - エージェントは変更されたファイル、エラーの詳細、次に行うことの提案を含められます。通知をタップすると、詳細ページで確認できます。

エージェントの識別 - 複数のエージェントを実行している場合、各通知に質問しているエージェントが表示されるため、何に回答しているのかを常に把握できます。

権限フック - Claude Code のツール承認プロンプトをプッシュ通知経由で受け取り、スマートフォンから承認または拒否できるようにします。

---

個人向けセットアップ：まずはスマートフォンから

エージェントのターミナルでペアリングのセットアップを実行します：

npx pushary@latest setup

Pushary をスマートフォンにインストールし、QR コードをスキャンするか、表示されたリンクを開きます。フィンガープリントを照合して承認してください。セットアップにより、選択したエージェントのツール、対応するフック、スキルが設定されます。最初に API キーをコピーする必要はありません。個人アカウントには有料プランが必要です。既存の認証情報は再利用されます。

セットアップを確認します：

npx pushary@latest doctor

エージェントに、問題のないテスト用の質問を 1 つ依頼します。想定したデバイスに質問が届き、回答が同じタスクに戻ることを確認してください。

Hermes の場合：

npx pushary@latest setup --agents hermes

これにより、ネイティブプラグインが ~/.hermes/plugins/pushary に書き込まれ、hermes plugins enable pushary と hermes config set で有効になります。その後、hermes gateway restart で Hermes を再起動してください。このプラグインは、通知、質問、待機、キャンセル、リマインダー、スコープ用のツールに加え、Partner の登録と顧客からの質問に対応するツールを提供します。パラメーターには snake_case を使用します。MCP のパラメーター名ではなく、Hermes スキルを使用してください。ネイティブの承認トランスポートでは、Hermes のセッションと継続的な承認が維持されます。

Mac のノッチとその他の回答画面

Pushary for Macをインストールし、同じ個人アカウントでサインインして、アプリからエージェントを接続します。ノッチでは、キーボード操作に対応した確認、選択、テキスト、質問セットのコントロールを利用できます。プレゼンスと配信を維持するには、アプリを起動したままにしてください。まず問題のない質問を 1 つ送ってそこで確認し、Mac から離れている間はスマートフォンへのフォールバックを確認してください。

画面	回答方法
モバイル	アプリ内で確認、選択、テキストによる回答ができます。対応する確認通知では、ロック画面から承認または拒否できます。任意の選択肢やテキストへの回答では、アプリを開きます。
Mac のノッチ	サインイン済みアカウント宛ての質問に、キーボードで回答できます。また、Partner の顧客がスマートフォンから Mac を接続すると、その顧客からの質問にも回答できます。
Slack	インテグレーションと宛先が設定されている場合、ボタン、選択メニュー、テキストモーダルを利用できます。
ブラウザー	ブラウザーの通知が有効な場合、判断ページへのフォールバックとブラウザー通知を利用できます。

配信は設定とプレゼンスに従います。push_first はプレゼンスに応じて配信し、push_only は毎回プッシュ通知を要求し、notify_only は現在のクライアント内に判断を留め、terminal_only はプッシュ通知を避けます。API 呼び出しが成功しただけでは、デバイスにリクエストが表示された証明にはなりません。

Partner のセットアップ：独自の顧客向け

個人向けのペアリングで接続されるのは、運用担当者であるあなたです。Partner インテグレーションでは、スコープ付き接続リンクを通じてアプリケーションの各顧客を登録し、安定した顧客 ID を使って判断のリクエストを送ります。顧客はモバイルの登録フローを使用します。顧客の承認を個人用 Mac の受信箱に送ったり、運用担当者の API キーを共有したりしないでください。

Partner インテグレーションガイドを参照してから、Mastra エージェントの例、AI SDK の例、またはLangGraph の例に進んでください。ツールでは確認、選択、テキストを選べます。アクションの承認と回答の提供は異なる操作です。「はい」というテキスト回答は、別のツールを実行する許可にはなりません。

手動でのフォールバック

手動で MCP を設定する必要があるクライアントの場合は、Pushary のダッシュボードでキーを取得し、次のように設定します。

{
  "mcpServers": {
    "pushary": {
      "url": "https://pushary.com/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

キーは非公開にしてください。クライアントが skills.sh に対応している場合は、npx skills add Pushary/pushary-skill を実行してスキルをインストールします。手動の MCP では、質問と通知をやり取りできます。承認を強制するには、対応するホストのフック／ランタイムとの統合が必要です。

Claude Code のユーザーは、このリポジトリをプラグインとしてインストールすることもできます。

/plugin marketplace add Pushary/pushary-skill
/plugin install pushary

この方法では、環境変数から PUSHARY_API_KEY を読み込みます。インストール方法はどちらか一方を選んでください。CLI でインストールした Claude のフックにプラグインを追加すると、フックが二重に実行される場合があります。方法を切り替える前に、npx pushary@latest clean を実行してください。

プラグインは各フックを npx 経由で起動します。これは、ライブ返信のプレビューをスマートフォンにストリーミングするフックには遅すぎるため、プラグインにはそのフックが含まれていません。ライブプレビューを使うには、代わりに npx pushary@latest setup でインストールしてください。セットアップでは、すべてのフックがローカルコマンドとしてインストールされます。

---

セットアップ：Lovable

Lovable はホステッド型のアプリビルダーであるため、ローカルでのインストール手順はありません（npx skills add は適用されません）。Lovable の UI で MCP サーバーに接続し、エージェントが自らスキルを使用できるよう、スキルを Lovable の Knowledge に貼り付けます。

1. MCP サーバーに接続します。 Lovable で Settings -> Connectors -> Personal connectors（有料の Lovable プラン）に移動し、New MCP server をクリックします。URL に https://pushary.com/api/mcp/mcp を設定し、Bearer token を選択して、API キー（pk_xxx.xxx）を貼り付けます。

2. スキルを Knowledge に追加します。 Lovable は npx によるスキルのインストールに対応していないため、スキルのガイダンスを Settings -> Knowledge に貼り付けます。ソースには、簡潔にまとめられた SKILL-LITE.md を使用してください。これにより、毎回指示を出さなくても、ビルドの完了時に Lovable エージェントが通知し、リスクのある変更の前に確認するようになります。

Lovable で利用できるのは通知と質問のみです（権限フックがないため、承認は強制されません）。詳しい手順は、Lovable guide をご覧ください。

---

セットアップ：Claude Chat と Cowork

Claude Chat または Claude Code では、Pushary for Claude を使用します。Chat では Customize > Plugins > Add > Add marketplace を開き、https://github.com/Pushary/claude-plugin を追加して、Pushary for Claude をインストールします。Claude Code では、/plugin marketplace add Pushary/claude-plugin を実行してから、/plugin install pushary@pushary-claude-plugin を実行します。

Cowork では、既存の Pushary for Cowork plugin を引き続き利用できます。マーケットプレイスとして https://github.com/Pushary/cowork-plugin を追加し、Pushary for Cowork をインストールします。Cowork は Settings > Cowork での常設指示にも対応しています。既存のプラグイン、マーケットプレイス、および pushary-cowork スキルの識別子はそのまま維持されています。

どちらのバンドルも、公開 OAuth コネクターと共通のスキルを使用します。Chat または Cowork ではプラグインの Connectors タブから、Claude Code では /mcp から Pushary に接続し、スマートフォンまたは Mac で使用しているものと同じ Pushary アカウントでサインインしてください。どちらのバンドルも CLI や API キーは必要ありません。

コネクターが表示されない場合は、Customize > Connectors > Add custom connector で https://pushary.com/api/mcp/mcp を追加し、OAuth Client ID と Secret の欄は空のままにしてください。会話で Pushary を有効にし、影響のないテスト質問を一つ送信して、回答が Claude に返ってくることを確認します。

これらのバンドルでは質問と通知を利用できますが、ネイティブの権限フックはインストールされません。Claude Code の承認フックを使うには、上記の Claude Code のセットアップを使用してください。Pushary コネクターの重複を避けるため、アプリごとにインストール方法を一つ選んでください。詳しい Claude のガイド。

---

ツール

このスキルでは、次の MCP ツールを使用します。

ツール	説明
send_notification	ファイルの変更、エラー、次の手順などのリッチコンテキストを任意で含めて、プッシュ通知を送信します
ask_user	プッシュ通知を通じて、はい／いいえ、選択式、自由記述の質問をユーザーに尋ねます
wait_for_answer	ユーザーからの回答をロングポーリングします
cancel_question	重要でなくなった保留中の質問をキャンセルします
list_sessions	実行中のエージェントセッションと保留中の質問を読み取り専用で表示します
propose_scope	実行の境界を確定します。ファイルの glob パターンは対応ホストで適用され、実行でファイルを変更しない場合は、その約束が記録されます

パラメーター、例、使用ガイドラインを含むツールの詳細なドキュメントは、skills/pushary/SKILL.md にあります。

Human-in-the-Loop

エージェントはプッシュ通知で判断を求め、回答を待つことができます。

Agent: "Which auth strategy should I use?"
  Options: JWT tokens / Session cookies / OAuth2 + PKCE
  -> push to your phone

You: tap "JWT tokens"

Agent: proceeds with JWT implementation

質問の種類は次の 3 つです。

• 確認 - はい／いいえの二択
• 選択 - 2～6 個の選択肢から選択
• 入力 - 自由記述で回答

ツールの結果から answered、status、handoffAction（または nextAction）を読み取ります。指示がある場合にのみポーリングしてください。別の画面に引き継ぐ前に、進行中の質問をキャンセルし、採用された回答を尊重してください。有効期限と待機時間はサーバーのポリシーに従います。返答がないことは承認を意味せず、終了したエージェントのターンを遅れて届いた回答で再開することはできません。

パッケージ

パッケージ	レジストリ	説明
pushary	npm	Pushary CLI：セットアップ、権限フック、doctor。同じパッケージは @pushary/agent-hooks としても公開されています
hermes-plugin-pushary	PyPI	Hermes Agent のネイティブプラグイン

対応エージェント

skills.sh または Model Context Protocol に対応するすべてのエージェントで動作します。

• Claude Code（MCP ＋ 権限フック）
• Claude Cowork（カスタムコネクター ＋ スキルのアップロード）
• Hermes Agent（ネイティブプラグインまたは MCP）
• Cursor（MCP）
• Windsurf（MCP）
• Lovable（MCP コネクター ＋ Knowledge 経由のスキル）
• OpenAI Codex（MCP）
• リモート MCP サーバーに対応するその他のクライアント

MCP レジストリエントリーの公開

server.json はマージするだけでは公開されません。MCP レジストリ はバージョンごとに 1 件のレコードを提供するため、変更を加えても、新しいバージョンがレジストリにプッシュされるまでは誰にも反映されず、すべてのエージェントが読み取る内容は古いままです。

通常の手順：server.json の version を更新し、main にマージしてから、公開スキルミラーを同期します。リリースワークフローによって、新しいレジストリエントリーが公開されます。

リリースワークフローは公開されている Pushary リポジトリから公開するため、GitHub OIDC によって io.github.Pushary/pushary 名前空間の所有権を証明できます。リリース後にワークフローとレジストリの結果を確認してください。

手動での代替手順。このディレクトリから実行します。

curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
./mcp-publisher login github
./mcp-publisher publish

レジストリで実際に提供されている内容を確認してください。重要なのはその数値だけです。

curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=pushary"

このエンドポイントは、古いものから順に すべての バージョンを返します。_meta."io.modelcontextprotocol.registry/official".isLatest が true のエントリーを確認してください。リストの先頭行は最も古いレコードであり、現在公開されているものではありません。

コントリビューション

コントリビューションを歓迎します。プルリクエストを送信する前に、コントリビューションガイドをお読みください。

セキュリティ

セキュリティの脆弱性を発見した場合は、責任ある方法で報告してください。詳細については SECURITY.md をご覧ください。

資金提供

このプロジェクトは、エストニアのソフトウェア開発企業である RalphNex OU から全額資金提供を受けています。

ライセンス

MIT - Copyright (c) 2025 RalphNex OU