gpt-worker マニュアル

ステップ 1：リポジトリのクローンとコマンドの配置

1. 任意の作業ディレクトリにリポジトリをクローンします。

   git clone https://github.com/Nihondo/gpt-worker.git
   cd gpt-worker

2. ターミナルから gpt-worker コマンドを実行できるように、パスの通った場所へシンボリックリンクを作成します。

   ln -s "$(pwd)/bin/gpt-worker" "$(brew --prefix)/bin/gpt-worker"

ステップ 2：エージェントへのスキル登録（SKILL.md）

お使いのコーディングエージェントの skills ディレクトリへ SKILL.md のシンボリックリンクを作成し、エージェントが gpt-worker を認識できるようにします。

mkdir -p ~/.claude/skills/gpt-worker
ln -s "$(pwd)/SKILL.md" ~/.claude/skills/gpt-worker/SKILL.md

mkdir -p ~/.codex/skills/gpt-worker
ln -s "$(pwd)/SKILL.md" ~/.codex/skills/gpt-worker/SKILL.md

mkdir -p ~/.agents/skills/gpt-worker
ln -s "$(pwd)/SKILL.md" ~/.agents/skills/gpt-worker/SKILL.md

ステップ 3：初期化と Worker の準備

最初のプロジェクトのディレクトリを指定して init コマンドを実行します。

gpt-worker init -w /path/to/your-project

• 初回実行時のみ、ブラウザで Cloudflare へのログイン画面が開きます。
• ログインが完了すると、自動的に Cloudflare Worker がデプロイされます。
• 完了時に表示される Server URL を確認します（後から gpt-worker url でも確認できます）。

ステップ 4：ChatGPT の設定

1. 開発者モードを有効にする：

2. MCP Connector を登録する：

3. ChatGPT Project を作成する：

4. 指示文（Project Instructions）を設定する：

     Use the gpt-worker connector. It supplies its own operating instructions — follow them for every round.

ステップ 5：ChatGPT Project URL の登録と Chrome の自動送信設定

1. 作成した ChatGPT Project の URL（ブラウザのアドレスバーにある https://chatgpt.com/g/...）を CLI に登録します。

   gpt-worker chat-url "https://chatgpt.com/g/g-p-.../project"

登録すると、タスク発行時に Chrome がプロンプトを準備し、Apple Events が有効なら自動送信します。

2. Chrome の自動送信を許可する（初回のみ）：

画面フォーカスを奪わずにバックグラウンドでメッセージを入力・送信させるために、Chrome 側で以下の設定を有効にします。

[あなた / ローカルエージェント]                 [ChatGPT]
          │                                         │
          │── 1. gpt-worker task "<作業内容>" ────>│
          │                                         │ (コード調査 & 計画立案)
          │<── 2. gpt-worker wait (計画受信) ───────│
          │                                         │
     (コード修正 & テスト実行)                      │
          │                                         │
          │── 3. gpt-worker report ────────────────>│
          │                                         │ (変更差分の確認 & レビュー)
          │<── 4. gpt-worker wait (完了または指示) ─│

1. 通信ブリッジを起動する

作業を始める前に、対象プロジェクトでローカル通信プロセス（ブリッジ）を起動します。

gpt-worker start -w .
gpt-worker status -w .

2. タスクを依頼する（`task`）

やりたい作業内容を自然言語で伝えます。

gpt-worker task "ログイン画面のバリデーション表示を修正して" -w .

Chrome で ChatGPT の画面が開き、プロンプトが自動で入力・送信されます（※ 自動送信には上述の Chrome「Apple EventsからのJavaScriptを許可」設定が必要です）。

3. 計画の完成を待つ（`wait`）

ChatGPT がファイルを調査し、作業計画（PLAN）を作成するのを待ちます。

gpt-worker wait -w .

計画が届くとターミナルに出力されます。内容を確認し、問題がないかチェックします。

