ritoko

Ritoko — AI エージェント向けの再開可能なブラウザー自動化

タスクを一度解決して、手順を保存し、新しいデータで再実行できます。

Ritoko は、AI エージェント向けのオープンソースのブラウザー自動化およびロボティック・プロセス・オートメーション（RPA）ツールです。解決したタスクを、再利用可能なブラウザー、HTTP API、または MCP ワークフローに変換し、CSV や Excel のバッチを実行して結果を検証できます。また、ローカルの SQLite ジャーナルを使って、中断した作業を再開できます。

Claude Code または Codex のプラグイン、ローカルの Model Context Protocol（MCP）サーバー、またはスタンドアロンの CLIとして使用できます。直接リプレイエンジンは、LLM を呼び出さずに保存済みのワークフローを実行します。接続された MCP ツール自体は AI を使用する場合があります。

ローカルで試す · クイックスタート · ユースケース · 仕組み · ワークフローの例 · FAQ · 詳細ガイド

34 秒のデモを見る — ローカルのテストアプリケーションでリアルタイムに実行します。5 件目の送信後にプロセスを終了して再開し、同じ CSV を再実行します。送信を 10 件受け付け、すべて一意で、1 行は確認待ちのままです。記録された結果と環境。

Ritoko を使う理由

エージェントは、顧客情報の入力、レポートのダウンロード、業務ツールの呼び出し方法を見つけ出せます。繰り返し実行するバッチには、入力形式、各レコードを特定するルール、成功を確認する方法、中断後の復旧方法も必要です。

Ritoko は、それらの判断を再利用可能な手順として保持します。

• 作業を再利用できます。 パラメーター、セレクター、API 呼び出し、検証ルールを、読みやすい JSON ワークフローに保存します。
• 新しいデータを処理できます。 各行について同じ手順を説明し直す代わりに、別の CSV または Excel ファイルを手順に入力します。
• 証拠に基づいて復旧できます。 完了、失敗、結果が不確かな項目を確認できます。確認済みの項目は後続の実行でスキップされ、不確かな書き込みはレビュー用に保留されます。

宛先検索を設定すると、Ritoko はレコードの作成前に確認（ensure）し、読み戻しによって不確かな結果を確定（reconcile）することもできます。これらの 0.2.0 の機能には、直接の HTTP GET、または信頼できる明示的な読み取り専用 MCP ツールが必要です。また、存在と不在を証明する個別のルールも必要です。検索に失敗した場合、その行は処理されません。設定と制限。

たとえば、エージェントに顧客を 1 件作成する方法を教えて customer-import として保存し、翌週のスプレッドシートを処理して各結果を報告するよう依頼できます。

自動化できること

Ritoko は、明確なルールと検証可能な結果がある、繰り返しのタスクに適しています。新しいタスクでは、エージェントまたはワークフローの作成者がサイトの仕組みを理解し、手順を定義する必要があります。

クイックスタート

偽の顧客 10 件をローカルで試す

空のディレクトリで Node.js 24 以降を使います。

npm install [email protected]
node node_modules/ritoko/examples/first-run/demo.mjs

このデモでは、ループバック HTTP サービスを起動し、偽の顧客 10 件を含む CSV を作成して、各レコードを読み戻して検証します。その後、再実行して 10 行すべてが追加書き込みなしでスキップされることを確認します。アカウント、API キー、Chrome は不要です。ジャーナルはコマンドが表示する一時ディレクトリに分離されます。これはローカルシミュレーションのテストです。ブラウザーの中断と送信先との照合は別のテストです。英語／フランス語のガイドと期待される結果。

公開されている npm 0.2.0 には、このデモと ensure、reconcile、doctor の各機能が含まれています。

1. エージェントにインストールする

Node.js 24 以降が必要です。直接ランナーを使うブラウザーワークフローでは、Google Chrome も必要です。スタンドアロンの HTTP／MCP ワークフローはブラウザーなしで実行できます。

