bugpatrol

Bugpatrol

Bugpatrol は、AI エージェントで構成された QA チームです。人間のテスターと同じように、ユーザーのアプリを実行します。CLI は npm パッケージ bugpatrol です。npx bugpatrol@latest <command> で実行します。ソースからビルドしないでください。

npx がキャッシュ内の古いコピーを実行する可能性があるため、必ず @latest を付けてください。古いコピーでは、コマンドや設定の構成が異なる場合があります。例外が 1 つあります。リポジトリの package.json に bugpatrol が記載されている場合は、リポジトリで選択されているバージョンを使うため、npx bugpatrol <command> を実行してください。

ソースと完全なドキュメント：https://github.com/agent-labs-dev/bugpatrol

1. Bugpatrol の機能

Bugpatrol には次の役割があります。

• explorer はアプリを起動し、画面をマッピングして、問題と思われる箇所を報告します。また、アプリのコンソールエラーと失敗したリクエストも確認します。
• judge は各検出結果とそのスクリーンショットを確認します。課題を起票するか、既存の未解決課題に検出結果を追加するか、理由を添えて却下します。
• fixer（デフォルトでは無効）は、独自の git ワークツリーで bugpatrol/fix-<issue> ブランチ上に修正を書きます。
• retest は修正用ワークツリーからアプリを起動します。explorer がフローを再度実行し、judge が修正前後のスクリーンショットを比較します。
• publish のステップ（デフォルトでは無効）では、検証済みの修正ごとに GitHub PR を作成し、修正されていない重大なバグごとに課題を作成します。

プラットフォーム：web（Playwright）、electron（CDP）、ios および android（Maestro）。

explorer、judge、fixer は LLM エージェントです。それぞれ、ローカルのエージェント CLI（claude、codex、kimi、opencode、pi）または API キー（OpenRouter、Vercel AI Gateway、OpenAI、Anthropic）で動作します。

Bugpatrol はすべてのファイルをプロジェクトのルートにある 1 つの .bugpatrol/ フォルダーに保存します。設定とアプリガイドはコミット対象です。ローカルデータは .bugpatrol/runs/ に保存され、git で無視されます。最初のセッションでは ルーチン（たとえば enter-app）を学習するため、以降のセッションはより速く開始でき、モデルを使わずにこれらの経路を再生できます。ルーチン（.bugpatrol/routines/）とアプリマップ（.bugpatrol/appmap.json）はコミット対象なので、CI や新たにクローンしたリポジトリでも再生できます。Bugpatrol はこれらを書き込みますが、コミットはしません。コミットするのはユーザーです。

2. リポジトリ向けに設定する

次の手順を順番に行ってください。リポジトリから見つけられない情報だけ、ユーザーに確認してください。

2.1 必ず把握する 2 つの情報

この 2 つの情報がなければ、Bugpatrol は何もできません。

1. このマシンでアプリを起動する方法。
2. アプリにサインイン機能がある場合、そのサインイン方法。

推測してはいけません。両方を把握するまで、ステップ 2.3 に進まないでください。いずれかを確認できない場合は、作業を止めてユーザーに伝えてください。試したこと、不足している情報、ユーザーに提供してほしい情報を伝えてください。

まず、リポジトリを確認してください。package.json のスクリプト、README、CONTRIBUTING、.env.example、docker-compose.yml、E2E テスト（Playwright、Cypress、Detox、Maestro）、app.json、Info.plist、AndroidManifest.xml を確認します。次の情報を見つけてください。

• プラットフォーム：web、Electron、iOS、Android、またはコマンドラインアプリ（cli）。
• ローカルで使うアプリの起動コマンド。たとえば npm run dev。
• URL とポート（web）、CDP ポート（Electron）、またはバンドル ID かパッケージ名（モバイル）。
• データの削除、実在する相手へのメール送信、支払いなど、explorer が決して実行してはならない操作。

事実 1：アプリを起動する

アプリを自分で起動し、実行できることを確認します。

• Web： 起動コマンドを実行し、続けて curl -sf <url> >/dev/null && echo up を実行します。確認後、サーバーを停止します。
• Electron： --remote-debugging-port=<port> を付けて起動コマンドを実行し、続けて curl -sf http://127.0.0.1:<port>/json/version を実行します。
• iOS： アプリが起動済みのシミュレーターにあることを確認します：xcrun simctl listapps booted | grep <bundle id>。アプリに必要な場合は、開発サーバー（Metro など）も起動します。
• Android： アプリがエミュレーターにあることを確認します：adb shell pm list packages | grep <package>。

バックエンドも確認します。.env または設定に API URL が指定されている場合は、たとえば curl -s -o /dev/null -w '%{http_code}' <api url> を実行して応答を確認します。Web アプリは起動しても、バックエンドが停止しているとサインインできないことがよくあります。

