Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

docs: document the browser extension as a supported runtime surface

shukieshahcdd9a4352733
diff --git a/AGENTS.md b/AGENTS.md
index 1d14516a..b98c4465 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -40,3 +40,18 @@ sh packaging/macos/smoke-endpoint.sh
Each directory above is a separate Go module; run Go commands from inside the module you are
changing.
+
+The npm and bun subprojects are separate from the Go modules and are not covered by the commands
+above:
+
+```bash
+cd packages/asymptote-sdk-js && npm ci && npm test && npm run check
+cd browser-extension && npm ci && npm run check && npm run test:unit
+cd plugins/opencode-beacon && bun run check && bun test
+cd plugins/cline-beacon && bun run check && bun test
+cd plugins/pi-beacon && bun run check && bun test
+```
+
+The browser extension's Playwright replay e2e (`npm test` in `browser-extension`) needs `openssl`
+on PATH and a one-time `npx playwright install chromium`. It replays recorded SSE through the real
+extension in headless Chromium, so it is deterministic, needs no login, and costs nothing to run.
diff --git a/CLAUDE.md b/CLAUDE.md
index d77df15c..2dc8d5a0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10,6 +10,7 @@ Beacon Endpoint Agent is a local-only endpoint telemetry agent for AI runtimes.
- `cli/beacon-hooks`: hook adapter invoked by Cursor and other supported runtimes.
- `collector-builder`: OpenTelemetry Collector distribution and Beacon JSONL exporter.
- `packages/asymptote-sdk-js`: TypeScript SDK for cloud agent telemetry that exports Beacon-compatible OpenTelemetry spans.
+- `browser-extension`: optional Chrome MV3 collector that relays Claude.ai and ChatGPT chat telemetry into the local pipeline as OTLP.
- `packaging`: macOS packaging and deployment assets.
Do not recreate or depend on removed `asymptote` mirror trees. Keep new work focused on the Beacon paths above.
@@ -34,6 +35,7 @@ Supported runtime surfaces today:
- Cline hook telemetry through a Beacon-managed local plugin (`~/.cline/plugins/beacon.ts`) covering prompts, task lifecycle, tool lifecycle, commands, file reads/edits with diffs, MCP activity, and task token usage. One plugin serves Cline's VS Code, JetBrains, and CLI hosts; Cline's own OTel export and hosted prompt storage are not used. Approval decisions are not exposed by Cline's hook payloads and are not synthesized.
- Pi hook telemetry through a Beacon-managed local extension (`~/.pi/agent/extensions/beacon.ts`, or `.pi/extensions/beacon.ts` at project level) covering session lifecycle, prompts, tool lifecycle and results, commands including operator `!` commands, file reads/creates/edits with the unified patch, agent reasoning from assistant thinking parts, and token usage/cost. The extension subscribes to seven Pi event types and ignores the streaming and provider internals. Approval decisions are not exposed by Pi's extension API -- its `tool_call` handler can block, but that is an extension deciding rather than an operator being asked -- and are not synthesized, matching the Cline decision.
- Claude Cowork admin-configured OpenTelemetry setup guidance and local validation.
+- Browser chat telemetry through an optional Chrome MV3 extension (`browser-extension/`) covering claude.ai and chatgpt.com. A main-world interceptor tees the streamed response, a per-site adapter parses it into a normalized turn, and the service worker POSTs OTLP GenAI logs to the local collector on `127.0.0.1:4318`; the extension never writes files and never contacts a remote endpoint. `harness.name` resolves to `claude_web` or `chatgpt_web` (already handled by `NormalizeHarnessName` in `pkg/asymptoteobserve/harness.go`, where the browser cases must stay above the generic `claude` rule) and `harness.collection_method` is `otlp`. Scope is deliberately narrow: only those origins' chat streams, never other tabs or general browsing. Retention defaults to `full`, so prompt and response text is retained by default; this is documented rather than defaulted down, because browser chat telemetry without content has no investigative value. Treat the adapters as experimental, since both sites' stream formats are private and undocumented.
- `beaconjson` OpenTelemetry Collector exporter that converts OTLP logs, traces, metrics, and resource attributes into Beacon endpoint JSONL.
- Asymptote Observe TypeScript SDK instrumentation for cloud applications, starting from OpenTelemetry/OpenLLMetry patterns and `observe()` wrappers.
- Elasticsearch/Filebeat content pack generation for forwarding local Beacon JSONL into customer-managed Elastic deployments or the bundled loopback-only development stack.
@@ -44,7 +46,7 @@ Supported runtime surfaces today:
Current non-goals unless explicitly requested:
-- Kernel/process monitoring, EDR replacement, shell history scraping, cloud audit ingestion, browser/SaaS telemetry, credential-use attribution, and MCP configuration inventory.
+- Kernel/process monitoring, EDR replacement, shell history scraping, cloud audit ingestion, general browser or SaaS activity monitoring beyond the supported chat surfaces, credential-use attribution, and MCP configuration inventory.
- Direct hosted integrations for Datadog, Snowflake, Chronicle, Panther, or other SIEM destinations beyond explicitly supported local/customer-managed forwarding patterns.
- Dependency vulnerability scanning or package security remediation.
@@ -119,6 +121,19 @@ npm run build
npm run pack:dry-run
```
+Run browser extension checks. The e2e replays recorded SSE through the real
+extension in headless Chromium, so it needs `openssl` on PATH and a one-time
+Chromium download, but no login and no network:
+
+```bash
+cd browser-extension
+npm ci
+npm run check
+npm run test:unit
+npx playwright install chromium # one-time
+npm test # builds dist/, runs the replay e2e
+```
+
Run the local dashboard during manual testing:
```bash
@@ -358,6 +373,42 @@ Use these npm trusted publisher values:
- Workflow filename: `npm-publish-sdk.yml`
- Environment: leave unset unless the workflow is updated to declare one
+### Browser Extension Release
+
+The browser extension versions independently of the CLI. A pushed `ext-v*` tag
+runs `.github/workflows/release-extension.yml`, which creates its own GitHub
+release carrying the unpacked Chrome build as a zip plus a `.sha256`.
+
+`ext-v*` and the CLI's `v*` trigger cannot collide: GitHub tag patterns anchor at
+the start, so `v*` does not match `ext-v0.1.0`.
+
+Bump the version in **both** `browser-extension/package.json` and
+`browser-extension/src/manifest.json` before tagging. The workflow requires the
+tag and both files to agree and fails otherwise.
+
+```bash
+cd browser-extension
+npm run check && npm run test:unit && npm run build
+cd ../
+git tag -a ext-v<version> -m "ext-v<version>"
+git push origin ext-v<version>
+gh run list --workflow release-extension.yml --limit 5
+```
+
+The zip is unsigned, so its `.sha256` is the only integrity check it has, the
+same posture as the Windows MSI. The workflow proves the artifact works by
+unzipping the published bytes and asserting they are a loadable MV3 extension.
+Verify after the run:
+
+```bash
+gh release download ext-v<version> --repo Asymptote-Labs/agent-beacon \
+ --pattern 'agent-beacon-browser-extension-*-chrome.zip*'
+shasum -a 256 -c agent-beacon-browser-extension-<version>-chrome.zip.sha256
+```
+
+Chrome Web Store publication is not yet wired. Until it is, the zip is loaded
+unpacked through Chrome's developer mode.
+
## Implementation Notes
- Prefer deterministic tests that use `t.TempDir()`, `t.Setenv("HOME", ...)`, fake binaries, and free local ports.
@@ -382,6 +433,8 @@ CI runs:
- `go test ./...` in `collector-builder/exporter/beaconjsonexporter`.
- `go test ./...` in `pkg/asymptoteobserve` (includes threat-rules pack conformance).
- `bun run check && bun test` in `plugins/opencode-beacon`, `plugins/cline-beacon`, and `plugins/pi-beacon`.
+- `npm run check`, `npm run test:unit`, and `npm run build` in `browser-extension` on Node 22, plus a check that the build produced a loadable MV3 extension.
+- Playwright replay e2e in `browser-extension` on ubuntu, running the real extension in headless Chromium against a local HTTPS replay server; the HTML report and traces upload on failure.
- CLI help smoke checks for the public command tree.
- macOS packaging script validation via `packaging/macos/test-endpoint-scripts.sh`.
- macOS endpoint smoke validation via `packaging/macos/smoke-endpoint.sh`.
diff --git a/README.md b/README.md
index b265e0db..3c15c62f 100644
--- a/README.md
+++ b/README.md
@@ -102,6 +102,22 @@ CI, and cloud surfaces.
| [Hermes Agent](https://docs.asymptotelabs.ai/cli/supported-runtimes-hermes-agent) | Shell hooks | Prompt, observed tool, command, file, approval request and response, session lifecycle, and subagent stop telemetry |
| [OpenClaw Gateway](https://docs.asymptotelabs.ai/cli/supported-runtimes-openclaw-gateway) | Gateway-configured OTLP/HTTP | OTLP logs, traces, and metrics from the Gateway diagnostics plugin |
+##### Browser Chat Surfaces
+
+| Agent harness | Collection path | Telemetry coverage |
+| --- | --- | --- |
+| [Claude.ai](https://docs.asymptotelabs.ai/runtimes/browser-extension) | Managed browser extension over local OTLP | Prompt, assistant response, tool call, and token usage telemetry from the claude.ai chat stream |
+| [ChatGPT](https://docs.asymptotelabs.ai/runtimes/browser-extension) | Managed browser extension over local OTLP | Prompt, assistant response, and tool call telemetry from the chatgpt.com chat stream |
+
+The optional Chrome MV3 extension in [`browser-extension/`](browser-extension/) posts OTLP GenAI
+logs to the collector already listening on `http://127.0.0.1:4318/v1/logs`, so browser chat lands in
+`runtime.jsonl` beside agent activity and forwards through the same shippers. It reads only the chat
+streams on those two sites and never writes files.
+
+Treat it as experimental: it parses private, undocumented APIs, so a change on either site can
+interrupt capture until the adapter is updated. **Retention defaults to `full`**, meaning complete
+prompt and response text is retained locally unless you change it in the extension's options page.
+
#### CI Agents
| Harness | Collection path | Telemetry coverage |
diff --git a/SECURITY.md b/SECURITY.md
index 28d79218..6281ddc8 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -12,7 +12,7 @@ For the full enterprise review package, see the
| Area | Default behavior |
| --- | --- |
-| Collection | Local OpenTelemetry receivers on `127.0.0.1` or local `beacon-hooks` adapter execution |
+| Collection | Local OpenTelemetry receivers on `127.0.0.1`, local `beacon-hooks` adapter execution, or the optional browser extension posting to the same loopback receiver |
| Content handling | Retained local telemetry is subject to secret redaction, sanitization, truncation, and event-size limits |
| Forwarding | Optional and customer configured |
| Hosted dependency | None required for normal endpoint collection or hook execution |
@@ -37,6 +37,15 @@ event, endpoint, and harness; optional entities add session, tool, command,
file, approval, MCP-like, prompt, destination, and health context when
available.
+The optional browser extension is a distinct surface. It observes only the chat
+request and response streams on `claude.ai`, `chatgpt.com`, and
+`chat.openai.com`, and posts them as OTLP logs to the same loopback receiver as
+every other source. It has no access to other tabs, browsing history, or page
+content elsewhere, and it never writes files. Its retention setting defaults to
+`full`, so complete prompt and assistant response text is retained in the local
+runtime log unless an operator changes it in the extension's options page.
+Retention is enforced in the browser before anything is sent.
+
Review the full
[data inventory](https://docs.asymptotelabs.ai/cli/security-review-data-inventory).
diff --git a/docs/changelog/cli.mdx b/docs/changelog/cli.mdx
index 7778bf22..fa961f31 100644
--- a/docs/changelog/cli.mdx
+++ b/docs/changelog/cli.mdx
@@ -11,6 +11,34 @@ Stay up to date with the latest changes to the Agent Beacon CLI.
## August 2026
+### Browser extension · August 24, 2026
+
+- **Browser chat is a supported surface** · An optional Chrome MV3 extension
+ relays Claude.ai and ChatGPT conversations into the same local pipeline as
+ agent activity, normalized into the same schema. Its service worker posts OTLP
+ GenAI logs to the collector already listening on `127.0.0.1:4318`, so browser
+ chats land in `runtime.jsonl` beside agent activity and forward through the
+ same shippers. Build it from `browser-extension/`, or download the zip from an
+ `ext-v*` release, then load it unpacked in Chrome.
+- **Narrow by construction** · The extension reads the chat streams on
+ `claude.ai`, `chatgpt.com`, and `chat.openai.com`, and nothing else. It has no
+ access to other tabs, browsing history, or page content elsewhere, and it never
+ writes files. Activity is attributed to the `claude_web` and `chatgpt_web`
+ harnesses, so browser chat stays distinguishable from CLI agents.
+- **Retention defaults to full** · Complete prompt and assistant response text is
+ retained locally. Browser chat telemetry without content has little
+ investigative value, so the default keeps it. Change it to `redacted` or
+ `metadata` in the extension's options page before enabling it on a machine
+ where the same browser profile is used for personal conversations. Retention is
+ enforced in the browser, so under `metadata` the text never leaves the page.
+- **Released on its own tags** · An `ext-v*` tag publishes the unpacked build as a
+ zip with a `.sha256`, independent of the CLI's `v*` releases. The archive is
+ unsigned, and Chrome Web Store publication is not yet available.
+- **Documented boundaries updated** · The security overview, threat model, and FAQ
+ previously listed browser telemetry as out of scope. They now scope that
+ statement to general browser activity, which the extension still does not
+ collect.
+
### Documentation · August 23, 2026
- **One house style across the docs** · Rewrote the pages that had drifted into
diff --git a/docs/concepts/faq.mdx b/docs/concepts/faq.mdx
index 4cabbfff..fba32f6d 100644
--- a/docs/concepts/faq.mdx
+++ b/docs/concepts/faq.mdx
@@ -47,8 +47,10 @@ Beacon can help investigate this when the data appears in emitted prompts, tool
results, command output, file activity, or retained content. That can make it
possible to spot data from an unexpected source in a session timeline.
-Beacon is not a browser monitor, email collector, SaaS audit log collector,
-kernel monitor, or universal data-origin tracker. If a runtime does not expose
+Beacon is not a general browser monitor, email collector, SaaS audit log
+collector, kernel monitor, or universal data-origin tracker. The optional
+browser extension is narrow: it reads the chat streams on claude.ai and
+chatgpt.com and nothing else you browse. If a runtime does not expose
the source content or action, Beacon cannot reconstruct it from outside the
runtime.
diff --git a/docs/docs.json b/docs/docs.json
index ca7632ba..35f0c459 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -160,6 +160,12 @@
"runtimes/hermes-agent",
"runtimes/openclaw-gateway"
]
+ },
+ {
+ "group": "Browser Chat",
+ "pages": [
+ "runtimes/browser-extension"
+ ]
}
]
},
diff --git a/docs/runtimes/browser-extension.mdx b/docs/runtimes/browser-extension.mdx
new file mode 100644
index 00000000..c4c563dd
--- /dev/null
+++ b/docs/runtimes/browser-extension.mdx
@@ -0,0 +1,68 @@
+---
+title: "Browser Extension"
+description: "Asymptote support details for Claude.ai and ChatGPT browser chat telemetry"
+---
+
+## Runtime overview
+
+Asymptote supports browser chat on Claude.ai and ChatGPT through an optional Chrome MV3 extension that relays conversation telemetry into the same local pipeline as agent activity.
+
+The extension is experimental. It reads the chat streams of two sites whose APIs are private and undocumented, so a change on either site can interrupt capture until the adapter is updated.
+
+Browser chat resolves to two harness names, `claude_web` and `chatgpt_web`, so browser activity is attributed separately from CLI agents in the runtime log and the dashboard.
+
+## Prerequisites
+
+Before enabling browser chat telemetry, make sure:
+
+- The Beacon endpoint is installed and running, because the extension posts to the local collector on `http://127.0.0.1:4318/v1/logs`.
+- You have reviewed what the extension retains. It captures full prompt and response text by default.
+- The people whose browsers it runs in know it is there, since it reads their Claude.ai and ChatGPT conversations.
+
+## Collection path
+
+A content script running in the page's main world tees the streamed chat response, a per-site adapter parses it into a normalized turn, and the extension's service worker posts OTLP GenAI logs to the local collector. The `beaconjson` exporter converts those into endpoint events and writes them to the runtime JSONL log, alongside every other source.
+
+The extension never writes files and never contacts a remote endpoint. Delivery is queued in local extension storage and retried with backoff, so a turn survives the service worker being suspended mid-stream.
+
+Events collected this way carry `harness.collection_method` of `otlp`.
+
+## Discovery and status
+
+Asymptote treats the browser extension as a user-installed source. It is not configured by `beacon endpoint install` and has no hook or plugin file on disk.
+
+To confirm it is working, generate a chat turn on either site and look for `claude_web` or `chatgpt_web` events in the runtime log or the local dashboard.
+
+## Install or configuration support
+
+Build the extension from `browser-extension/` in the agent-beacon repository, or download the zip from an `ext-v*` release, then load it unpacked through Chrome's developer mode.
+
+Capture is configured in the extension's own options page: on/off, retention mode, the collector endpoint, and per-site toggles. There is no `beacon` command that configures it.
+
+## Retained content
+
+Retention defaults to `full`. Browser chat telemetry has little investigative value without content, so the default keeps it, and the tradeoff is documented rather than defaulted away.
+
+| Mode | What is retained |
+|------|------------------|
+| `full` (default) | Complete prompt text, full assistant response, tool call arguments and results |
+| `redacted` | The same text with emails and API-key-shaped tokens scrubbed in the browser |
+| `metadata` | No chat text. Actions, models, token counts, and tool names only |
+
+Retention is enforced in the browser before anything is sent, so under `metadata` the text never leaves the page. Endpoint-side redaction, sanitization, truncation, and event-size limits apply to whatever is sent.
+
+Change the mode in the extension's options page before enabling it on a machine where the same browser profile is used for personal conversations.
+
+## Telemetry coverage
+
+| Area | Support |
+|------|---------|
+| Prompt telemetry | Supported, with full prompt text under `full` and `redacted` retention |
+| Assistant response telemetry | Supported, including the response text and model |
+| Tool telemetry | Supported where the chat stream exposes tool calls, including call id, arguments, and results |
+| Token usage | Supported for Claude.ai. ChatGPT web does not report usage in its stream |
+| Command and file telemetry | Not applicable. Browser chat performs no local commands or file edits |
+| Approval telemetry | Not available. Neither site exposes approval decisions to a page script |
+| Session lifecycle | Partial. Turns are correlated by conversation id; there is no session start or stop signal |
+| Local JSONL and dashboard | Supported after events reach the collector |
+| MDM deployment | Not covered by Beacon's MDM assets. Distribute through browser policy instead |
diff --git a/docs/security/data-flow-threat-model.mdx b/docs/security/data-flow-threat-model.mdx
index 58fec6c1..a9e716e9 100644
--- a/docs/security/data-flow-threat-model.mdx
+++ b/docs/security/data-flow-threat-model.mdx
@@ -42,7 +42,9 @@ flowchart LR
## Current boundaries
-Beacon focuses on supported agent harness telemetry and local endpoint configuration context. It does not provide kernel or process monitoring, shell history collection, cloud audit ingestion, browser or SaaS telemetry, credential-use attribution, Datadog API export from Beacon, Sumo Logic API export from Beacon, Rapid7 API export from Beacon, or automatic mutation of Factory Droid shell profiles.
+Beacon focuses on supported agent harness telemetry and local endpoint configuration context. It does not provide kernel or process monitoring, shell history collection, cloud audit ingestion, general browser or SaaS activity monitoring outside the supported chat surfaces, credential-use attribution, Datadog API export from Beacon, Sumo Logic API export from Beacon, Rapid7 API export from Beacon, or automatic mutation of Factory Droid shell profiles.
+
+Browser chat telemetry is limited to the Claude.ai and ChatGPT conversation streams captured by the optional [Agent Beacon browser extension](/runtimes/browser-extension). Beacon does not observe other tabs, browsing history, or page content elsewhere. That extension retains full prompt and response text by default, which is the most sensitive default in the product; see [its retention modes](/runtimes/browser-extension).
Provider-managed cloud agents use a separate ephemeral boundary from the local
endpoint. Their hook adapter writes sandbox-local JSONL and can send compressed
diff --git a/docs/security/index.mdx b/docs/security/index.mdx
index 517bc5da..6d76f1b5 100644
--- a/docs/security/index.mdx
+++ b/docs/security/index.mdx
@@ -88,4 +88,6 @@ For dedicated infrastructure, stricter data boundaries, or residency requirement
## Boundaries
-Beacon currently focuses on endpoint telemetry for supported agent harnesses and local endpoint configuration context. It does not provide kernel or process monitoring, shell history collection, cloud audit ingestion, browser or SaaS telemetry, credential-use attribution, or automatic mutation of Factory Droid shell profiles. Use [Log Forwarding](/log-forwarding) for supported SIEM, observability, object-storage, local JSONL, and customer-managed destinations.
+Beacon currently focuses on endpoint telemetry for supported agent harnesses and local endpoint configuration context. It does not provide kernel or process monitoring, shell history collection, cloud audit ingestion, general browser or SaaS activity monitoring outside the supported chat surfaces, credential-use attribution, or automatic mutation of Factory Droid shell profiles. Use [Log Forwarding](/log-forwarding) for supported SIEM, observability, object-storage, local JSONL, and customer-managed destinations.
+
+Browser chat telemetry is limited to the Claude.ai and ChatGPT conversation streams captured by the optional [Agent Beacon browser extension](/runtimes/browser-extension). Beacon does not observe other tabs, browsing history, or page content elsewhere.