Claude CodeでPixelRAGを使う方法【2026年8月版】ビジュアルRAGで表・図解入り文書を検索！

2026年8月3日

「PixelRAG」はWebページやPDF、画像をテキストではなく“スクリーンショット”として扱い、表やグラフのレイアウトを保ったまま検索・参照できるビジュアルRAGツールです。

この記事ではプラグイン経由でのインストールから実際の使い方、通常のテキストベースRAGとの使い分け、つまずきやすいポイントまで、Claude Codeユーザー向けに実践的に解説します。

この記事で分かること

Claude Codeを業務で使っている中級エンジニア
ドキュメントの表・図解・レイアウトを含めて検索・理解したい人
通常のテキストRAG（Embedding + ベクトルDB）との違いを知りたい人

PixelRAGとは何か

PixelRAGは、ウェブページやPDF、画像などのドキュメントをスクリーンショットとしてレンダリングし、その画像をそのままモデルに読み込ませます。HTML解析では失われてしまう視覚的構造——表、チャート、レイアウト、インフォグラフィックなど——がそのまま保持されるため、読解モデルはそれらに関する質問にも実際に答えることができるのです。

PixelRAGの内部構成は「Visual Retrieval-Augmented Generation」を掲げるOSSで、次の5つのパッケージで構成されています。

パッケージ	役割
`pixelrag-render`	ドキュメント（Webページ・PDF）を画像タイルに変換（Playwright/CDP）
`pixelrag-embed`	タイル画像をベクトル化してFAISSインデックスを構築
`pixelrag-index`	source → ingest → embed → index の一連のパイプラインを実行
`pixelrag-serve`	FAISS検索APIを提供（CPU/GPU対応）
`pixelrag-train`	Qwen3-VL-EmbeddingをLoRAでファインチューニング

このうちClaude Codeユーザーが最初に触れるのは、pixelrag-renderが提供するpixelshotコマンドと、それをClaude Codeに組み込む「pixel browse」プラグインです。

通常のテキストRAGとの違い

表の行と列の対応関係（テキスト抽出だと崩れやすい）
グラフ・図解・インフォグラフィックの内容そのもの
レイアウトが持つ意味（強調、注釈の位置関係など）

PixelRAG導入のステップ

PixelRAGの導入はシンプルで、リポジトリをクローンして実行するか、マーケットプレイス経由でプラグインを追加するかの2通りです。まずは公式の導入スクリプトの内容を確認しましょう。

導入前の準備

Python 3.12以上（pyproject.tomlのrequires-pythonより）
Claude Code CLIがインストール済みであること
ライセンス: Apache-2.0（商用利用可）
注意: リポジトリのpyproject.tomlにはenvironments = ["sys_platform == 'linux'"]という記述があり、GPUを使うembed/serve/train系の依存関係はLinux前提です。スクリーンショット機能（pixelshot）のみを使う分には影響は小さいと考えられますが、Mac/WindowsではWSL経由の利用が無難です。
コスト目安: pixelshotによるスクリーンショット機能はローカルでPlaywright/Chromiumを動かすだけなので追加費用はかかりません。Claude Codeの通常利用分のトークン課金のみです。ただし、自前でインデックスを構築するembed/serve/trainはGPUが必要になり、クラウドGPUを使う場合はその利用料が別途発生します。

インストール手順

PixelRAGのインストール手順は以下の通りです。

PixelRAGのインストール

公式のplugin/setup.shからセットアップを開始します。

#!/bin/bash
# pixelragをインストールし、Claude Codeにプラグインとして登録するワンライナー
set -e

# uv経由で隔離環境にpixelragをインストール
uv tool install --from "$REPO_DIR" pixelrag 2>/dev/null || \
    uv tool upgrade --from "$REPO_DIR" pixelrag

# スクリーンショット用にChromiumを導入
uvx playwright install chromium 2>/dev/null || true

リポジトリをクローンしてローカル実行（方法1）

git clone https://github.com/StarTrail-org/PixelRAG.git
cd PixelRAG
./plugin/setup.sh
claude --plugin-dir ./plugin

方法2: マーケットプレイス経由でインストール（方法2）

pip install pixelrag                                # pixelshotコマンドが入る
claude plugin marketplace add StarTrail-org/PixelRAG
claude plugin install pixelbrowse@pixelrag-plugins

プラグインを使用する場合は、Claudeに「pixelshotをBashで呼び、生成された画像をReadツールで読む」手順を教える構成になります。

Claude CodeでのPixelRAG使い方

インストール後は、通常の会話でURLを渡すだけで動くようになっています。

bash
claude -p "https://news.ycombinator.com を見て、上位の記事を要約して"

インタラクティブセッションではスラッシュコマンドも使えます。

claude --plugin-dir ./plugin
# セッション内で
/screenshot https://example.com

内部的には、Claudeが次のようなpixelshotコマンドをBash経由で実行します。

bash
# URLをスクリーンショット（Claudeの視覚モデル向けにタイル高さ1568pxで最適化）
pixelshot https://example.com --output /tmp/pixelbrowse --tile-height 1568 --wait-network-idle

# 複数URLを並列処理
pixelshot url1 url2 --output /tmp/pixelbrowse --tile-height 1568 --wait-network-idle --workers 4

# PDFのレンダリング
pixelshot document.pdf --output /tmp/pixelbrowse

出力は/tmp/pixelbrowse/<ドメイン名>.png.tiles/tile_0000.jpgのような命名規則で保存され、Claudeがそれを画像として読み込んで内容を理解します。

つまずきやすいポイント・エラー対処と活用シーン

以下のQ&Aは、公式SKILL.mdに明記されている実務上重要な注意点です。

--wait-network-idleを付け忘れると空白ページになる: JavaScriptで描画するサイトは、ページの読み込み完了前にキャプチャされると中身が空のまま撮影されます。URLを対象にする場合は必ず付与する必要があります。
--tile-heightは1568px固定が推奨: Claudeの視覚モデルは長辺1568px（Sonnet/Haiku）または2576px（Opus）を超える画像を縮小してから処理するため、デフォルトの8192pxのままだと文字が潰れて読めなくなります。
文字が小さくて読めない場合はクロップして再読み込み: Pillowで該当領域を切り出し、再度Readツールで読み込むワークフローが公式に案内されています。

PxelRAGの活用シーン

表やグラフを含む仕様書・IR資料など、テキスト抽出だと崩れる文書の検索
自社サイトのUI崩れチェック（screenshot http://localhost:3000 and tell me if anything looks brokenのような指示）
論文やスキャンPDFなど、レイアウトに意味がある文書の理解