4. コード修正とテストを実行する

ローカルエージェント（Claude Code や Antigravity など）またはあなた自身が、計画に沿ってファイルを編集し、テストを実行します。

5. 結果を報告する（`report`）

変更したファイル数やテスト結果を ChatGPT に報告します。

gpt-worker report --changed 2 --tests "8 件のテストすべて合格" -w .

6. レビュー結果を受け取る（`wait`）

再度 wait を実行して ChatGPT の返答を待ちます。

gpt-worker wait -w .

ChatGPT が「完了（DONE）」と判断すれば作業終了です。追加の作業指示がある場合は、ステップ 4 へ戻ります。

7. 作業を終了する

作業が終わったらブリッジプロセスを停止します。

gpt-worker stop -w .

新しいチャットの開始と会話スレッドの管理

gpt-worker はワークスペースごとに ChatGPT の会話スレッド（URL）を記憶し、同じスレッド上で対話を継続します。 会話が長くなって ChatGPT の動作が重くなった場合や、新しいスレッドで仕切り直したい場合、あるいはブラウザで手動で開いた別の会話に切り替えたい場合は、以下のコマンドを使用します。

gpt-worker chat new -w .

gpt-worker chat attach "https://chatgpt.com/g/g-p-.../c/..." -w .

gpt-worker chat status -w .

別のプロジェクトを追加したい

Cloudflare Worker の再デプロイや ChatGPT の再設定は不要です。新しいディレクトリで init を実行するだけで登録できます。

gpt-worker init -w /path/to/another-project

プロジェクト固有のルールを設定したい（`guidance`）

「テストは Vitest で書く」「TypeScript の strict モードを守る」など、ChatGPT に常に守らせたい前提ルールを登録できます。

gpt-worker guidance "テストは必ず Vitest で書き、関数コンポーネントを優先すること" -w .

gpt-worker guidance -w .

gpt-worker guidance --clear -w .

読み取りアクセスの管理（allow-read と deny-read）

.gitignore に含まれるファイルは通常 ChatGPT から隠され、通常の追跡ファイルは読み取ることができます。allow-read と deny-read を使用して、きめ細かな読み取りポリシーを設定できます。

• ポリシーの優先順位: 機密ファイル（.env、秘密鍵など） > deny-read > .gitignore ベースライン（allow-read による例外許可を含む）。機密パスは絶対に読み取れません。
• allow-read <path>: Git で無視されているファイルまたはディレクトリへの MCP read_file 直接読み取りを個別許可します。ディレクトリ配下のファイルは一覧表示や検索からは隠蔽されたままとなります。
• unallow-read <path>: allow-read の例外許可を解除します。
• deny-read <path>: ファイルまたはディレクトリ（通常の追跡ファイルや過去に allow-read されたパスを含む）の読み取りを明示的に禁止します。禁止されたパスは一覧表示、検索、直接読み取りから完全に隠蔽されます。
• undeny-read <path>: 明示的な禁止設定を解除します。そのパスが同時に allow-read にも登録されていた場合、背後にある allow-read 例外が再び有効になります。

gpt-worker allow-read config/test-fixture.json -w .
gpt-worker allow-read fixtures -w .

gpt-worker allow-list -w .

gpt-worker unallow-read config/test-fixture.json -w .
gpt-worker unallow-read fixtures -w .

gpt-worker deny-read secret-docs -w .
gpt-worker deny-read config/internal.json -w .

gpt-worker deny-list -w .

gpt-worker undeny-read secret-docs -w .
gpt-worker undeny-read config/internal.json -w .

※ gpt-worker status では read allowed と read denied の両方のパスが表示されます。.env や秘密鍵（.ssh/ 等）などの機密ファイルは、いずれのリストによっても読み取り可能になることはありません。

プロジェクト全体を一度に ChatGPT に渡したい（`workspace_bundle`）

