@viewgraph/core

The UI context layer for agentic coding.

Built with Kiro, for Kiro - and every MCP-compatible coding agent.

       

Browser extension + MCP server for AI-powered UI capture, auditing, and annotation.

ViewGraph captures structured DOM snapshots from any web page and exposes them to AI coding assistants via the Model Context Protocol. Agents can query page structure, audit accessibility, find missing test IDs, compare captures, track regressions, and act on human annotations - all through 41 MCP tools and 12 prompt templates.

Works with any MCP-compatible agent: Kiro, Claude Code, Cursor, Windsurf, Cline, Aider, and more. No agent-specific code - pure MCP protocol. Tools that don't support MCP can read .viewgraph.json capture files directly from disk.

Components

Component	Description
server/	MCP server - 41 query/analysis/request tools, WebSocket collab, baselines
extension/	Chrome/Firefox extension - DOM capture, annotate, 21 enrichment collectors, multi-export
packages/playwright/	Playwright fixture - capture structured DOM snapshots during E2E tests
power/	Kiro Power assets - 3 hooks, 9 prompts, 3 steering docs, MCP config

How It Works

ViewGraph runs alongside your project as a standalone tool. It does not embed into your codebase or require changes to your application. It works with any web app regardless of backend technology (Python, Ruby, Java, Go, PHP, etc.).

Your app (any language) --> serves HTML --> Browser renders it --> Extension captures DOM
                                                                        |
                                                                        v
Kiro / Claude / Cursor  <-- MCP protocol <-- ViewGraph server <-- .viewgraph.json files

The extension captures the DOM from Chrome or Firefox. The server reads those capture files and exposes them to your AI agent via MCP. Your agent then uses this context to modify your source code - it never injects into or manipulates the running application directly.

Getting Started

Prerequisites: Node.js 22+, npm 9+, Chrome 116+ or Firefox 109+

# 1. Install the browser extension from Chrome Web Store or Firefox Add-ons (links above)

# 2. Add to your AI agent's MCP config (~/.kiro/settings/mcp.json):
{
  "mcpServers": {
    "viewgraph": { "command": "npx", "args": ["-y", "@viewgraph/core"] }
  }
}

# 3. Capture: click the ViewGraph toolbar icon on any page
# 4. Ask your agent: "Fix the annotations from my last review"

The server runs automatically via npx - no install needed. It auto-creates .viewgraph/captures/ and learns your URL pattern from the first capture.

GitHub Releases = latest version, always. Chrome/Firefox store reviews can delay updates by days or weeks. GitHub Releases always has the newest extension ZIPs and changelog. For the bleeding edge, get it from GitHub.

Alternative: npm install -g @viewgraph/core for explicit version pinning, then run viewgraph-init from each project folder to configure URL patterns and capture routing.

Uninstall: npx @viewgraph/core uninstall from your project folder. Removes MCP config, steering docs, prompts, and hooks. Optionally removes capture data. Uninstall guide.

The extension sidebar opens with Review (annotate and comment) and Inspect (network errors, console issues) tabs. Export via Send to Agent (MCP), Copy Markdown (Jira/GitHub), or Download Report (ZIP).

For detailed setup with screenshots, browser-specific instructions, and multi-project configuration, see the Quick Start Guide.

Try the demo: Open docs/demo/index.html - a login page with 8 planted bugs. Annotate, send to Kiro, watch them get fixed. Walkthrough.

Workflows

ViewGraph supports three broad workstreams. For the full list of 23 problems it solves, see Why ViewGraph?.

For developers with AI agents

• Open your app in the browser, click the ViewGraph icon
• Click elements or shift+drag regions, add comments describing what to fix
• Check the Inspect tab for network errors or console issues
• Click Send to Agent - annotations bundle with the full DOM capture + enrichment data
• Ask your agent to fix the issues - it has full DOM context

For testers and reviewers (no AI agent needed)

The extension works standalone. No MCP server required.

• Open the app in the browser, click the ViewGraph icon
• Click or shift+drag to select problem areas, add comments
• Export:
  • Copy Markdown - paste into Jira/Linear/GitHub (includes network failures, console errors, viewport breakpoint)
  • Download Report - ZIP with markdown, screenshots, network.json, console.json

For teams

A tester annotates and exports to markdown. A developer annotates and sends to Kiro. A reviewer compares captures against baselines. Same tool, same workflow, same format - the only difference is where the output goes. See Why ViewGraph? for the full list of review, release, and platform workflows.

For test automation teams