アプリが起動しない場合は、原因を特定します。依存関係の不足、.env の値の不足、データベースまたはバックエンドの停止、アプリビルドの未インストールなどが考えられます。npm install のように、安全かつローカルで対応できるものだけを修正します。それ以外の問題は、作業を中止してユーザーに確認します。例：

• 「アプリには DATABASE_URL が必要です。テストにはどのデータベースを Bugpatrol で使用できますか？」
• 「iOS アプリがシミュレーターにインストールされていません。npx expo run:ios を使って、一度ビルドしてください。」
• 「アプリは API_URL のバックエンドを呼び出しています。使用できる開発環境またはステージング環境のバックエンドはありますか？」

ユーザーが安全だと明言しない限り、Bugpatrol を本番システムに接続しないでください。

事実 2：サインインする

アプリにサインイン機能があるかどうかを確認します。アプリを開くか、コード内のサインインルート、認証ミドルウェア、認証プロバイダーを調べます。サインイン機能がない場合は、ステップ 2.2 に進みます。

サインイン機能がある場合は、次の方法から優先順に探します。

1. アプリがサインイン済みの状態で起動する。 たとえば、開発用の認証バイパス、シード済みのセッション、環境変数内のセッショントークン、またはセッションを設定するディープリンクです。コマンドを app.setup に記述します。
2. セットアップコマンドでテストユーザーを作成する。 たとえば、シードスクリプトや、E2E テストで使用するテスト専用のログインエンドポイントです。これを app.setup に記述し、capture を使って出力から値を読み取ります。
3. テストアカウントを使う。 ユーザーがメールアドレスとパスワードを環境変数として設定します。環境変数名を app.secrets に記載し、サインインの手順を .bugpatrol/instructions.md に {{NAME}} プレースホルダーを使って記述します。

エクスプローラーは、ワンタイムコード、CAPTCHA、ハードウェアキー、またはサードパーティの SSO ページを通過できません。サインインにこれらのいずれかが含まれる場合、アプリにはテスト用のバイパスが必要です。

多くのアプリはワンタイムコードでサインインし、E2E テストではセッショントークンを返すテスト専用エンドポイントを使用します。E2E セットアップファイル（たとえば e2e/setup/、auth.setup.ts、または global-setup）で探してください。次に、トークンからセッションを設定する URL を探します。OAuth またはマジックリンクのコールバックルートで設定できることがよくあります。両方を app.setup とアプリガイドで使用します。

app:
  setup:
    # One command can capture more than one value.
    - run: >-
        curl -sf -X POST "$API_URL/auth/test-login"
        -H "X-Test-Secret: $TEST_LOGIN_SECRET" -d '{"email":"[email protected]"}'
      capture:
        SESSION_TOKEN: '"token":\s*"([^"]+)"'
        USER_ID: '"userId":\s*"([^"]+)"'

## Sign in
Open http://localhost:3000/auth/callback#token={{SESSION_TOKEN}}&user_id={{USER_ID}}. Do not use the sign-in form.

モデルに表示されるのは {{NAME}} プレースホルダーだけです。Bugpatrol は、たとえばエクスプローラーが URL を開くときなど、エクスプローラーがアプリを操作する際にのみ実際の値を挿入します。Bugpatrol はすべてのログとファイルで値を隠します。

テストアカウントの状態

テストアカウントによって、エクスプローラーでテストできる内容が決まります。

• オンボーディング。 新しいアカウントは通常、最初にオンボーディングに進みます。オンボーディングでは、エクスプローラーのステップのほとんどを使用できます。アカウントのオンボーディングが必要な場合は、アプリガイドにオンボーディングの回答を記載するか、パトロールの前にアカウントのオンボーディングを一度済ませてください。
• オンボーディングのバグ。 オンボーディングの修正を再テストするには、オンボーディングを済ませていないアカウントが必要です。セッションごとに新しいテストユーザーを作成します。セットアップコマンドに一意のメールアドレスを指定してください。例：bugpatrol-$(date +%s)@example.test。
• データ。 新しいアカウントにはデータがないため、多くのページには空の状態のみが表示されます。主要なフローでデータが必要な場合は、app.setup にシードコマンドを追加してください。

Bugpatrol には、E2E テストで共有しているアカウントではなく、専用のアカウントを使用してください。エクスプローラーがアカウントのデータを変更するためです。

サインイン方法がわからない場合は、作業を止めてユーザーに確認してください。次の選択肢を提示してください。

• 「テストアカウントを提供してもらえますか？シェルで TEST_EMAIL と TEST_PASSWORD を設定してください。ここには貼り付けないでください。」
• 「Bugpatrol がそのセッションを使えるように、一度サインインしてもらえますか？」（たとえば、環境変数に保存したセッショントークンや、サインイン状態を維持するシミュレーターなどです。）
• 「Bugpatrol 用のテストユーザーを作成する方法を追加できます。シードスクリプト、または開発環境でのみ動作するテスト専用のログインエンドポイントです。追加してもよいですか？」

本人の許可なく、その人自身のアカウントを使用しないでください。本番システムでテストユーザーを作成しないでください。