ChatGPT は workspace_bundle を呼び出すことで、プロジェクトの読み取り可能なテキストファイルを 1 つの .tgz アーカイブとして受け取り、自身のサンドボックスで展開して必要な箇所だけ読めます。広い文脈が必要な作業で、何度もファイルを読みに行く往復を減らせます。ご自身で実行するものではなく、ChatGPT が必要なときに呼び出します。

• 他の読み取りと同じルール：ChatGPT がすでに読める範囲だけが入ります。機密ファイル（.env、秘密鍵など）、Git で無視されているファイル、deny-read したパス、ノイズの多いフォルダ（node_modules、ビルド出力など）は除外され、名前も件数も出ません。allow-read したパスは直接読み取り専用のままで、アーカイブには入りません。
• 梱包前に秘密をマスク：スキャナが見つけた秘密はすべて [REDACTED:<ルール名>] に置き換えられ、ローカルのパスは [workspace] や [home] に正規化されます。その場でマスクできない秘密が見つかったファイルは、代わりにアーカイブから外されます。
• 入らないもの：バイナリファイル、シンボリックリンク、1 MiB を超えるファイル。アーカイブの先頭にある BUNDLE.md に、これらの一覧と、アーカイブが完全かどうかが書かれます。
• サイズ：既定は 1 MiB、最大 4 MiB です。大きすぎる場合、ChatGPT にはフォルダ別の内訳付きのエラーが返り、より狭い path を指定し直します。黙って切り詰められることはありません。
• アーカイブを開く際に ChatGPT が承認を求めます。 初回は「ファイルを実体化しますか？」というダイアログが出ます。「この会話内では許可」（「許可する」の右の矢印から選択）を選ぶと、その会話では再度聞かれません。通常の「許可する」だと毎回聞かれます。新しい会話では再び聞かれます。
  • 拒否すると、ChatGPT には拒否されたことが伝わり、アーカイブの再試行はしません。1 ファイルずつ読むように依頼してください。
  • 誰も応答しないと、ChatGPT は無期限に待ち続けます（15 分以上待っても続くことを確認済み）。gpt-worker はダイアログ自体は見えませんが、「アーカイブを渡したあと ChatGPT が静かになった」ことは分かります。その場合、gpt-worker wait が通知を出し、沈黙が続くと催促を出します。gpt-worker status にも hint の行が出ます。未回答のダイアログと、ChatGPT がアーカイブをまだ読んでいる状態は区別できないため、証拠ではなく、ChatGPT の画面を見るきっかけとして扱ってください。
• tar が必要です（macOS と Linux には標準で入っています）。

設定内容を確認したい

登録されている Project URL や自動送信の設定を確認できます。

gpt-worker show-config -w .

登録中のワークスペース一覧を見たい

このマシンで登録されている全プロジェクトと、ブリッジの稼働状態を一覧表示します。

gpt-worker workspaces

Web ダッシュボード

Cloudflare Worker はブラウザダッシュボードも配信します。キュー状態・タスク履歴をカンバン風に可視化し、メッセージの ack/discard、guidance/limits の編集、CLI を使わずブラウザから新規タスクを投入することもできます。ログイン経路は2つあり、それぞれ URL が異なります。

ワークスペース単位（そのワークスペース自身の owner token でログイン）:

gpt-worker url -w .

WebUI URL（https://<your-worker>.workers.dev/dashboard/<workspace_id>）を開き、上記と同じ owner token（そのワークスペースの gpt_token）でログインします。共有 hub token ではここではログインできません（拒否されます）。ログインすると、その owner token は 24 時間有効なブラウザセッション（そのワークスペースのダッシュボード専用パスに限定された HttpOnly/Secure Cookie）と交換されます——以降のリクエストで owner token 自体が再送されることはありません。

登録済み全ワークスペースの横断（共有 hub token でログイン）:

gpt-worker url

