agent-eyes

agent-eyes is a tool for AI coding agents, not for people. When an agent like Claude Code, Cursor or Codex edits a web page, it normally has no way to see the result. It changes some CSS, says “fixed”, and hopes. agent-eyes is an MCP server, a small program the agent can call, that opens the page in a real Chrome, looks at it, measures it and reports back. I built it for my own work in June 2026 and have used it every day since. The code went public in September.

The problem it solves

A screenshot alone is not enough. A picture is expensive for an agent to look at, and even with the picture in front of it the agent still has to guess at numbers: is that button 40 pixels wide or 44? Did the hero text actually stop overflowing on mobile? Did the fix even reach the deployed site, or is the agent looking at a stale tab?

agent-eyes is built around everything that happens after the screenshot. Most of its 28 tools return text instead of images, and the ones that return images keep the full-resolution file on disk and send the agent only a small thumbnail.

What it does

• Capture. Screenshots at four named breakpoints, mobile, tablet, desktop and ultrawide, so the agent reasons in names instead of inventing pixel sizes. One call can shoot all four.
• Layout and measurement. A layout scan that finds overflow, overlapping elements, tap targets under 44 px and unreadable text, and returns the diagnosis as text with no image at all. An element inspector that returns real dimensions, spacing, colours and WCAG contrast. A layout-shift meter. Pixel diffs against baselines you commit to git.
• Verify. A verify_fix tool that reloads the live URL and checks a list of small assertions, then returns a pass/fail table. This is the one that catches “the agent said it was fixed, but production still has the bug”.
• Accessibility and design. WCAG basics like alt text and heading order, a design-system review, and a tool that extracts a site’s colours and type into CSS variables.
• Interaction. Click, type, hover, scroll and drag, then capture. A tool that numbers every clickable element on screen and returns a legend of exact selectors, so the agent never guesses a selector. Multiple named tabs that keep their state. Network mocking for deterministic captures.
• Logins without leaking secrets. When a site needs a password, agent-eyes opens a small page on localhost where a human types it. The agent gets back “success”, never the credentials. Two-factor codes work the same way. Stored credentials go in an AES-256-GCM vault with no plaintext mode. When a page needs a real human, for a CAPTCHA for example, the browser becomes visible, the person clicks, and the run continues. It never tries to bypass those checks.

It drives the Chrome you already have, invisibly, with no automation fingerprint, so sites that block bots treat it as a normal browser. One browser session lives across tool calls, so a login in step one still holds in step nine.

How it was built

agent-eyes is about 17,000 lines of TypeScript on Node, using the official MCP SDK and Playwright to drive Chrome. Each tool is its own module, and the in-page code that scans layouts or labels elements lives separately from the server code that calls it. Unit tests cover config, Chrome detection, the login classifier, vault crypto and the verify assertions, and they run on Node 20, 22 and 24 in CI without launching a browser.

A one-line installer detects your Chrome and writes the MCP config for Claude Code, Cursor, Codex, Zed or VS Code:

npx -y github:oljodev/mcp-agent-eyes setup --agent claude-code --write

Cost mattered as much as features. The tool list an MCP server sends is resent on every request in every conversation, so the last release before publishing cut it by 35 percent just by rewriting the descriptions.

Status

Active and in daily use. I develop it alongside my other work and ship changes when I need them. Recent commits appear below.

What I got out of it

This is the first project where I built the tool I was missing instead of working around it. It taught me how AI agents actually consume tools, and how much the design of a tool’s inputs and outputs decides whether the agent uses it well. It also forced me to take security seriously from the start, because a tool that logs into real sites on your behalf has to be trustworthy or it is useless.