Browser Extension

The Glasstrace browser extension connects what happens in your browser to what happens on your server. When you click a button and something breaks, the extension captures the click, injects a correlation header, and links it to the server-side trace. Your AI agent sees both sides of the story.

The extension is observational only. It does not intercept requests, read response bodies, or modify page content. It watches, correlates, and reports.

Install

Install the Glasstrace extension from the Chrome Web Store:

Open the Chrome Web Store listing and click Add to Chrome.
Confirm the permissions dialog.
Pin the extension to your toolbar for quick access.

During beta, you may need to load the extension manually:

Download the latest extension release from the Glasstrace releases page and unzip it, or build from source:

cd packages/extension
npm install
npm run build

Open chrome://extensions in Chrome.
Enable Developer mode (top right).
Click Load unpacked and select the dist/ directory.

Permissions

The extension requests three permissions:

Permission	Why
`storage`	Stores your auth state, domain allowlist, and observation buffer locally in the browser.
`scripting`	Injects content scripts on non-localhost allowlisted domains after you sign in.
`alarms`	Schedules periodic tasks like buffer flushing and allowlist sync.

The extension also declares host permissions for localhost, 127.0.0.1, and [::1] (your local dev server) and *.glasstrace.com (the Glasstrace API). Non-localhost domains are requested at runtime only when you explicitly add them.

How it works

The extension captures four types of client-side data:

Gesture capture. Records click, form submit, and keypress events with timestamps and element fingerprints. The fingerprint priority chain is: data-testid > id > aria-label > React component name > tag.className.

Correlation header injection. Adds a single x-gt-cid header (a UUID v4) to every outbound fetch and XMLHttpRequest on allowlisted domains. This header is the primary link between browser actions and server traces.

Network observation. Observes outbound network requests via the Performance API. Records URL, HTTP method, and timing. Only fetch and XMLHttpRequest requests are tracked; images, stylesheets, and other resources are ignored.

Console error capture. Captures console.error output only (not log, warn, or info). Each error is truncated to 500 characters. Sensitive patterns are stripped before transmission: JWT tokens, API key formats, connection strings, base64 blobs, AWS keys, GitHub tokens, Slack tokens, and URL-embedded credentials are replaced with [REDACTED].

What the extension does NOT do

This matters for trust. The extension:

Does not intercept, modify, or block HTTP requests or responses
Does not read request or response bodies
Does not modify page content or the DOM (beyond the fetch/XHR constructor override for header injection)
Does not capture form input values, passwords, or cookies
Does not store traces locally beyond a temporary send buffer
Does not run on non-allowlisted domains (completely inert)
Does not require any backend module or server-side dependency at runtime

Auth modes

The extension operates in one of three auth modes. The mode determines what data is captured and where it is sent.

Unauthenticated

The default state. Behavior depends on where you are:

Non-localhost pages: The extension is completely inert. No observation, no data capture, no headers injected.
Localhost pages: The extension observes gestures and network activity for popup UI context (observation count), but does not send data to the cloud. This supports the case where the Glasstrace SDK is not yet installed on your dev server.

Anonymous

Activated automatically on localhost when the extension discovers a running Glasstrace SDK.

When you navigate to localhost:3000 (or any localhost port), the extension fetches GET /__glasstrace/config from your dev server. If the SDK is running in anonymous mode (no GLASSTRACE_API_KEY set, NODE_ENV is not production), it returns an anonymous key (gt_anon_xxx) and session ID. The extension uses this key to send observations to the Glasstrace cloud.

This is the zero-config experience: install the SDK, install the extension, and traces are correlated automatically.

Anonymous mode is per-origin. If you run apps on localhost:3000 and localhost:8080, each gets its own anonymous key from its own SDK instance.

Authenticated

Activated when you sign in via the extension popup.

Click the extension icon and select Sign in. This opens the Glasstrace dashboard in a new tab. After authentication, the dashboard delivers a session token (gt_session_xxx) to the extension.

Authenticated mode unlocks:

Observation on non-localhost domains (staging, preview deployments)
Domain allowlist sync from your account settings
Extension-initiated domain addition

The session token is stored in memory only (chrome.storage.session) and cleared when you close the browser.

Transitioning between modes