ensure、reconcile、doctor、初回実行デモには 0.2.0 以降が必要です。固定バージョンでインストールした環境をアップグレードする前に、バージョン別リリースとリリースゲートを確認してください。

Claude Code

claude plugin marketplace add Swih/ritoko
claude plugin install ritoko@ritoko

Codex CLI

codex plugin marketplace add Swih/ritoko
codex plugin add ritoko@ritoko

インストール後、クライアントを再起動してください。Git プラグインにはエージェントスキルとローカル MCP サーバーが含まれています。ランチャーは初回起動時に、npm のライフサイクルスクリプトを無効にした状態で、固定バージョンのランタイム依存関係をインストールします。

長時間の Codex バッチを実行する場合は、実行前にツール呼び出しのタイムアウトを設定してください。

{
  "mcpServers": {
    "ritoko": {
      "command": "npx",
      "args": ["--yes", "--prefer-online", "ritoko@latest", "mcp"]
    }
  }
}

2. ブラウザーまたは連携方法を選ぶ

使用するブラウザーをエージェントに伝えてください。直接ランナーは、chrome://inspect/#remote-debugging でリモートデバッグを有効にし、接続を許可した後、個人用 Chrome に接続します。別のプロファイルを使う場合は、明示的に RITOKO_BROWSER=clean を選択してください。

ホストページのスクリプト実行を許可する場合、互換性のあるエージェントブラウザーでホストワークフローを実行できます。**Codex の現在のコンピューター操作機能の evaluate は読み取り専用のため、ホストブラウザーの再生を実行できません。**ホスト上での API のみのバッチと、接続済み MCP ツールのバッチは引き続き利用できます。ブラウザーの選択と信頼境界を参照してください。

3. 1 つのタスクを教えて、再利用する

エージェントに次のように依頼します。

このバックオフィスで、Ritoko を使って顧客のインポートを記録してください。私が選択したブラウザーを使用してください。input スプレッドシートパラメーターを指定して、customer-import として保存してください。ビジネスキーにはメールアドレスを使い、作成された顧客のメールアドレスを確認してください。

デモで実際のレコードが作成された場合、バッチを再実行する前に、run_adopt と証拠を使って、すでに送信されたその行をエージェントが引き継ぐ必要があります。

続けて、次のように依頼します。

同じバックオフィスで customer-import を実行し、input には customers.csv の絶対パスを指定してください。確認済み、失敗、レビューが必要な項目と、保存されたファイルがあれば表示してください。

後で、次のように依頼できます。

Ritoko の最後の実行を再開してください。

最後の実行のレポートを表示し、まだレビューが必要な項目を説明してください。

仕組み

flowchart LR
    A["Describe a task"] --> B["Agent records or authors it"]
    B --> C["Save a JSON workflow"]
    C --> D["Replay with new data"]
    D --> E["Journal and verify each item"]
    E --> F["Report results and review holds"]

1. 定義。 エージェントはブラウザーの操作を記録するか、サポートされている API／MCP のステップを記述します。レコーダーは、一意のラベル、ロール、その他の意味のあるセレクターを優先します。壊れやすい位置指定セレクターには警告が表示されます。
2. 保存。 ワークフローには、パラメーター、入力、ビジネスキー、送信境界（commit）、結果チェック（expect）を宣言します。
3. 再実行。 ダイレクトエンジンが保存済みのステップを実行します。ホストモードでは、互換性のあるエージェントがサポート対象のブラウザー操作や接続済みのツールを実行できます。
4. 記録と復旧。 SQLite に各実行のワークフローと入力行が保存されます。バッチを再開すると、元のスプレッドシートが変更されていても、そのスナップショットが使われます。ページが変更されると修復のために一時停止することがあります。送信が行われたか不確かな場合は、レビューのために保留されます。

失敗した場合はどうなりますか？

すべての項目が確認済みまたはスキップ済みで、最終チェックに合格した場合にのみ、実行は完了となります。部分的な結果や修復のための一時停止はレポートに表示され、CLI の終了コード 2 が返されます。