WebUI URL（https://<your-worker>.workers.dev/dashboard/hub）を開き、その共有 hub token でログインします（単一ワークスペースの gpt_token ではここではログインできません）。ログイン後は、この共有コネクタに登録されている全ワークスペース（gpt-worker init で追加され、ChatGPT の list_workspaces にも表示されるのと同じ一覧）を選択できるワークスペース一覧が表示され、選んだワークスペースについて単一ワークスペース用ダッシュボードと全く同じ閲覧・操作ができます。2つのログインは完全に別セッションです——ワークスペースのセッションで hub ダッシュボードに入ることはできず、hub のセッションでワークスペース自身のダッシュボード URL に直接ログインすることもできません。また hub 側は自身が登録済みのワークスペースにしか到達できず、任意のワークスペースには到達できません。

できること・動作仕様:

• できること: キューに残っているメッセージやタスク履歴の閲覧（時系列タイムライン表示含む）、メッセージの確認（ack）や破棄（discard）、guidance（開発ルール）やメッセージ上限サイズの編集、ブラウザ設定（共有 Project URL・個別 override・会話 URL）の確認・編集・クリア、ブラウザからの新規タスク投入（これらはワークスペース単位・hub 横断のどちらのダッシュボードからも操作可能です）。
• MCP アクセス履歴: タスク・メッセージタブの隣にある MCP Access タブで、ChatGPT が MCP コネクタ経由で行った操作を確認できます（下記の MCP アクセス履歴 を参照）。
• リアルタイム更新: WebSocket によるリアルタイムプッシュ通知に対応しており、タスクの進捗やメッセージの送受信、設定変更などが画面へ即座に反映されます（WebSocket 切断時は適応型ポーリング（作業中: 約30秒、アイドル: 約2分、Hub ワークスペース一覧: 約60秒）へ自動フォールバックし、タブ非表示時は通信を停止します）。
• データ保持期間: Worker 本体の仕様に準拠します（acked メッセージは7日後、完了したタスク履歴は30日後に自動消去）。MCP アクセス履歴は24時間、1ワークスペースあたり最大1000件まで保持されます。

ワークスペース単位のダッシュボードは、そのワークスペースの owner token をローテーションした場合（gpt-worker rotate --gpt -w .）、またはワークスペースを削除した場合（gpt-worker remove -w . --yes）にセッションが即座に無効化されます。hub ダッシュボードは、共有 hub token をローテーションした場合（gpt-worker rotate --hub）にセッションが即座に無効化されます——データの保持期間を参照してください。

#### MCP アクセス履歴

MCP Access タブには、ChatGPT がコネクタ経由で行ったツール呼び出しが新しい順に一覧表示されます。何を読んだか（読もうとしたか）、なぜ拒否されたかを確認できます。各行には次を表示します。

• 操作: 平易なツール名（Read file、Git diff、Search、Batch など）と、その下に元のツール名。
• 対象: ファイルやディレクトリのパス、または「workspace search」「PLAN · iteration 2」のような固定表記。
• 結果: 文字のバッジで表示します（色だけには頼りません）。OK、Gate（ブロック：アクティブなタスクが無い、または読み取り窓が閉じている——「アクセス制限」を参照）、Deny（拒否：機密ファイル・Git 無視ファイル・ワークスペース外のファイル）、NG（エラー）、Mix（結果が混在するバッチ。開くと各呼び出しを確認できます）。バッジは収まるよう短くしてあり、詳細欄では「Blocked」「Denied」と正式な語で表示します。
• 所要時間と、その呼び出しが属するタスク。

読みやすさのため、同じタスクの連続したファイル読み取り成功（互いに30秒以内）は「Read file × N」の1行にまとめます。拒否・ブロック・エラーはまとめません。Group repeated reads のチェックを外すと全件を個別に表示します。Tool と Result のフィルターは読み込み済みのページだけでなく履歴全体に適用され、Load more でさらに過去へ遡れます。ワークスペース単位・hub のどちらのダッシュボードでも同じように使えます。

