iris README

The project's README from github.com/brijr/iris. As one markdown file: README.md.

iris

ChatGPT Image Aug 18, 2026, 12_50_00 PM

A camera for coding agents. One fast command or MCP tool call produces one trustworthy image.

iris example.com                        # 1440×900 @2x → example.com.png
iris --full --dark tailwindcss.com      # full page, dark color scheme
iris --size iphone stripe.com           # 390×844 @3x with a mobile UA
iris --selector '#hero' --padding 24 app.dev # first matching element, tightly framed
iris -o shots/ a.com b.com c.com        # batch, captured concurrently
cat urls.txt | iris - -o shots/         # batch from stdin (# comments ok)
iris -o hero.jpg --wait-for 'h1' app.dev
iris --selector 'h1' --json app.dev      # machine-readable JSON Lines

iris --full bridger.to →

Full-page capture of bridger.to, taken by iris

Install

curl -fsSL https://raw.githubusercontent.com/brijr/iris/main/install.sh | sh

Or with a Rust toolchain:

cargo install iris-screenshot

The crates.io package is named iris-screenshot; the installed command is iris.

The only runtime dependency is an installed Chrome-family browser (Chrome, Chromium, Edge, or Brave). Building from source requires Rust 1.88 or newer.

Give your coding agent eyes

Iris includes a local stdio MCP server in the same binary. Add it to Codex:

codex mcp add iris -- iris mcp

Or use the equivalent configuration in another MCP client:

{
  "mcpServers": {
    "iris": {
      "command": "iris",
      "args": ["mcp"]
    }
  }
}

The server exposes one tool, capture, which returns the image inline with structured metadata. It writes nothing by default; pass output when the agent also needs a file.

{
  "url": "localhost:3000",
  "selector": "#pricing-card",
  "padding": 24,
  "size": "desktop",
  "dark": false,
  "format": "png",
  "timeout_seconds": 30,
  "output": "/tmp/pricing-card.png"
}

Bare localhost, .localhost, and loopback addresses use HTTP automatically. Other bare hosts use HTTPS. Run iris mcp --help to select a Chrome binary for the server.

MCP clients may need a fresh agent task before the newly registered capture tool appears.

Setup Prompt

Give this setup prompt to your coding agent:

Set up Iris as your visual camera in this coding environment.

Goal: install Iris, connect its local MCP server to this agent client, and prove
both the CLI and MCP paths work. Do not modify the application repository.

1. Check for an installed Chrome-family browser, `iris --version`, and an
   existing Iris MCP configuration.
2. If Iris is missing or outdated, install it with:

   curl -fsSL https://raw.githubusercontent.com/brijr/iris/main/install.sh | sh

   Or, when Rust is available:

   cargo install iris-screenshot

   Make sure the resulting `iris` command is on PATH.
3. Register the stdio MCP server without duplicating an existing entry.

   For Codex:

   codex mcp add iris -- iris mcp
   codex mcp get iris

   For another MCP client, configure command `iris` with args `["mcp"]`.
4. Prove the CLI works:

   iris https://example.com --selector h1 --padding 8 --scale 1 --json \
     -o /tmp/iris-smoke.png

   Confirm `status: ok` and a readable, non-empty PNG.
5. Reload the MCP configuration or start a fresh agent task if required. Call
   Iris's `capture` tool once for `https://example.com`, selecting the first
   `h1` with 8px padding and scale 1. Confirm an inline PNG and structured
   dimensions are returned.
6. Report the installed Iris version, MCP configuration, CLI smoke result, MCP
   smoke result, and any remaining blocker.

Do not claim MCP success from the CLI test alone. Do not add browser automation,
interaction scripting, or review tooling; use Iris only as the camera.

What it does for you

Element capture is intentionally CSS-selector based: Iris captures the first match in document order. --selector conflicts with --full; --padding requires it. Cross-origin iframe contents and capturing every match are not supported.

{"status":"ok","url":"https://example.com/","output":"/absolute/example.com.png","mode":"element","selector":"h1","padding":24,"css_width":180,"css_height":72,"scale":2.0,"format":"png","bytes":14231}

Benchmarking

Capture time includes navigation and Iris's correctness waits, so compare the same URL, capture mode, viewport, scale, Chrome version, and hardware. Prefer a deterministic local page when comparing releases; public URLs add network and server variance.

For a repeatable one-shot CLI benchmark from this repository, install hyperfine and run:

cargo build --release
hyperfine --warmup 1 --runs 10 \
  './target/release/iris file://$PWD/tests/fixtures/precise-capture.html \
    --selector .capture-target --padding 24 --scale 1 \
    -o /tmp/iris-benchmark.png'

The CLI starts a Chrome process for every invocation. MCP keeps one Chrome process alive for the server's lifetime, so benchmark it separately: initialize once, record the first capture, then report the median and p95 of at least ten identical subsequent calls. Measure from JSON-RPC request to complete tool response and exclude model time.

Reference results (not a performance guarantee):