2.2 マシンを確認する

1. node --version を実行します。Bugpatrol には Node 22 以降が必要です。
2. アプリのリポジトリで git remote -v を実行します。Bugpatrol には git と origin リモートが必要です。各パトロールサイクルで origin/main を取得するためです。デフォルトブランチが main でない場合は、agents.patrol.pull を設定します（例：origin/master）。
3. ユーザーが GitHub の PR と issue を使う場合は、gh auth status を実行します。gh がない場合は、https://cli.github.com からインストールするようユーザーに伝えます。gh にログインしていない場合は、gh auth login を実行するよう伝えます。
4. Web の場合は、PLAYWRIGHT_SKIP_BROWSER_GC=1 npx -y [email protected] install chromium を実行します。バンドルで Playwright 1.48.2 に固定されているため、この正確なバージョンを使用してください。PLAYWRIGHT_SKIP_BROWSER_GC=1 はそのままにしてください。これがないと、Playwright がリポジトリ独自の Playwright バージョンのブラウザーを削除します。
5. iOS または Android の場合は、maestro --version を実行します。Maestro がない場合は、https://maestro.mobile.dev からインストールするようユーザーに伝えます。シミュレーターが起動している（xcrun simctl list devices booted）か、エミュレーターが実行中（adb devices）であることを確認します。
6. Electron の場合は、アプリが --remote-debugging-port=<port> を指定して起動し、起動コマンドがポートを出力することを確認します。
7. npx bugpatrol@latest --version を実行します。これにより、パッケージが動作することを確認できます。

2.3 自分自身を LLM として init を実行する

あなたは LLM エージェントなので、すべてのエージェントのプロバイダーとして自分自身を使用してください。そうすれば、ユーザーがエージェント用の API キーを用意する必要はありません。

1. 自分が使用している CLI 名を確認します。

   あなたが使用しているもの	--agent
   Claude Code	claude
   Codex	codex
   Kimi CLI	kimi
   opencode	opencode
   pi	pi（pi install npm:pi-mcp-adapter が必要です）

2. CLI が PATH 上にあることを確認します。例：command -v claude。

3. 別のエージェント（たとえば Cursor や Gemini）を使用している場合は、インストール済みの CLI のいずれかを使用します。どれもインストールされていない場合は、ユーザーに API キーのプロバイダーを確認し、--agent openrouter または --agent vercel を使用します。

4. ステップ 2.1 の起動コマンドと URL またはアプリ ID を指定し、リポジトリのルートで init を実行します。

   npx bugpatrol@latest init --yes --agent claude \
     --platform web --start "npm run dev" --url http://localhost:3000
   

   その他のフラグ：--app-id <id>（モバイル）、--explorer、--judge、--fixer（1 つのエージェントに別のプロバイダーを指定）。

init は次のファイルを書き込みます。既存のファイルを上書きすることはありません。

.bugpatrol/
  bugpatrol.yml     # the config: commit it
  instructions.md    # the app guide template: commit it
  runs/              # the local data: init adds .bugpatrol/runs/ to .gitignore

.bugpatrol/bugpatrol.yml がすでに存在する場合は、代わりにそのファイルを編集してください。プロジェクトのルートには bugpatrol.yml を書き込まないでください。Bugpatrol はそこから読み込みません。ルートに古いファイルがある場合は、npx bugpatrol@latest doctor を実行すると、移動するコマンドが表示されます。

2.4 .bugpatrol/bugpatrol.yml を正しく設定する

init が書き込んだファイルを読み、推測できなかった値を修正します。ファイル内のパス（source、cwd、instructions）は、.bugpatrol/ を含むフォルダーであるプロジェクトルートからの相対パスです。コマンドはプロジェクト内のどのフォルダーからでも実行できます。

開発サーバーを使う Web アプリ：

version: 1

app:
  platform: web
  source: .                          # the repo that the fixer edits
  setup:
    - run: npm run dev
      background: true               # keep the server alive for the session
      readyWhen: 'Local:|ready|listening'   # regex on the output; start when it matches
      timeoutMs: 120000
  connect:
    url: http://localhost:3000
  instructions: .bugpatrol/instructions.md
  secrets: [TEST_EMAIL, TEST_PASSWORD]   # env vars; the explorer sees {{TEST_EMAIL}}

ユーザーがすでにアプリを実行している場合、またはアプリがデプロイ済みの場合は、setup を省略し、connect.url のみを設定します。

Electron アプリ：

version: 1

app:
  platform: electron
  source: .
  setup:
    - run: ./scripts/start-test-app.sh
      capture: { CDP_PORT: 'CDP :(\d+)' }    # first regex group becomes ${CDP_PORT}
  teardown:
    - run: ./scripts/stop-test-app.sh
  connect:
    cdp: http://127.0.0.1:${CDP_PORT}
  instructions: .bugpatrol/instructions.md

iOS または Android アプリ：