Capture structured DOM snapshots during Playwright E2E tests, or generate tests from browser captures:

• Generate tests from captures: Capture a page with the extension, ask your agent @vg-tests - it generates a complete Playwright test file with correct locators for every interactive element. 20-30 minutes of manual inspection reduced to one prompt.
• Capture during tests: Add await viewgraph.capture('checkout-page') to existing tests. The agent can then diff captures between runs, audit accessibility, and detect structural regressions.
• Annotate from tests: await viewgraph.annotate('#email', 'Missing aria-label') flags issues for the agent to fix with full DOM context.

See @viewgraph/playwright for setup, API, and examples.

Capture Accuracy

ViewGraph's capture accuracy is measured automatically against 150 diverse real-world websites using a bulk capture experiment. The experiment runs ViewGraph's DOM traverser via Puppeteer, then compares the output against live DOM ground truth across 7 dimensions.

Latest results (Set A - Breadth, 48 sites across 12 categories, 4 rendering types, 6 writing systems):

Dimension	Median	What it measures
Composite	92.1%	Weighted combination of all dimensions
Selector accuracy	99.7%	VG's CSS selectors resolve to real DOM elements
Testid recall	100.0%	All data-testid elements captured
Interactive recall	97.9%	Buttons, links, inputs captured
Bbox accuracy	100.0%	Bounding boxes preserved through serialization
Semantic recall	88.2%	Landmark elements (nav, main, header) captured
Text match	53.1%	visibleText matches element text (see note)

Full methodology, per-site breakdowns, and run history: scripts/experiments/bulk-capture/

Token Efficiency (v3 Format)

ViewGraph v3 (format v2.4.0) reduces agent token consumption by up to 97% compared to full-capture approaches:

Optimization	Measured Impact	Method
Action Manifest	80-85% reduction on interactive queries	Pre-joined flat index with short refs
Style dedup	50% dedup rate across 175 captures	Shared style table, hash-based refs
Default omission	41.8% of style values removed	Browser defaults filtered at serialization
Container merging	30-50% fewer nodes	D2Snap-aligned empty wrapper removal
observationDepth	96% reduction at interactive-only	Agent chooses depth per request
File-backed receipts	99.8% reduction on transmission	~200 token receipt instead of full JSON
JSON Patch diffs	50-1500x compression	RFC 6902 patches for sequential captures

All measurements from experiments on 175 real captures across 4 projects + 48 diverse websites. See scripts/experiments/ for methodology and results.

Format spec: docs/architecture/viewgraph-v2-format.md | Research: docs/architecture/viewgraph-v3-format-agentic-enhancements.md

Documentation

• User Guide - getting started, tutorials, feature guides
• Quick Start - zero to first fix in 5 minutes
• Why ViewGraph? - 23 problems it solves
• Who Benefits? - developers, testers, PMs, career switchers
• Multi-Project Setup - URL patterns, routing
• @viewgraph/playwright - Playwright fixture on npm
• Roadmap - milestone plan and completion status
• Security Assessment - threat model, HMAC auth, 7 security reviews
• Spec Index - Kiro specs, ADRs, architecture docs
• ViewGraph v2 Format Spec - capture format (v2.1.0)
• Format Research - format analysis and design rationale
• Competitive Analysis - browser MCP comparison
• Product Analysis - user journeys, pain points, competitor matrix

Companion Tools

ViewGraph sees the UI. TracePulse feels the backend. Together with Chrome DevTools MCP, they form the three-layer agentic debugging stack: backend verification (TracePulse) + browser verification (Chrome DevTools MCP) + visual verification (ViewGraph).

Acknowledgments

ViewGraph's capture format was inspired by Element to LLM (E2LLM) by insitu.im - the first browser extension to frame DOM capture as a structured perception layer for AI agents. The core insight - that agents need a purpose-built intermediate representation, not raw HTML - came from E2LLM. ViewGraph extended these foundations through deep format research that produced 20 improvement proposals across token efficiency, accessibility, enrichment, and bidirectional MCP integration. Full comparison.

ViewGraph's security assessment was conducted using the AWS Labs Threat Modeling MCP Server by Aidin Ferdowsi (AWS). The tool's structured STRIDE analysis and Threat Composer integration produced the 9-threat, 9-mitigation model that drove ViewGraph's HMAC auth implementation, prompt injection defenses, and seven rounds of security reviews. Full threat model.

License

AGPL-3.0 - see COPYING for the full license text.

Copyright (c) 2026 Sourjya S. Sen. See ADR-009 for licensing rationale.