記録される内容と、決して記録されない内容: 保存するのはメタデータ（時刻・ツール・コネクタ・タスク ID・安全な対象表記・結果の分類・短い理由コード・所要時間）のみです。ファイルの内容、diff、検索クエリやヒット結果、メッセージ本文やタイトル、エラー文、ツールの生の引数・結果、シークレット、絶対パスは一切保存されません。 ワークスペース外を指すパスは固定のラベルに置き換えて表示します。これは「何にアクセスしたか」の監査記録であり、アクセスした内容の複製ではありません。

wait の待ち時間はデフォルトで 15 分です。タイムアウトした場合や状況を確認したいときは、そのまま再度 wait を実行します（タスクを再送する必要はありません）。

gpt-worker state -w .

gpt-worker wait -w .

別のエージェントへのタスク引き継ぎ

作業中のエージェントが途中で停止せざるを得ない場合（レートリミットが近い、セッションが終了するなど）、ラウンドを通常どおり終える代わりに、タスクを別のエージェントへ引き継げます。

gpt-worker handoff --changed 3 --tests "ユニットテストは通過、結合テストは未実行" --reason "rate limit" -w .

エージェントはここで待たずに終了します。ChatGPT がタスクの経緯——目標、完了した内容、下した判断、既に検討して見送った案——をまとめた引き継ぎ brief をキューに入れます。別のエージェントは通常の待機コマンドでそれを受け取ります。

gpt-worker wait -w .

brief はキューに 7 日間保持されるため、受け手はいつ開始しても構いません。別のモデル、別のセッション、あるいは同じマシンで翌日でも構いません。2 つのエージェント間でファイルやセッション状態を手動でコピーする必要はありません。タスクの状態は Worker 側で保持されているため、再開する側は前任者から直接引き継ぎを受けることなく作業を続けられます。

引き継がれるのは、ChatGPT が計画とレビューを通じて蓄積した文脈です。ローカルのエージェントが交代しても ChatGPT はタスクに留まり続けるため、引き継ぎ後のレビューでも、それ以前に行われた作業を踏まえた判断が行われます。

前のエージェントが handoff を実行できないまま停止した場合（途中で打ち切られ、正常に終了できなかった場合）、キューにはまだ引き継ぎ内容が入っていません。その場合は新しいエージェント自身が handoff を実行してタスクを引き取れます。handoff は引き継ぎ元・引き継ぎ先のどちらからでも実行できる共通コマンドです。Worker や ChatGPT はどちらのエージェントが呼んでいるかを区別せず、進捗情報として処理します。

gpt-worker handoff --reason "前のエージェントが報告せずに停止したため引き継ぐ" -w .

--changed / --tests は省略するか、何も検証していないと正直に書いてください。自分がやっていない作業を報告する必要はありません——ChatGPT はどの報告に対しても git_status / git_diff でコードの実態を自ら確認します。これはタスクがまだラウンド途中の状態でのみ機能します。失敗した場合はすでに返信がキューにある可能性があるため、代わりに gpt-worker wait を実行してください。成功したら続けて gpt-worker wait を実行し、brief を受け取ってください。

引き継ぎ brief がメッセージサイズの上限（既定 16KB）に収まらない場合は、そのワークスペースの上限を引き上げられます。

gpt-worker limits 65536   # バイト単位。引数なしで実行すると現在値を表示
gpt-worker limits --reset # 既定値に戻す

どちら側が書いたメッセージも、このワークスペースがタスクをまたいで使い回している同じ長期会話に載ります。上限を引き上げるほど、その会話がコンテキスト上限に達するペースも速まるため、安易に上げず必要な場合にのみ調整してください。

最新版へのアップデートと再デプロイ

git pull でツールを最新版に更新した際、Worker 側のコード（worker/）に変更が含まれている場合は、Worker の再デプロイを行います。