version: 1

app:
  platform: ios                      # or android
  source: .
  setup:
    - run: npx expo start --port 8083
      background: true
      readyWhen: 'Waiting on http'
      timeoutMs: 180000
  connect:
    appId: com.example.app           # bundle ID (iOS) or package name (Android)
    # device: <simulator UDID or emulator serial>   # default: the booted one
  instructions: .bugpatrol/instructions.md

セットアップコマンドのフィールド：

フィールド	用途
run	シェルコマンド
cwd	プロジェクトルートからの相対パスで指定するフォルダー
capture	{ NAME: 'regex' }。最初のグループは、後続のコマンドと connect では ${NAME} に、エクスプローラーでは {{NAME}} になります。Bugpatrol はこれをシークレットとして扱います
background	プロセスが実行し続けるサーバーの場合は true
readyWhen	バックグラウンドコマンドの場合、その出力に対する正規表現
timeoutMs	制限時間。デフォルトは 600000 です

teardown には同じフィールドがあります。プロセスが自動終了しない場合は、setup で開始したプロセスを停止するために使用します。

2.5 .bugpatrol/instructions.md を作成する

このファイルには、エクスプローラー向けの平易な英語を記載します。init はテンプレートを書き込みます。新しい人間のテスター向けの説明に置き換えてください。これはリポジトリをもとにした初稿です。エクスプローラーがアプリを確認した後、実行するのステップ 3 で修正します。次の内容を含めてください。

• アプリの概要と主な画面について、1〜2 文で説明します。
• サインイン方法を記載します。シークレットには {{NAME}} プレースホルダーを使用します。このファイルに実際のパスワードは絶対に記載しないでください。
• アプリにオンボーディングがある場合は、その進め方を記載します。
• 特に重要なフローを記載します。
• 絶対にしてはいけないことのリストを記載します。

# Acme
Acme is a project tracker. The sidebar lists the projects. Each project has a board and a settings page.

## Sign in
Sign in with the email {{TEST_EMAIL}} and the password {{TEST_PASSWORD}}.

## Important flows
- Make a project, add three tasks, and move a task across the board.

## Never do these things
- Do not delete a project that you did not make.
- Do not invite a person by email.
- Do not open the billing page.

2.6 キーを確認する

設定されているキーを確認します。値は表示しません：

for k in OPENROUTER_API_KEY AI_GATEWAY_API_KEY OPENAI_API_KEY ANTHROPIC_API_KEY; do
  test -n "$(printenv $k)" && echo "$k set" || echo "$k missing"
done

• API キーを必要とするエージェント。 エージェントが runtime: model を使用する場合、そのキーを設定する必要があります。OpenRouter のキー：https://openrouter.ai/keys。Vercel AI Gateway のキー：https://vercel.com/ai-gateway。

キーが設定されていない場合は、シェルで設定するようユーザーに依頼してください。チャットにキーを貼り付けるよう求めてはいけません。

各エージェントのプロバイダーは agents.<role>.use にあります：

use:	プロバイダー	必要なもの
claude、codex、kimi、opencode、pi	ローカルエージェント CLI（ロールに適したフラグが設定されたプリセット）	PATH 上の CLI、ログイン済みであること
{ runtime: model, via: openrouter, model: z-ai/glm-5.3-flash }	OpenRouter	OPENROUTER_API_KEY
{ runtime: model, via: vercel, model: <id> }	Vercel AI Gateway	AI_GATEWAY_API_KEY
{ runtime: model, via: openai, model: <id> }	OpenAI	OPENAI_API_KEY
{ runtime: model, via: anthropic, model: <id> }	Anthropic	ANTHROPIC_API_KEY
{ runtime: model, via: custom, model: <id>, endpoint: <url> }	OpenAI 互換エンドポイント	BUGPATROL_MODEL_API_KEY
{ runtime: cli, command: '...' }	追加のフラグを指定できる完全なコマンド	PATH 上の CLI

ユーザーから使用するモデルについて尋ねられた場合は、この表からモデルを推奨してください。Judge には最も高性能なモデルを、Explorer には高速で低コストのモデルを割り当ててください。各エージェントに適したモデル に、各モデルの use: 設定があります。

エージェント	必要なもの	Anthropic	OpenAI	その他のラボ（OpenRouter）
Explorer	ビジョン、コンピューター操作、信頼性の高いツール呼び出し、低コスト	claude-sonnet-5	gpt-6-luna	google/gemini-3.8-flash
Judge	精度、細部まで捉える視覚能力、明確な文章	claude-opus-5-5	gpt-6-sol	moonshotai/kimi-k3
Fixer	エージェント CLI での高度なコーディング能力	claude と --model claude-opus-5-5	codex と -m gpt-6-astra	Kimi K3 を使う kimi

コマンドは、プロンプトを stdin と {prompt}（ファイル）で受け取り、ロールのツールを MCP 経由で {mcp}（設定ファイル）または {mcpUrl} から受け取り、ワークツリーを {workdir} から受け取ります。

