Using PixelRAG with Claude Code (August 2026) — Visual RAG for Documents with Tables and Diagrams

PixelRAG, an open-source visual retrieval-augmented generation tool, treats documents as screenshots to preserve layout and structure for AI models. The project, built by StarTrail-org, includes components for rendering, embedding, indexing, serving, and training, and integrates with Claude Code via a plugin. It enables visual understanding of tables, charts, and infographics, differing from traditional text-based RAG.

PixelRAG is a visual RAG tool that treats web pages, PDFs, and images as screenshots rather than text — preserving the layout of tables and charts so you can search and reference them as-is. This post covers installing it as a plugin, actual usage, how it differs from traditional text-based RAG, and the gotchas you're likely to hit — all from a Claude Code user's perspective. What you'll get out of this post PixelRAG renders documents — web pages, PDFs, images — as screenshots and feeds those images directly to the model. The visual structure that HTML parsing normally destroys — tables, charts, layout, infographics — stays intact, so the model can actually answer questions about them. PixelRAG is an open-source project built around "Visual Retrieval-Augmented Generation," made up of 5 components: | Component | Role | |---|---| pixelrag-render | Converts documents web pages, PDFs into image tiles via Playwright/CDP | pixelrag-embed | Vectorizes tile images and builds a FAISS index | pixelrag-index | Runs the full source → ingest → embed → index pipeline | pixelrag-serve | Serves a FAISS search API CPU/GPU | pixelrag-train | Fine-tunes Qwen3-VL-Embedding via LoRA | These are all now bundled into a single pixelrag package, installable with one pip install pixelrag . As a Claude Code user, the first thing you'll actually touch is the pixelshot command shipped by pixelrag-render and the "pixelbrowse" plugin that wires it into Claude Code. php flowchart LR A URL / PDF -- B "pixelshot<br/ generates image tiles " B -- C "tile 0000.jpg ..." C -- D "Claude Code's Read tool" D -- E "Claude understands it visually" C -.- |optional| F pixelrag-embed / index F -- G FAISS index G -- H pixelrag-serve search API How this differs from traditional text RAG Setup is straightforward: either clone the repo and run it locally, or add the plugin via the marketplace. requires-python in pyproject.toml pyproject.toml includes environments = "sys platform == 'linux'" , meaning the GPU-dependent parts embed / serve / train assume Linux. This shouldn't matter much if you're only using the screenshot feature pixelshot , but on Mac/Windows you're safer running it through WSL. pixelshot screenshot feature just runs Playwright/Chromium locally, so there's no extra cost beyond your normal Claude Code token usage. Building your own index with embed / serve / train , however, needs a GPU, and if you use a cloud GPU for that, you'll pay for that usage separately.The official plugin/setup.sh looks like this: bash /bin/bash One-liner that installs pixelrag and registers it as a Claude Code plugin set -e Install pixelrag into an isolated environment via uv uv tool install --from "$REPO DIR" pixelrag 2 /dev/null || \ uv tool upgrade --from "$REPO DIR" pixelrag Install Chromium for screenshots uvx playwright install chromium 2 /dev/null || true Option 1: Clone the repo and run it locally git clone https://github.com/StarTrail-org/PixelRAG.git cd PixelRAG ./plugin/setup.sh claude --plugin-dir ./plugin Option 2: Install via the marketplace pip install pixelrag installs the pixelshot command claude plugin marketplace add StarTrail-org/PixelRAG claude plugin install pixelbrowse@pixelrag-plugins With the plugin installed, Claude is set up to call pixelshot via Bash and then read the generated images with the Read tool. Once installed, you just pass a URL in regular conversation and it works. claude -p "Look at https://news.ycombinator.com and summarize the top stories" In an interactive session, you can also use the slash command: claude --plugin-dir ./plugin inside the session /screenshot https://example.com Under the hood, Claude runs something like the following pixelshot command via Bash: Screenshot a URL tile height optimized to 1568px for Claude's vision model pixelshot https://example.com --output /tmp/pixelbrowse --tile-height 1568 --wait-network-idle Process multiple URLs in parallel pixelshot url1 url2 --output /tmp/pixelbrowse --tile-height 1568 --wait-network-idle --workers 4 Render a PDF pixelshot document.pdf --output /tmp/pixelbrowse Output is saved with a naming pattern like /tmp/pixelbrowse/<domain .png.tiles/tile 0000.jpg , and Claude reads it in as an image to understand the content. The following notes come straight from the official SKILL.md and matter in practice. Forgetting --wait-network-idle gives you a blank page Stick with the default --tile-height of 1568px If text is too small to read, crop and re-read it The official workflow is to crop the relevant region with Pillow and feed it back through the Read tool. Where PixelRAG is useful PixelRAG specializes in exactly what traditional text RAG struggles with: searching documents while preserving tables, diagrams, and layout. Wiring it into Claude Code doesn't require an MCP server at all — it's a skill-only setup that comes down to a single pixelshot command. Before using it in production, check the official repo for the latest status. 📌 This post reflects information as of August 2026. Since Claude Code updates frequently, check the official docs for the latest specifics. This article was edited with AI assistance. Originally published in Japanese on EdgeHUB.