/beacon-lens-create

name: beacon-lens-create
description: Create, revise, debug or validate a Beacon lens, a single HTML file that renders one agent trace as a purpose-built view (a per-file review, a cost breakdown, a timeline of risky commands, a map of tool use) in a sandboxed tab of the local Beacon dashboard, fed once through window.beacon.getTrace(). Use when the user asks to "make a lens", "build a view of my traces", "visualize this session", wants a custom tab next to the full session in the Beacon dashboard, or when a lens fails to load, renders wrong, or needs checking before install.
license: MIT
compatibility: Requires the Beacon CLI (beacon) on PATH with endpoint capture installed, so there are traces to render. Reads only local state and makes no network calls.
metadata:
  author: asymptote-labs
  homepage: https://docs.beacon.sh/concepts/lenses
  version: "0.1.0"

Beacon lens create

A **lens** is one self-contained HTML file that renders one agent trace: the prompts, agent messages, tool calls, commands, file edits, approvals, token usage and threat-rule findings Beacon recorded for a session. The local dashboard (`beacon endpoint dashboard`) shows lenses as tabs on a session's page, next to **Full session**, and runs each one in a locked-down frame.

You write the file, check it against the user's real sessions, and install it. Nothing is published anywhere: lenses live on this machine.

Step 1: check that Beacon is available

beacon version

If `beacon` is not found, tell the user that lenses need the Beacon CLI, point them to https://docs.beacon.sh/get-started/overview, and stop. Do not install it yourself.

Step 2: decide what the lens shows

Start from the user's description. If it is missing, or leaves a choice open that changes what the numbers mean (what counts as a "turn", a "failure", a "risky" command, which cost total), ask one focused question before building. Define each unit from this request, not from another lens, and label anything derived or estimated as such.

Step 3: read the spec and the real data

beacon lenses spec              # the format, the data, the sandbox, the style tokens
beacon lenses spec --example    # a complete working lens to start from
beacon lenses list              # lens ids already in use
beacon lenses data              # exactly what getTrace() returns for the latest session
beacon lenses data --session <session-id>

Read the whole spec before writing anything. Then look at real data rather than guessing its shape from the spec: note which event `type`s the user's sessions carry, whether `file.diff`, `command.output` or `usage` is present, and whether `findings` exists. Design for those, and for sessions that lack them. The output contains whatever content the log retained (prompts, command output, diffs), so read it locally and do not paste large amounts back to the user.

Step 4: write the file

One HTML file. No build step, bundler or `package.json`. Write it in the user's project or a scratch directory, never directly in the lens store.

Hard limits

The dashboard enforces these; a lens that breaks them fails to install or fails to run.

• **One file, at most 16 MiB**, with every script, style, image and font inline (`data:` URIs for

images and fonts). Inlining a library is allowed but counts against the size and costs parse time on every open; prefer a few lines of your own.

• **A manifest**, in exactly one element whose opening tag is spelled exactly

`<script type="application/beacon-lens+json">`, holding `id`, `title`, `version` and `"api": "beacon.lens.v1"` (optionally `description`, `icon`, `author`; unknown keys are an error). The `id` is lowercase letters, digits and hyphens, and cannot be a built-in lens's id.

• **No network and nothing loaded by URL.** The frame's Content Security Policy blocks `fetch`,

XHR, WebSockets, `EventSource`, `sendBeacon`, remote scripts, stylesheets, fonts and images, `@import`, workers, nested frames, `eval` and `new Function`.

• **No dashboard access.** The frame is `sandbox="allow-scripts"` with an opaque origin: no

cookies, `localStorage`, `sessionStorage` or IndexedDB, no access to the parent page, no popups or forms. Keep state in memory.

• **Never navigate the frame.** The dashboard closes a lens that loads a second document.

The data

The host defines `window.beacon` before your scripts run. Its one call is the whole data API:

const data = await window.beacon.getTrace();

It resolves once with everything you get and never refreshes. Calling it again returns the same promise. It rejects with an `Error` if the trace does not arrive within 10 seconds; show that message instead of a blank tab.

The result is `LensDataV1`; `beacon lenses spec` has the full shape. The parts you will use most:

• `trace.summary`: title, `started_at`/`ended_at`, `event_count`, `harness.name`, `session`,

`repository`, `model`, `token_usage`.

• `trace.events[]`, in order, each with `id`, `number`, `timestamp`, `type`, `action` and

optional `title`, `summary`, `fidelity`, `content`, `tool`, `command`, `file`, `mcp`, `approval`, `policy`, `error`, `model`, `usage`, `tool_call_id`. `error.type` is set when the runtime reported the action as failed, even on an event whose `type` is not `error`. `type` is one of `user_message`, `agent_message`, `agent_reasoning`, `tool_call`, `tool_result`, `command`, `file`, `mcp`, `approval`, `token_usage`, `session`, `error`, `other`, and the list can grow.

• `findings`: threat-rule matches, each pointing at its evidence by `event_ids`.
• `token_usage` and `token_coverage`: the trace's counted usage, and whether this runtime reports

usage at all.

• `truncated`: the trace was cut to fit the size cap.

Things that are easy to get wrong:

• **Retained text is an object, not a string.** Prompts, messages, `command.output` and

`file.diff` arrive as `{text?, included, retention, redacted?, truncated?,