各エージェントのコマンドがアプリを起動する前に、Bugpatrol は各エージェントの LLM を確認します。キーまたは CLI が見つからない場合、コマンドは停止し、修正方法を示します。

3. 実行する

各コマンドをプロジェクト内で実行します。Bugpatrol は、現在のフォルダーまたはその上位のフォルダーから .bugpatrol/ を見つけます。

1. まず、短いセッションを実行します。これにより、Bugpatrol がアプリを起動してサインインできることを確認できます。

   npx bugpatrol@latest explore --steps 10 --goal "Sign in, then open the main screen"
   

   出力を確認します。セットアップに失敗した場合、またはエクスプローラーがサインイン画面から先に進まない場合は、.bugpatrol/bugpatrol.yml または .bugpatrol/instructions.md を修正して、もう一度実行します。動作させられない場合は、そこで中止し、何に失敗したかをユーザーに伝えます。

   エクスプローラーがアプリのメイン画面に到達した場合にのみ続行します。オンボーディングで止まった場合は、テストアカウントの状態を確認します。

2. エクスプローラーのフルセッションを実行します。

   npx bugpatrol@latest explore
   npx bugpatrol@latest explore --goal "Test the checkout flow" --steps 40
   

   このコマンドは setup を実行し、アプリを探索して、レポートを作成し、teardown を実行します。数分かかる場合があります。出力を確認します。セットアップに失敗した場合は、.bugpatrol/bugpatrol.yml を修正して、もう一度実行します。

3. エクスプローラーが確認した内容をもとに、.bugpatrol/instructions.md を修正します。最初のドラフトはソースコードから作成しました。ここではエクスプローラーがアプリを使用したため、そのドラフトは誤っていたり、不完全だったりする可能性があります。

   1. .bugpatrol/appmap.json（画面とその接続方法）と、npx bugpatrol@latest memory list の出力（得られた教訓）を確認します。git が .bugpatrol/runs/ を無視するため、教訓はこのマシンにのみ残ります。エクスプローラーは各セッションの開始時に instructions.md を読み込み、このファイルはコミットされるため、各マシンで把握しておくべき内容をここに記載します。
   2. ファイルをもう一度作成します。
      • アプリに表示される名前で主要なエリアを記載し、それぞれへの移動方法を説明します。
      • サインインとオンボーディングの手順を、実際にうまくいった手順に修正します。
      • 画面から確認できたフローのうち、ドラフトに含まれていないものを追加します。
      • データの削除、実在の人物へのメッセージ送信、または金銭が発生する操作を見つけた場合は、その操作を 絶対に行わないこと のリストに追加します。
   3. 続行する前に、新しいファイルをユーザーに見せます。どのフローが最も重要か、また 絶対に行わないこと のリストに不足しているものは何か、2つの質問をします。これらについては、リポジトリよりもユーザーのほうが詳しいためです。
   4. 回答を反映します。シークレットには {{NAME}} プレースホルダーを使用します。

4. セッションを判定します。

   npx bugpatrol@latest judge
   

   ジャッジは候補を含む最近のエクスプローラーセッションを読み込み、すでに判定済みの候補はスキップします。最初の行には、対象セッションと新しい候補の数が表示されます。1つのセッションのみを判定するには、--session <id> を追加します。

5. 問題を表示します。

   npx bugpatrol@latest issue list
   

6. ダッシュボードをユーザーに表示します。ダッシュボードには、スクリーンショット、手順、画面グラフが表示されます。

   1. ダッシュボードがすでに起動しているか確認します。

      curl -fsS http://127.0.0.1:4311/api/overview > /dev/null && echo running
      

   2. 起動していない場合は、バックグラウンドで起動します。ダッシュボードは自動では停止しません。

      npx bugpatrol@latest dashboard
      

   3. Bugpatrol dashboard on http://127.0.0.1:4311 という行が表示されるまで待ちます。

   4. ユーザーのブラウザーで URL を開きます。macOS では open、Linux では xdg-open、Windows では start を使用します。

   5. どのページを確認するかユーザーに伝えます。ダッシュボードの表を参照してください。

   6. 短いテキストの要約も伝えます。重大度ごとの問題数と、critical または major の各問題のタイトルを含めます。

   7. 次の手順を伝えます。フィクサーを有効にする、GitHub を有効にする、またはパトロールを開始する、のいずれかです。フィクサーまたは GitHub を有効にする前に、ユーザーに確認します。

   セッションが終了すると、ダッシュボードはリアルタイムで更新されます。エクスプローラーの動作をユーザーが確認できるように、explore の前にダッシュボードを起動しておくこともできます。

任意：バグを修正させる

フィクサーはコードを書き換えるため、ユーザーの同意を得た場合にのみ有効にしてください。