検証の品質が重要です。 領収書、レコード ID、または顧客のメールアドレスの一致は、意図した結果の証拠になります。一方、一般的な「成功」バナーだけでは、通常は証拠になりません。ジャーナルはこの Ritoko のインストール環境での実行を追跡しますが、独立した送信を防いだり、リモートサイトの冪等性を保証したりするものではありません。

ワークフローはどのようなものですか？

この例示用ブラウザーワークフローでは、スプレッドシートの各行につき 1 人の顧客を作成します。保存する前に、URL、ラベル、結果セレクターをアプリケーションに合わせて変更してください。

{
  "name": "customer-import",
  "version": 1,
  "description": "Create customers and verify their email.",
  "params": {
    "base": { "description": "Back-office base URL" },
    "input": { "description": "Absolute CSV or XLSX path" }
  },
  "items": {
    "from": "{{param.input}}",
    "key": "{{item.Email}}",
    "scope": "{{param.base}}"
  },
  "item": [
    {
      "do": "goto",
      "url": "{{param.base}}/customers/new"
    },
    {
      "do": "fill",
      "target": { "primary": { "by": "label", "text": "Email" } },
      "value": "{{item.Email}}"
    },
    {
      "do": "click",
      "target": {
        "primary": { "by": "role", "role": "button", "name": "Create customer" }
      },
      "commit": true
    },
    {
      "do": "expect",
      "target": { "primary": { "by": "testid", "id": "customer-email" } },
      "text": "{{item.Email}}"
    }
  ]
}

key は業務レコードを識別します。この例では、宛先 URL を分けるために scope を使用しています。複数のアカウントで同じ URL を共有する場合は、アカウント識別子をスコープに含めてください。commit は取り消せない操作を示し、その後の expect は該当する行をチェックします。読み取り専用のバッチでは、readOnly: true を宣言してください。

完全なワークフローの例、ワークフローのスキーマ、HTTP／MCP リファレンスを参照してください。

エージェントなしで CLI を使う

Git チェックアウトから、ランチャーはエージェントや LLM API キーなしで既存のワークフローをインポートして実行できます。

git clone https://github.com/Swih/ritoko.git
cd ritoko
node bin/ritoko.mjs import examples/rpa-challenge.json
node bin/ritoko.mjs run rpa-challenge
node bin/ritoko.mjs report

RPA Challenge の例では、独自の Excel 入力ファイルをダウンロードします。実行前に、上記の説明に従ってダイレクトブラウザーを選択してください。このチャレンジを意図的に再度実行するには、--repeat を追加してください。レビュー保留中の項目は引き続きブロックされます。

中断したダイレクト実行を再開するには、node bin/ritoko.mjs resume <runId> を使用してください。ワークフロー、ジャーナル、証拠、出力ファイルはデフォルトで ~/.ritoko に保存されます。RITOKO_HOME で保存先を変更できます。

バッチのトラブルシューティングを行う前に、node bin/ritoko.mjs doctor を使ってローカル環境を確認してください。設定済みの宛先検索があるレビュー行については、node bin/ritoko.mjs reconcile <runId> <key> を使うと、再送信せずに結果を読み取れます。手動で resolve する場合は、宛先を自分で確認したうえで、メモと --confirm-checked が必要です。

証拠と現在の対象範囲

記録されたデモでは、Windows 上のヘッドレス Chrome で Ritoko 0.1.0 を使用しました。RPA サイトのタイマーにはインストールとセットアップの時間は含まれていません。記録された CLI の実経過時間は 3.559 秒でした。RPA Challenge には行ごとの受領確認がないため、この例では最終スコアを使用しています。これらのデモと管理されたテストは、すべてのウェブサイトにおける信頼性や処理量を示すものではありません。

FAQ

別途 LLM API キーが必要ですか？

