viewgraph

<p align="center"> <img src="docs/logos/viewgraph-logo.png" alt="ViewGraph" width="420"> </p> <p align="center"><strong>The UI context layer for agentic coding.</strong></p> <p align="center"><em>Built with Kiro, for Kiro - and every MCP-compatible coding agent.</em></p> <p align="center"> <a href="https://chromewebstore.google.com/detail/viewgraph-capture/dmgbneoidgmkdcfnlegmfijkedijjnjj"><img src="https://img.shields.io/badge/Chrome-Install_Extension-4285F4?style=for-the-badge&logo=google-chrome&logoColor=white" alt="Chrome Web Store"></a> &nbsp; <a href="https://addons.mozilla.org/en-US/firefox/addon/viewgraph-capture/"><img src="https://img.shields.io/badge/Firefox-Install_Extension-FF7139?style=for-the-badge&logo=firefox-browser&logoColor=white" alt="Firefox Add-ons"></a> &nbsp; <a href="https://www.npmjs.com/package/@viewgraph/core"><img src="https://img.shields.io/badge/npm-@viewgraph/core-CB3837?style=for-the-badge&logo=npm&logoColor=white" alt="npm"></a> &nbsp; <a href="https://chaoslabz.gitbook.io/viewgraph"><img src="https://img.shields.io/badge/Docs-GitBook-blue?style=for-the-badge&logo=gitbook&logoColor=white" alt="Documentation"></a> &nbsp; <a href="https://chaoslabz.gitbook.io/viewgraph/getting-started/quick-start"><img src="https://img.shields.io/badge/Quick_Start-5_minutes-green?style=for-the-badge&logo=clockify&logoColor=white" alt="Quick Start"></a> </p> <p align="center"> <a href="https://www.youtube.com/watch?v=ociXQLaY2z4"> <img src="docs/logos/demo-thumbnail.png" alt="ViewGraph Demo" width="600"> </a> </p> Browser extension + MCP server for AI-powered UI capture, auditing, and annotation. **Our mission: make agentic coding environmentally sustainable.** AI agents waste [60-80% of their tokens](https://arxiv.org/html/2601.14470v1) on orientation, not problem-solving. Every wasted token is wasted compute, wasted energy, and avoidable carbon emissions. With data center energy demand projected to [double by 2030](https://www.iea.org/news/ai-is-set-to-drive-surging-electricity-demand-from-data-centres-while-offering-the-potential-to-transform-how-the-energy-sector-works), ViewGraph delivers the UI context agents need in the smallest possible token footprint - 97% fewer tokens per task, measured across 175 real captures. ViewGraph captures structured DOM snapshots from any web page and exposes them to AI coding assistants via the [Model Context Protocol](https://modelcontextprotocol.io/). 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/`](./server/) | MCP server - 41 query/analysis/request tools, WebSocket collab, baselines | | [`extension/`](./extension/) | Chrome/Firefox extension - DOM capture, annotate, 21 enrichment collectors, multi-export | | [`packages/playwright/`](./packages/playwright/) | Playwright fixture - capture structured DOM snapshots during E2E tests | | [`packages/vitest/`](./packages/vitest/) | Vitest plugin - capture DOM snapshots during component and unit tests | | [`power/`](./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+ ```bash # 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](https://github.com/sourjya/viewgraph/releases/latest) 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](https://chaoslabz.gitbook.io/viewgraph/getting-started/uninstall). 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](https://chaoslabz.gitbook.io/viewgraph/getting-started/quick-start). **Try the demo:** Open [`docs/demo/index.html`](./docs/demo/) - a login page with 8 planted bugs. Annotate, send to Kiro, watch them get fixed. [Walkthrough](./docs/demo/README.md). ## Workflows ViewGraph supports three broad workstreams. For the full list of 23 problems it solves, see [Why ViewGraph?](https://chaoslabz.gitbook.io/viewgraph/why-viewgraph). ### For developers with AI agents 1. Open your app in the browser, click the **ViewGraph** icon 2. Click elements or shift+drag regions, add comments describing what to fix 3. Check the **Inspect** tab for network errors or console issues 4. Click **Send to Agent** - annotations bundle with the full DOM capture + enrichment data 5. 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. 1. Open the app in the browser, click the **ViewGraph** icon 2. Click or shift+drag to select problem areas, add comments 3. 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?](https://chaoslabz.gitbook.io/viewgraph/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`](./packages/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](./scripts/experiments/bulk-capture/). 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/`](./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/`](./scripts/experiments/) for methodology and results. Format spec: [`docs/architecture/viewgraph-v2-format.md`](./docs/architecture/viewgraph-v2-format.md) | Research: [`docs/architecture/viewgraph-v3-format-agentic-enhancements.md`](./docs/architecture/viewgraph-v3-format-agentic-enhancements.md) ## Documentation - [User Guide](https://chaoslabz.gitbook.io/viewgraph) - getting started, tutorials, feature guides - [Quick Start](https://chaoslabz.gitbook.io/viewgraph/getting-started/quick-start) - zero to first fix in 5 minutes - [Why ViewGraph?](https://chaoslabz.gitbook.io/viewgraph/why-viewgraph) - 23 problems it solves - [Who Benefits?](https://chaoslabz.gitbook.io/viewgraph/who-benefits) - developers, testers, PMs, career switchers - [Multi-Project Setup](https://chaoslabz.gitbook.io/viewgraph/getting-started/multi-project) - URL patterns, routing - [@viewgraph/playwright](https://www.npmjs.com/package/@viewgraph/playwright) - Playwright fixture on npm - [Roadmap](./docs/roadmap/roadmap.md) - milestone plan and completion status - [Security Assessment](./docs/security/security-assessment.md) - threat model, HMAC auth, 7 security reviews - [Spec Index](./.kiro/specs/README.md) - Kiro specs, ADRs, architecture docs - [ViewGraph v2 Format Spec](./docs/architecture/viewgraph-v2-format.md) - capture format (v2.1.0) - [Format Research](./docs/references/viewgraph-format-research.md) - format analysis and design rationale - [Competitive Analysis](./docs/references/competitive-analysis-browser-mcp.md) - browser MCP comparison - [Product Analysis](./docs/references/product-analysis.md) - user journeys, pain points, competitor matrix ## Companion Tools ViewGraph is the **optic nerve** for AI coding agents - it transforms raw DOM into structured perception that LLMs can reason about. [Research shows](https://arxiv.org/html/2604.01535v1) high-capability models gain +14-17 points on web tasks when given structured layout data (CSS, bounding boxes, z-index) vs raw accessibility trees alone. ViewGraph delivers exactly that, at 1,930 tokens median vs ~17,000 for raw snapshots. But perception alone isn't enough. The complete agent nervous system: | Layer | Tool | Role | |---|---|---| | **Eyes** (perception) | [ViewGraph](https://chaoslabz.gitbook.io/viewgraph) | Sees the UI - structured captures, diffs, a11y audits, source mapping | | **Ears** (feedback) | [TracePulse](https://chaoslabz.gitbook.io/tracepulse) | Hears the backend - errors, hot-reloads, build state, signal scoring | | **Hands** (action) | [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) | Acts in the browser - click, type, navigate, screenshot, JS eval | ViewGraph also serves humans directly: click what's broken, describe it, send to your agent. No other tool in the ecosystem is both a human annotation tool and an agent perception layer. [Full positioning](docs/references/viewgraph-vs-devtools-positioning.md). ## Acknowledgments ViewGraph's capture format was inspired by [Element to LLM](https://addons.mozilla.org/en-US/firefox/addon/element-to-llm/) (E2LLM) by [insitu.im](https://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](./docs/references/viewgraph-format-research.md) that produced 20 improvement proposals across token efficiency, accessibility, enrichment, and bidirectional MCP integration. [Full comparison](https://chaoslabz.gitbook.io/viewgraph/how-it-compares/capture-format#acknowledgments). ViewGraph's [security assessment](https://chaoslabz.gitbook.io/viewgraph/reference/threat-model) was conducted using the [AWS Labs Threat Modeling MCP Server](https://github.com/awslabs/threat-modeling-mcp-server) by [Aidin Ferdowsi](https://github.com/aidinferdowsi) (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](./docs/security/security-assessment.md). ## License AGPL-3.0 - see [COPYING](COPYING) for the full license text. Copyright (c) 2026 Sourjya S. Sen. See [ADR-009](docs/decisions/ADR-009-agpl-licensing.md) for licensing rationale.