cd /path/to/gpt-worker
git pull

npm run deploy

gpt-worker stop -w /path/to/your-project
gpt-worker start -w /path/to/your-project

プロジェクトの登録を解除したい

不要になったプロジェクトの登録情報と Worker 上の記録を削除します。

gpt-worker remove -w /path/to/project --yes

Chrome の自動送信が動かない場合

既存の会話タブへ背面からメッセージを自動送信するには、Chrome の設定が必要です。

1. Chrome のメニューバーから 表示 → 開発 → Apple EventsからのJavaScriptを許可 を有効にします。
2. 設定後、Chrome を完全に再起動 してください。
3. 入力欄にテキストや下書き（メンション含む）が残っている場合でも、自律的な作業の継続性を優先するため、自動送信時は既存の内容を消去して新しいプロンプトが上書き投入されます。

安全上の注意

• 計画の確認：ChatGPT が作成した計画（PLAN）は、実行前に必ず確認してください。意図しないファイルの削除や外部通信（curl など）が含まれていないかチェックします。
• 機密ファイルの保護：.env、秘密鍵、.ssh、.aws などの機密ファイルは、ChatGPT からの読み取り要求があっても自動的に拒否されます。
• アクセス制限：ChatGPT がファイルを読み取れるのは、アクティブなタスクが存在する間だけです。

データの保持期間

ステップ3でデプロイした、ご自身の Cloudflare Worker 上にタスクのやり取りが一定期間保持されます（チャットとローカルのみで完結する構成に比べ、Worker 上に一時データが残ります）。

• タスク本文（目標テキスト、計画、実行報告）は、配信され確認応答が返されてから7日後に Worker 上から自動的に削除されます。
• タスク履歴（ChatGPT に過去のタスクの文脈を渡すための目標テキストと結果概要）は、タスクが完了または保留などの最終状態に達してから30日後に Worker 上から自動的に削除されます。進行中のタスクは削除されません。
• MCP アクセス履歴（メタデータのみ——MCP アクセス履歴を参照）は各呼び出しから24時間後に削除され、1ワークスペースあたり最新1000件のみが保持されます。gpt-worker remove でワークスペースと一緒に削除されます。
• Web ダッシュボードのセッションは24時間で失効し、自動的に掃除されます。ワークスペース単位のダッシュボードはそのワークスペースの owner token をローテーションした場合やワークスペースを削除した場合、hub ダッシュボードは共有 hub token をローテーションした場合に即座に無効化されます。
• ワークスペースのタスク・キュー記録を Cloudflare アカウントから完全に消去するには gpt-worker remove -w <dir> --yes を実行してください（プロジェクトの登録を解除したいを参照）。個別のタスク履歴だけを削除する手段はなく、ワークスペースごと削除する必要があります。

終了コード

コード	意味
0	成功
1	エラー（メッセージに対処方法が出ます）
2	wait がタイムアウトし、まだ返信がない — もう一度実行する。ChatGPT に workspace_bundle のアーカイブを渡したあと沈黙が続いている場合は、その旨がメッセージに出ます（ChatGPT の画面で承認待ちかもしれません）
3	wait は返信を受け取ったが、タスクが先に進まなかった。返信は表示されます。gpt-worker state で確認し、本当に滞留しているなら gpt-worker discard-task --yes
4	Worker に接続できなかった。task/report/handoff ではリクエストが反映された可能性があるかどうかがメッセージに出ます — 再実行する前に gpt-worker state で確認してください。wait は、返信を表示した直後に、その確認応答（ack）を確認できなかった場合にも 4 で終わります。再配信されると決めつけず、表示される案内（gpt-worker state と gpt-worker queue --task <task id> の確認）に従ってください

コマンドは一時的なネットワーク障害を自動で再試行します（短い間隔で数回）。wait はさらに、自身のタイムアウトまで再試行を続けるので、長い待機中の短い接続断で終了することはありません。