agents:
  fixer:
    enabled: true
    minSeverity: minor
    commitMessage: 'fix(app): {title}'     # match the repo's commit style and hooks: read `git log --oneline`
    retest: { prepare: npm ci }            # installs the dependencies in each new worktree
    verify: npm run typecheck && npm test  # Bugpatrol runs this after each fix
    use: claude                            # or codex, kimi, opencode, pi

• prepare には、リポジトリのパッケージマネージャーのインストールコマンドを設定します。たとえば pnpm install --frozen-lockfile です。Bugpatrol は、フィクサーの開始前と再テストの前に、新しい各ワークツリーでこのコマンドを実行します。
• verify には、修正が合格すべきチェックを設定します。claude フィクサーのプリセットはファイルを編集できますが、コマンドを実行できません。そのため、Bugpatrol が verify を実行します。verify が失敗すると修正も失敗となり、フィクサーにはエラーとともに教訓が与えられます。次の修正試行では出力全体が渡され、同じ変更が修復されます。fixer.attempts（デフォルトは 3 回）を超えると、フィクサーはその問題の修正を諦めます。

npx bugpatrol@latest fix                     # fix the worst open issues, then retest each fix
npx bugpatrol@latest fix --issue <id>
npx bugpatrol@latest retest --issue <id>

このコマンドは、各修正のステータスとブランチを一覧表示します。フィクサーは .bugpatrol/runs/worktrees/ 内でのみ動作し、ユーザーのチェックアウトを変更することはありません。

再テスト後、各修正には判定が付きます。✅ 修正済み、❌ 未修正（フィクサーが再試行）、または ❔ 判定不能です。判定不能とは、再テストでエクスプローラーが画面に到達できなかったことを意味します。多くの場合、原因はテストアカウントの状態です。各修正の判定をユーザーに伝えてください。

任意：GitHub に公開する

GitHub への公開はチームのリポジトリに書き込むため、ユーザーの同意を得た場合にのみ有効にしてください。有効にする前に、何を行うかユーザーに伝えてください。

• 各修正について PR を作成し、修正がない issueMinSeverity 以上の各バグについて GitHub issue を作成します。
• bugpatrol ラベルを作成し、レポートのスクリーンショットを含む孤立ブランチ bugpatrol-assets をプッシュします。
• 各修正について、ブランチ bugpatrol/fix-<issue> を 1 つずつプッシュします。

リポジトリへのプッシュ権限がある、ログイン済みの gh CLI が必要です。gh auth status または npx bugpatrol@latest doctor で確認してください。

agents:
  github:
    enabled: true
    pullRequests: draft          # draft | ready
    issueMinSeverity: major

次の手順を順番に実行してください。

1. レポートをローカルに書き込みます。GitHub には何も送信されません。

   npx bugpatrol@latest publish --dry-run
   

2. 下書きの一覧をユーザーに表示し、.bugpatrol/runs/publish/ 内にある各下書きファイルのパスを伝えます。

3. 公開してよいかユーザーに尋ねます。公開するのは、同意を得てからにしてください。

   npx bugpatrol@latest publish
   

4. 各 PR と issue の URL をユーザーに伝えます。コマンドが URL を出力します。

5. 各 PR のチェックがすべて成功するまで CI を監視します。チェックが失敗した場合、フィクサーが修正して新しいコミットをプッシュします。

   npx bugpatrol@latest ci --wait
   

   出力に A person must look at it と表示された場合は、PR の URL と失敗したチェックの名前をユーザーに伝えてください。

GitHub から PR と issue の状態を読み戻すには、npx bugpatrol@latest github sync を実行します。チームがマージせずにクローズした PR は教訓となり、チームが「予定なし」としてクローズした issue は却下として扱われます。詳しいリファレンス：https://github.com/agent-labs-dev/bugpatrol/blob/main/docs/github.md

オプション：プルリクエストをレビューする

review は、実行中のアプリでチームのプルリクエストを 1 件テストします。プルリクエストのコミットとそのマージベースからアプリを起動し、両方で同じフローを繰り返して、GitHub レビューを投稿します。プルリクエストによって引き起こされた問題はそれぞれ、その原因となった変更行へのコメントになります。agents.review.block が有効で、リプレイによって主張が 2 回否定されない限り、レビューがマージを妨げることはありません。

npx bugpatrol@latest review <pr> --dry-run   # write the review to .bugpatrol/runs/reviews/pr-<pr>.md
npx bugpatrol@latest review <pr>             # post the review; it edits the same PR comment on each push