From	To	How
Unauthenticated	Anonymous	Navigate to localhost where the SDK is running. Automatic.
Unauthenticated	Authenticated	Sign in via the extension popup.
Anonymous	Authenticated	Sign in via the extension popup. Your anonymous traces can be claimed to your account.
Authenticated	Unauthenticated	Sign out, or close the browser (session token expires).

Domain allowlist

The domain allowlist controls which websites the extension is active on. If a domain is not on the list, the extension does nothing on that page: no observation, no headers, no data.

Defaults

In anonymous mode, only localhost variants are allowed: localhost, 127.0.0.1, and [::1] (any port). No configuration needed.

Adding domains

Non-localhost domains (staging servers, Vercel preview URLs) require an account. Add them through either:

Dashboard settings. Go to your account settings in the Glasstrace dashboard and add domains there. The extension syncs the allowlist periodically after sign-in.
Extension popup shortcut. Navigate to the domain you want to observe. Click the extension icon. If the domain is not on your allowlist, the popup shows “Not observing this domain” with an Add to Glasstrace button. Clicking it adds the domain to your account and requests Chrome host permission in one step.

When new domains are synced from the dashboard, Chrome will prompt you to grant host permissions before the extension can observe those pages. This is a Chrome platform requirement and a privacy safeguard.

How enforcement works

The allowlist is enforced at three independent points:

Manifest matches — Content scripts are only injected on localhost by default. Non-localhost domains require dynamic script registration after you grant permissions.
Injector check — Before injecting the x-gt-cid header, the injector checks the request destination URL against the allowlist (not the page origin). This prevents headers from leaking to third-party APIs called from an allowlisted page.
Observer check — Before capturing any events, the observer checks the page origin against the allowlist.

If any check fails, no data is captured and no headers are injected.

Correlation

The x-gt-cid header is how Glasstrace answers “why did that break?” Here is the full correlation flow:

You click a button in your app (e.g., “Submit Order”).
The extension captures the gesture: click event, element fingerprint (data-testid="submit-order"), timestamp.
Your app calls fetch('/api/orders', { method: 'POST' }).
The extension’s injector overrides the fetch constructor, generates a UUID v4 correlation ID, and adds the x-gt-cid header to the request.
Your server receives the request. The Glasstrace SDK reads the x-gt-cid header and stores it as a span attribute on the server trace.
The extension observes the network request via the Performance API and records URL, method, and timing.
The extension sends the client observation (gesture + network + correlation ID) to the Glasstrace cloud.
The cloud matches the client observation to the server trace using the x-gt-cid value.

When your AI agent calls get_latest_error or get_trace, it sees both sides: the user action that triggered the request and the server error that resulted. Instead of a stack trace in isolation, the agent knows “the user clicked Submit Order, which called POST /api/orders, which threw a PrismaClientKnownRequestError.”

Without the extension (SDK-only install), the cloud falls back to URL + method + timestamp matching with confidence scoring. The x-gt-cid header provides exact correlation.

Privacy

The extension is designed around a minimal data footprint. Here is exactly what it captures and what it does not.

What IS captured

Gesture type (click, submit, keypress) and timestamp
Element fingerprint (data-testid, id, aria-label, component name, or tag.className)
Outbound request URLs and HTTP methods (on allowlisted domains only)
Request timing (via Performance API)
Console errors (error-level only, truncated to 500 chars, sensitive patterns stripped)
The x-gt-cid correlation UUID

What is NOT captured

Form input values or passwords
Request or response bodies
Cookies or session storage content
Non-error console output (log, warn, info)
Any data from non-allowlisted domains
Browsing activity outside your development domains

Extension permissions explained

The extension requests only storage, scripting, and alarms permissions. It does not request tabs (tab URLs are not accessed), webRequest (requests are not intercepted), or cookies. Host permissions for localhost and *.glasstrace.com are declared in the manifest. Permissions for non-localhost domains are requested at runtime only when you explicitly add a domain.

All data sent to the Glasstrace cloud is transmitted over HTTPS. Localhost discovery uses plain HTTP. The extension never logs, displays, or persists sensitive data beyond the temporary observation buffer.

A full privacy policy will be published at glasstrace.dev/privacy.