DEV Community

Cover image for Give Your AI Agent Eyes: Meet ContextGraph — The Offline Flight Recorder for Web Apps
Shadow Coderr
Shadow Coderr

Posted on

Give Your AI Agent Eyes: Meet ContextGraph — The Offline Flight Recorder for Web Apps

#testing #playwright #ai #webdev

IDE-based AI agents are powerful — but they're blind.

GitHub Copilot, Cursor, and Claude can't see your running browser. They don't know your live DOM, your real API traffic, or your accessibility tree. They're writing tests for an app they've never actually seen.

ContextGraph fixes that.

What Is ContextGraph?

ContextGraph is a CLI tool that acts like a flight data recorder for your browser. You navigate your app manually — it silently captures everything: DOM snapshots, accessibility trees, network traffic, screenshots, Playwright locators, and more.

When you're done, it exports a single ai_context_bundle.md file you can paste directly into any AI agent.

Your AI can now "see" your app — without MCP, without cloud, without any security compromise.

npm install -g @shadowcoderr/context-graph
Enter fullscreen mode Exit fullscreen mode

The Problem It Solves

In enterprise environments, MCP is frequently blocked by security policy. Cloud-based recording tools are off the table. AI agents generate hallucinated selectors because they've never seen your actual UI.

The result? You spend more time fixing broken AI-generated tests than writing them yourself.

ContextGraph bridges this gap using only Playwright — already whitelisted on most QA teams' machines — and outputs structured, offline, AI-ready intelligence.

Your Browser Session → ContextGraph → Structured Output → AI Agent → Generated Tests
Enter fullscreen mode Exit fullscreen mode

⚡ Quick Start (Under 2 Minutes)

Step 1: Install

npm install -g @shadowcoderr/context-graph
Enter fullscreen mode Exit fullscreen mode

Step 2: Capture your app

context-graph --mode browser --url https://your-app.com
# Navigate freely — every page is captured automatically
# Press Ctrl+C when done
Enter fullscreen mode Exit fullscreen mode

Step 3: Paste into your AI agent

# Bundle auto-generates at:
context-graph-output/bundles/ai_context_bundle.md
Enter fullscreen mode Exit fullscreen mode

Paste it into Copilot Chat, Cursor, or Claude → ask for tests → done.

🔑 What Gets Captured

For every page you navigate, ContextGraph saves:

File What's Inside
DOM Sanitised HTML — scripts stripped, Shadow DOM inlined
a11y_tree.json Full ARIA hierarchy — most semantically dense representation
locators.json 5+ selector strategies per element, ranked by resilience
api_inventory.json Every API endpoint observed, normalised path params
screenshot.png Full-page capture
ai_context_bundle.md Everything above in one file, ready for your AI

🔒 Enterprise-Safe by Design

Security wasn't an afterthought. ContextGraph enforces a 5-layer redaction pipeline before any disk write:

  1. Header stripping (auth, cookie, x-api-key)
  2. URL sanitisation (token, api_key, secret, password params)
  3. Pattern matching (JWT, Bearer, credit cards, SSNs, AWS keys)
  4. Key-based redaction
  5. Custom user-defined rules

Hardcoded invariants that cannot be disabled:

  • <script> content is always stripped
  • type="password" inputs are always [REDACTED]
  • Zero outbound connections. Zero telemetry. Zero update checks.

Every redaction is logged to logs/redaction_audit.jsonl for compliance review.

🤖 Real AI Workflow Example

After pasting ai_context_bundle.md into your AI agent:

I am testing the app shown in this session context.

Using ONLY the locators from the "Interactive Elements" tables above,
generate Playwright TypeScript tests that:
  1. Navigate to the login page and log in with valid credentials
  2. Assert the dashboard renders correctly
  3. Test the shopping cart add/remove flow
  4. Cover the checkout form submission

Use test.describe() groups per page. Include assertions for
visible elements and navigation outcomes.
Enter fullscreen mode Exit fullscreen mode

No hallucinated selectors. No guessed API paths. Your AI works from ground truth.

🏢 4 Enterprise Patterns

Pattern A — AI Test Generation
Browse your app → paste bundle → get .spec.ts files.

Pattern B — Regression Detection
Capture before and after a release. Compare locator drift to find tests that will break before they break in CI.

Pattern C — Undocumented App Onboarding
Spend 1–2 hours navigating an unfamiliar internal app → api_inventory.json gives you a full API surface. No Swagger docs needed.

Pattern D — Manual Test Conversion
Follow your manual test script step-by-step in recorder mode → output is a .spec.ts file.

Why This Matters for QA Teams

Most AI coding tools are built for greenfield development. QA engineers deal with the messy reality of legacy apps, undocumented APIs, and locked-down enterprise environments.

ContextGraph was built specifically for that reality:

  • ✅ No cloud required
  • ✅ No MCP required
  • ✅ Works inside enterprise perimeters
  • ✅ Uses Playwright (already approved on most teams)
  • ✅ Produces audit-ready redaction logs

Try It Now 

npm install -g @shadowcoderr/context-graph
context-graph --mode browser --url https://your-app.com
Enter fullscreen mode Exit fullscreen mode

📦 npm package
⭐ GitHub
📖 Full Documentation

Give your AI the eyes it was missing.

If this saved you time or unblocked your team, drop a ⭐ on GitHub and share it with your QA community — it means a lot as an indie dev.

Top comments (0)