• ログイン済みの gh が必要です。レビューを投稿するには、agents.github.enabled: true も必要です。
• このマシン上で、アプリのシークレットを使ってプルリクエストのコードを実行します。フォークからのプルリクエストは拒否されます。ユーザーが差分を確認して承認した後にのみ、--allow-fork を追加してください。
• 同じマシンでパトロールが実行中の場合は開始しません。
• まず --dry-run を実行して、ファイルをユーザーに見せ、承認を得てから投稿してください。
• --claims（または agents.review.claims: true）を指定すると、プルリクエストが実行すると述べている内容も一覧表示されます。説明にある ## Claims リストから取得し、なければタイトル、説明、コミット、クローズ済みの Issue から取得します。Bugpatrol は各主張のフローを両方のビルドでリプレイし、各主張に証拠付きの判定（proven、not-proven、partly-proven、untested）を付けます。証拠には、判定時にジャッジが参照したものや、リプレイ画面も含まれます。主張のルーチンは .bugpatrol/runs/reviews/pr-<n>/ に保存されます。Web、Electron、iOS、Android では、ffmpeg が PATH にある場合、Bugpatrol は各リプレイを録画し、レビューに両方のビルドの GIF と、完全版の MP4 へのリンクを表示します。ffmpeg がない場合はスクリーンショットを表示します。クローズ済みの Bugpatrol Issue は、モデルを使わず、証拠 replay で判定する独自の主張になります。コミット済みの再現ルーチンを両方のビルドでリプレイし、ベースビルドではバグチェックが成功し、プルリクエストのビルドでは失敗する必要があります。ベースビルドでバグが再現しない場合は untested になります。cli アプリでは、各ステップでターミナル内のコマンドを実行します（python3 が必要です）。エクスプローラーは終了コードと出力に対する厳密なチェックを追加でき、それらのチェックによって証拠 assertion の判定が決まります。レビューには各ターミナルセッションの GIF が表示されます。GIF は ffmpeg なしで描画され、.cast ファイルへのリンクも表示されます。api アプリでは、最後のレスポンス（ステータスコード、本文内のテキスト）をチェックします。レビューには各ビルドの HTTP トランスクリプトが同じ方法で表示され、認証情報は伏せられます。cli または api アプリで動作が変わらないこと（リファクタリング、新しいページネーションなど）を主張する場合は、両方のビルドで同じコマンドまたはリクエストをリプレイし、時刻、UUID、16 進 ID、Unix 時刻、期間、JSON キーの順序を正規化した後、出力を比較します。出力が等しければ proven、差分があれば変更行とともに not-proven となり、証拠は assertion です。ブロッキングが有効な場合は、両方のビルドで 2 回目のリプレイを行い、差分が再現される必要があります。
• agents.review.block: true を設定すると、Bugpatrol claim check チェックランが設定されます（トークンには checks: write が必要です）。モデルを使わずコードで判定された、証拠が replay または assertion の not-proven な主張が、2 回目のリプレイでも繰り返された場合に限り失敗し、review は 1 で終了します。再現と動作不変の主張は、両方のビルドで 2 回目のリプレイを行います。2 回目のリプレイでコード判定の結果が変わった場合、その主張は untested（「不安定なリプレイ」）になります。ジャッジによる判定でチェックが失敗することはありません。

詳細なリファレンス：https://github.com/agent-labs-dev/bugpatrol/blob/main/docs/github.md#7-review-a-pull-request

オプション：終日実行する

npx bugpatrol@latest patrol --once       # one full cycle: setup, explore, judge, teardown, fix, retest, publish
npx bugpatrol@latest patrol --once --force  # the same, also when the commit did not change
npx bugpatrol@latest patrol              # repeat every agents.patrol.intervalMinutes (default 30); a cycle runs only when origin/main has a new commit

patrol は自動では停止しません。バックグラウンドまたは別のターミナルで実行してください。

4. 結果を確認する

ダッシュボード

npx bugpatrol@latest dashboard               # http://127.0.0.1:4311
npx bugpatrol@latest dashboard --port 5000

ダッシュボードは自動では停止しません。バックグラウンドで実行し、URLをユーザーのブラウザーで開いて、ユーザーにURLを伝えてください。127.0.0.1のみで待ち受け、読み取り専用です。ポート4311が別のプログラムで使用されている場合は、--portを追加してください。

ページ	表示内容	ユーザーからこのように尋ねられた場合に表示
概要	各エージェントが現在行っていることと、その費用、人の対応が必要な問題、ライブ画面、これまでに見つかった画面	「Bugpatrolは何をしていますか？」
問題	各問題のスクリーンショット、手順、判定者の理由、修正差分、修正前後の再テスト、GitHubの状態	「どんなバグが見つかりましたか？」「修正はうまくいきましたか？」
アクティビティ	各セッションのタイムライン	「エクスプローラーは何をしましたか？」
画面	画面とそのつながりを示すグラフ	「アプリのどの部分をテストしましたか？」
メモリ	エージェントが学習した内容	「私のアプリについて何を知っていますか？」

ターミナル

コマンド	用途
npx bugpatrol@latest issue list	問題を重大度の高い順に表示
npx bugpatrol@latest issue dismiss <id> --reason "..."	バグではないとして問題を閉じます。再び表示されることはありません
npx bugpatrol@latest issue reopen <id>	却下した問題を再び開きます
npx bugpatrol@latest memory list	エージェントが学習した内容
npx bugpatrol@latest memory add --role explorer "text"	たとえばアプリについてのヒントなど、学習内容を追加
npx bugpatrol@latest replay <routine-id>	モデルを使わずに、学習済みのルーチンを再生
npx bugpatrol@latest worktrees clean	完了した修正のワークツリーを削除

