approval-box

Approval Box connector. When an AI coding agent needs a human decision, approval or action, it also files a request to Approval Box. You answer from the Approval Box app or web, and the answer is delivered straight back into the same agent session — mid-turn if the agent is working, as a new turn if it is idle. The agent never polls.

Supported agents: Claude Code, Codex, Cursor, Grok — on macOS, Windows and Linux.

Cursor and Grok receive answers through the background receiver command returned by the request tool. Cursor hooks bind that receiver to the conversation; they do not consume answers. Keep the receiver running until it returns the answer. Its output includes a command to wait for the next answer.

Codex answers use Aiterm's Steer delivery. Requests do not depend on Codex hook state or an application restart. Setup removes the old Approval Box delivery hooks and their registration while keeping other products' hooks.

Codex answer delivery requires Aiterm 0.56.0 or later. Configure its shared Steer through aiterm-setup --codex-steer enable to receive answers during the current turn as well as while idle. Approval Box does not register another Codex delivery hook.

AIが人間の判断・承認・操作を求める時に、Approval Boxへも申請します。アプリかWeb版で答えると、その答えが申請したAIの会話へそのまま届きます。

Setup / 使い方

npx -y approval-box@latest setup

1. setup finds the agents on this machine and registers Approval Box (MCP server and hooks). It shows the files it will change and keeps a backup (*.approval-box-backup) before writing. PCにあるAIを見つけて登録します。書き換えるファイルを先に見せ、控えを残してから書き換えます。 It also offers to add one short paragraph to each agent's global instructions (~/.claude/CLAUDE.md, $CODEX_HOME/AGENTS.md, ~/.grok/AGENTS.md) so the agent also files decisions, approvals and actions with request_decision. Cursor does not read a global file, so setup passes the same text through a sessionStart hook in ~/.cursor/hooks.json. If an instructions file is a symlink (for example, generated by a dotfiles repo), setup leaves it alone and asks you to add the paragraph to the source instead. Skip with --no-instructions. AIが毎回読む全体の指示に「判断・承認・操作が要る時は request_decision でも申請する」という一節を足すかを聞きます。Cursor はファイルから読まないので、会話の始まりのhook（~/.cursor/hooks.json の sessionStart）で渡します。指示ファイルが別の所への参照（symlink、dotfilesの生成物など）の時は書かず、管理元の規範に足すよう案内します。足さない時は --no-instructions。
2. Scan the QR code or enter the code in “Add device” in the app or web. 画面のQRコードかコードを、アプリかWeb版の「端末を追加」で読み取ります。
3. Tell your agent: Approval Boxのsetup_testを実行して (or “run Approval Box setup_test”). Answer the test request; when the answer reaches the agent, you are ready. AIに「Approval Boxのsetup_testを実行して」と言い、テストの申請に答えます。答えがAIまで届けば準備完了です。

Commands / コマンド

npx approval-box test        # connection test / 接続テスト
npx approval-box status      # connection, registrations, checks / 状態
npx approval-box doctor      # find why answers do not arrive / 届かない時の原因
npx approval-box uninstall   # remove everything and unlink this device / 全部外す

Self-hosted server: npx -y approval-box@latest setup --server https://your-server.

Requires Node.js 20 or later. License: MIT.

会話を開き直した時

list_my_decisions で、自分が引き継ぐ申請を確かめ、対象ごとに resume_decision({decision_id: "K-…"}) を呼びます。未決・保留なら今の会話へ 配送先を移し、回答済みなら答えを直接返します。同じ端末にある他の作業の申請は、 引き継ぐ対象に含めないでください。amend_decision も、修正が成功した時に配送先を 呼び出した会話へ更新します。Cursor・Grokでは、返る案内に従って背景の受信を起動します。

この機能はコネクタ0.1.13以降と対応サーバーを使います。会話を開き直しても、 再開を指定するまでは元の会話が配送先です。答えは get_decision でも取得できます。

誰から・何の仕事の申請か

request_decision は requester_name（申請するAI自身の名前）と session_label（何の仕事の申請か）を必須で受けます。アプリの一覧と通知には「申請者 / 作業名」の一行が出ます。名前を持たないAIは requester_name を空文字にします。その申請は、AIの種類と作業名で出ます。

AIには、利用者へ申請の話をする時は件名で伝えるよう返します。アプリは申請のID（K-…）を出しません。

申請に画像を添える

request_decision に image_paths: ["/absolute/path/screenshot.png"] を指定すると、AIの画像を本文下に添えて申請します。10件、単体20MiB、合計50MiBまで。全画像を上げてから申請と通知を確定します。最初の確認の札を付けた出し直しでも同じ画像パスを渡してください。amend_decision.changes.image_paths は全置換、空配列で削除です。回答添付とは別の欄です。リモートMCPは upload_request_image のIDを request_attachment_ids に渡します。