Iris Machine Chrome Workload Result
0.4.1 Apple M2 Max, macOS 26.5.2 151.0.7922.138 One-shot CLI, 10 runs after one warmup 1.00 s median
0.4.1 Apple M2 Max, macOS 26.5.2 151.0.7922.138 MCP first capture 965 ms
0.4.1 Apple M2 Max, macOS 26.5.2 151.0.7922.138 MCP next 10 captures 366 ms median, 383 ms p95

All reference runs used the local precise-capture.html fixture, .capture-target, 24px padding, PNG, and scale 1. Record iris --version, the Chrome version, and the exact command with any published result.

Flags

-o, --out <PATH>       output file (single URL) or directory (batch)
-s, --size <SIZE>      WxH, or desktop (1440x900@2x) | iphone (390x844@3x) | ipad (1024x1366@2x)
    --full             capture the full page height
    --selector <CSS>   capture the first element matching a CSS selector
    --padding <PX>     nonnegative CSS-pixel padding around a selected element
    --dark             emulate prefers-color-scheme: dark
    --format <FMT>     png | jpg | webp (a recognized --out extension wins)
    --wait <MS>        extra settle delay after smart waiting
    --wait-for <CSS>   wait until a selector exists before capturing
    --scale <N>        device scale factor (overrides the preset's)
    --jobs <N>         concurrent captures (default: min(4, URLs))
    --timeout <SECS>   per-page budget (default: 30)
    --chrome <PATH>    browser binary (auto-detected; also via $CHROME)
    --json             emit one JSON object per completed capture

iris mcp [--chrome <PATH>] serves the single-image capture tool over stdio. Batch capture, browser interaction scripting, diffs, and review workflows remain outside Iris.

License

MIT

iris (brijr/iris)

Searching Database…

515 ·GitHub
Iris
Что это?Iris — консольная утилита и MCP-сервер, которая делает скриншоты живых сайтов, управляя вашим реально установленным Chrome через DevTools Protocol. Она задумана как «камера» для кодинг-агентов: одно надёжное изображение на команду или вызов инструмента.
Это CLI-утилита, библиотека или MCP-сервер?И то и другое: один бинарник на Rust, работающий как консольный инструмент (iris --full url), внутри которого есть ещё и локальный stdio MCP-сервер, предоставляющий кодинг-агентам инструмент захвата.
Как её установить и запустить?Установите с crates.io (имя пакета iris-screenshot, после установки команда iris) или соберите из исходников с тулчейном Rust, затем выполняйте команды вроде 'iris --full bridger.to'. Для использования агентом добавьте iris mcp в конфиг вашего MCP-клиента, например Codex.
Нужно ли что-то, кроме самой Iris?Нужен установленный браузер семейства Chrome (Chrome, Chromium, Edge или Brave) — единственная рантайм-зависимость; для сборки из исходников требуется Rust 1.88 или новее.
Чего Iris не умеет?Она не поддерживает содержимое кросс-доменных iframe и захват всех совпадений CSS-селектора (только первое), а --selector конфликтует с --full. Полные страницы выше предела рендеринга Chrome (~16 тыс. px) автоматически откатываются к @1x.
Для кого она создана?Она нацелена на кодинг-агентов и разработчиков, которым нужна надёжная визуальная проверка сайтов — через CLI-скрипты или прямым подключением к ИИ-агенту для кодинга через MCP.
Чего Iris на самом деле дожидается перед снимком?Она дожидается загрузки шрифтов, изображений и появляющихся анимаций, а в режиме --full ещё и прокруткой подгружает ленивый контент перед снимком, стремясь к достоверному, а не преждевременному захвату.
Какие форматы изображений и разрешения она поддерживает?Формат вывода выбирается по расширению в -o или флагу --format: по умолчанию PNG, ещё JPG или WebP (кодирование с качеством 90). По умолчанию используется масштаб Retina @2x, если страница не слишком высокая для предела рендеринга Chrome.
Можно ли снять один элемент вместо всей страницы?Да, --selector захватывает первый подходящий под CSS-селектор элемент в порядке документа, автоматически прокручивая его в зону видимости и давая новому видимому контенту устояться перед кадром.
Как работает пакетный захват?Iris запускает один процесс браузера с параллельными вкладками; неудачный URL печатает пометку и не прерывает пакет, хотя общий код выхода равен 1, если что-то не удалось. Имена файлов берутся из URL, при коллизиях добавляются суффиксы -2, -3, а --json выводит по одному JSON-объекту на снимок в stdout.
What are similar projects?bb-browser, oc, agent-browser, leviathan, memex, playwright-cli, dev-browser, mcp-chrome
Which topics is it in?screenshots, screenshot, chrome, browser-automation, cli-tool, mcp-server, rust, command-line-tool, mcp, terminal, tool, cli
Creator
brijr
Size
0.6 MB
Stars
515
Updated
CommitSep 01Releasev0.4.1Aug 18
Age
2mo
Commits · 90 Days