Ritoko の決定論的なランナーには必要ありません。プラグインを使用する場合、クライアントエージェントは既存のサブスクリプションまたは API 設定を通じて推論を行います。記録、修復、ホストのオーケストレーションにも引き続きそのクライアントを使用し、接続されたツールが独自にモデルを呼び出す場合もあります。外部 API、OCR プロバイダー、有料の生成サービスには、それぞれ個別のアクセス権が必要で、別途料金がかかる場合があります。

Ritoko は請求書を読み取ったり、OCR を実行したりしますか？

ドキュメントの読み取りは任意です。document_image は、ダウンロードした JPEG/PNG をクライアントエージェントに返し、モデルが読み取れるようにします。Ritoko にはローカル OCR エンジンや請求書パーサーは含まれていません。選択した外部 OCR サービスを使う場合は、ユーザーが設定した認証情報を使用します。新しい画像ごとに、引き続きエージェントまたはそのサービスが必要です。通常のブラウザーおよび API の再生には必要ありません。

ログイン済みのブラウザーで Ritoko を使えますか？

ダイレクトランナーは、リモートデバッグの許可があれば個人用 Chrome に接続できます。別のクリーンなプロファイルを明示的に選択することもできます。統合ブラウザーのサポートは、クライアントで許可されている操作によって異なります。ドライバーの制限を参照してください。必要に応じて、選択したブラウザーでログインまたは MFA を完了してください。

どの MCP クライアントでも Ritoko を使えますか？

stdio プロセスを起動できるローカルクライアントは、サーバーに接続できます。テスト済みのプラグインクライアントは Claude Code と Codex CLI です。その他のクライアントでは、設定と機能の確認が必要です。隔離されたクラウドクライアントは、別の接続手段がない限り、ローカル MCP プロセスやファイルにアクセスできません。

Ritoko は重複書き込みが発生しないことを保証しますか？

いいえ。ジャーナル内で確定済みの項目はスキップし、不確実な書き込みはブロックします。この処理は次回以降の実行でも適用されます。ワークフローには、正しい業務キー、宛先のスコープ、結果の確認が必要です。個別の送信やリモートシステムの動作は、このジャーナルの対象外です。レビュー項目を解決するには、実際に何が起きたかを示す証拠が必要です。

ブラウザーの記録から API ワークフローを作成できますか？

オプションのネットワークキャプチャでは、エージェントが API を調査するための fetch/XHR メタデータを取得できます。記録が実行可能な API ステップに自動変換されるわけではありません。API の仕様と認証を確認し、許可された行をテストしてから、置き換え後の内容を明示的に保存してください。ネットワークヒントをご覧ください。

ドキュメントとコントリビューション

• 高度な使い方：クライアントの設定、CLI、ブラウザーの選択、ホストの一括処理、復旧、ワークフローのルール。
• エージェントスキル：ワークフローの記録、実行、採用、修復に関する手順。
• 統合リファレンス：入力形式、HTTP/MCP ステップの形式、ドライバーの制限。
• 問題別ガイドとツールの比較：ワークフローを選び、そのトレードオフを理解するための情報。
• 検索可視性の測定：固定の英語／フランス語プロンプトと、取得した回答に基づくレポート。
• リリースゲート：必須チェック、検証ロードマップ、公開、更新ポリシー。
• ローカルソフトウェアのプライバシー：保存される実行データ、設定済みの宛先、認証情報、保持期間。
• バグの報告または機能のリクエスト：クライアント、Node／ブラウザー／OS のバージョン、機密情報を除いた再現手順を記載してください。認証情報と業務データは非公開にしてください。

開発には Node.js 24+ と pnpm を使用してください。

pnpm install
pnpm check
pnpm test
pnpm build
pnpm test:e2e

Ritoko は、使用する権限のあるサービスを自動化します。CAPTCHA やボット対策を回避することはありません。ワークフローと API/MCP コマンドは実行可能な設定であり、信頼できる作成者によるものである必要があります。

Swih が Claude (Anthropic) および Codex (OpenAI) とともに開発し、Git 履歴では貢献者として記録されています。MIT ライセンスのもとで公開されています。