ファイル

ユーザーに結果を要約するには、次のファイルを読み取ってください。

パス	内容
.bugpatrol/runs/issues/<id>.json	1件の問題：title、severity、status、body（判定者のレポート）、judgement.reason、evidence（スクリーンショット）
.bugpatrol/runs/fixes/<id>.json	1件の修正：status、branch、diff、retests、pr
.bugpatrol/runs/reviews/pr-<number>.json	1件のプルリクエストに対する最新のレビュー：それぞれにverdictを含むfindingsと、posted.url
.bugpatrol/runs/sessions/<id>/	1件のエクスプローラーセッションとそのスクリーンショット
.bugpatrol/appmap.json	エクスプローラーが見つけた画面。コミットしてください
.bugpatrol/routines/<id>.json	ルーチンと、各問題の再現ルーチン（repro-<hash>）。コミットしてください
.bugpatrol/runs/memory.json	学習内容

重大度は、重大な順にcritical、major、minor、cosmeticです。

問題の状態	意味
new	判定者が登録した問題です。GitHubには登録されていません
filed	GitHubに登録されています
fixing	現在、修正担当が対応しています
fix-proposed	修正案がレビュー待ち、またはプルリクエスト待ちです
fixed	修正が検証済み、または問題が完了としてGitHub上でクローズされました
dismissed	人またはGitHubがバグではないとしてクローズしました。再び表示されることはありません

各session.jsonのcostUsdには、Bugpatrolが行うAPI呼び出し（runtime: modelエージェント）の費用のみが記録されます。ローカルのエージェントCLI（claude、codex、kimi、opencode、pi）はユーザー自身のプランを使用するため、Bugpatrolにはその費用はわかりません。

各session.jsonには、tokensとtokensByModelも含まれています。概要ページには、過去7日間のエージェント別およびモデル別のトークン使用量テーブルが表示されます。ユーザーが費用について尋ねた場合や、モデルを比較したい場合は、このテーブルを表示し、セッションごとのトークン数を伝えてください。

ルール

• リポジトリの package.json に bugpatrol が記載されていない限り、CLI は npx bugpatrol@latest として実行してください。
• アプリの起動方法とサインイン方法が明確に定義されていない場合は、先に進まないでください。方法がわからない場合は、ユーザーに確認してください。
• シークレットの値を表示、ログ出力、コミットしてはいけません。シークレットは環境変数に設定し、その名前を app.secrets に記載してください。
• ユーザーが安全だと言わない限り、Bugpatrol を本番データに接続してはいけません。
• agents.fixer または agents.github を有効にする前に、ユーザーに確認してください。
• .bugpatrol/runs/ 内のファイルを手動で編集してはいけません。CLI コマンドを使用してください。
• 人が問題を却下した場合や PR をクローズした場合、その判断を覆してはいけません。

トラブルシューティング

問題	対処方法
Web driver requires app.connect.url or run.url	app.connect.url を設定してください
セットアップがタイムアウトする	readyWhen 正規表現を修正するか、timeoutMs を増やしてください
Playwright が Chromium を見つけられない	PLAYWRIGHT_SKIP_BROWSER_GC=1 npx -y [email protected] install chromium を実行してください
エクスプローラーがサインイン画面から進まない	.bugpatrol/instructions.md に、より明確なサインイン手順を記述し、シークレットが設定されていることを確認してください
Electron が接続されない	アプリが CDP ポートを開くこと、および capture が出力からポートを読み取ることを確認してください
モバイルが接続されない	シミュレーターを起動するかエミュレーターを開始し、maestro --version と connect.appId を確認してください
No .bugpatrol/bugpatrol.yml found	プロジェクトのルートで npx bugpatrol@latest init を実行してください
Bugpatrol now keeps its config in .bugpatrol/	古いバージョンでは設定がルートに保存されていました。メッセージ内のコマンドを実行してください
Judging 0 new candidate(s)	これらの候補は判定済みです。新しい候補を見つけるには、再度 explore を実行してください
エクスプローラーがオンボーディングにステップを費やしている	テストアカウントの状態をお読みください
再テストの判定が ❔ 不明確	再テストでエクスプローラーが画面に到達しませんでした。テストアカウントの状態を確認してください
GitHub is off または The fixer is off	ユーザーに確認してから、agents.github.enabled または agents.fixer.enabled を true に設定してください
explore の後に問題が見つからない	npx bugpatrol@latest judge を実行してください。判定エージェントが問題を登録します
開始時に ... is not set または ... is not on PATH と表示される	キーを設定するか、CLI をインストールするか、agents.<role>.use を変更してください

ドキュメント全文：https://github.com/agent-labs-dev/bugpatrol/tree/main/docs