Logs show what happened. A marker says which moment mattered.
Use Agent Markers when a bug appears during real app use and the next agent needs more than a sentence and a screenshot. The move is to mark the decisive moment while it is happening, capture nearby runtime evidence, add the human explanation, review the packet, and export only what is safe to share.
mark -> capture -> explain -> review/export
The Problem
You found the bug while using the app. The checkout button stayed disabled, the billing retry fired twice, the auth session rotated at the wrong time, or the date rendered in the wrong format.
We're interacting with an app, we're clicking on buttons, and we're typing in fields, and then something happens, and we want to be able to capture that specific moment. We don't want to have to quit our app, start up debugging mode.
— John Lindquist
The old ritual is expensive:
- add temporary logs
- reproduce the bug
- forget which log line mattered
- remove the logs
- hope the next agent understands the state you saw
A debug marker preserves the moment without turning the whole session into a permanent logging project.
Bounded Debug Packets
A bounded debug packet is a small export centered on one marked moment.
It can include:
- the marker label and note
- nearby console, fetch, error, unhandled rejection, and manual events
- route, viewport, and environment metadata
- optional DOM or screenshot evidence
- the privacy review boundary
- the first verification command for the next agent
It is not a replay system, production telemetry, a browser extension, a server product, or an AI product. It is a reviewed packet for debugging work.
Smallest Setup
import { createAgentMarkers } from "<verified-agent-markers-client>";
const markers = createAgentMarkers({
appName: "checkout-demo",
exposeGlobal: true
});
await markers.mark("Checkout button stayed disabled", {
note: "Expected it to enable after selecting shipping.",
tags: ["checkout", "regression"]
});
const session = markers.export();
createAgentMarkers sets up a browser-side collector. It can mark moments, record manual events, export a DebugSession, optionally expose a dev/test global, and clean itself up with stop().
The Data Model
| Concept | Practical Meaning |
|---|---|
DebugSession |
One bounded debugging run: app name, session id, environment, markers, and events. |
DebugMoment |
The human marker: label, note, tags, severity, environment, optional data, optional DOM/screenshot evidence, and nearbyEventIds. |
CapturedEvent |
Runtime evidence near the marker: console, fetch, error, unhandled rejection, or manual event. |
nearbyEventIds |
The bridge between the marked moment and the runtime events captured near it. |
| export JSON | The reviewed packet that can be attached to a test run, issue, or agent prompt. |
The useful part is the link between the human explanation and the runtime trail. Without nearbyEventIds, the agent gets a label and starts guessing. With it, the agent gets a bounded slice of the session.
Privacy Defaults
Field rule: metadata first, values only after review.
Agent Markers is designed around a local review boundary:
- data stays in memory until explicit export
- storage capture records key names and counts by default, not values
- fetch capture records metadata and does not read request or response bodies
- treat raw exported sessions as private until reviewed and redacted
Do not share raw exported sessions. Review and redact private routes, screenshots, stack traces, request URLs, user-entered text, tokens, cookies, account data, local paths, and application-specific identifiers.
Test Runner And Agent Handoff
In dev and test, exposeGlobal: true gives a test runner a browser handle:
window.__AGENT_MARKERS__
A browser test can reproduce the bug, call mark(...), export JSON to a private test artifact, and attach or share only a reviewed and redacted packet. The next agent gets a bounded packet instead of a vague report.
You can take that kind of entire session, you can copy and paste the logs into your agent. And tell it, please review for the markers and help me get this fixed.
— John Lindquist
Treat the redaction helper below as project-specific review code, not an Agent Markers API.
const session = await page.evaluate(async () => {
await window.__AGENT_MARKERS__.mark("checkout disabled unexpectedly", {
note: "Expected submit to enable after terms and shipping were selected."
});
return window.__AGENT_MARKERS__.export();
});
const redactedSession = redactAgentMarkerSession(session);
await testInfo.attach("agent-markers.redacted.json", {
body: JSON.stringify(redactedSession, null, 2),
contentType: "application/json"
});
Import from the reviewed Agent Markers client in the current project. Verify the package or workspace path before turning this into executable setup.
The handoff prompt should tell the agent:
- what the human expected
- what happened instead
- which event ids are nearby
- what is intentionally redacted
- where to start verification
- what not to infer from missing data
Clean Up
Call stop() when the collector is done.
The collector installs capture hooks for useful evidence. stop() disposes those hooks. After stop(), treat the collector as finished instead of continuing to mark new moments.
Copyable Artifact: Bounded Debug Packet
Marker:
- label:
- note:
- expected:
- actual:
- next action:
Session:
- schemaVersion:
- sessionId:
- appName:
- markerId:
- nearbyEventIds:
Included evidence:
- console:
- fetch:
- error:
- unhandledrejection:
- manual:
- DOM or screenshot availability:
Privacy review:
- storage values exported? no
- request bodies exported? no
- response bodies exported? no
- private routes removed?
- user-entered text removed?
- stack paths reviewed?
- screenshot reviewed?
Handoff:
- first verification command:
- files or areas to inspect:
- what the agent must not infer:
- stop condition:
Example prompt:
Use this bounded debug packet to investigate the checkout disabled-state bug.
Start from the marker note and nearbyEventIds.
Do not assume redacted fields are absent in the app.
Inspect the checkout form state, shipping selection flow, and submit-button disabled logic.
Return the likely cause, smallest patch plan, and first verification command before editing.
Claim Boundaries
Agent Markers gives the next agent a better packet. It does not guarantee the agent will find the defect automatically.
Use it for local development, browser tests, and reviewed debugging artifacts. Verify any production use, data retention policy, screenshot capture, source-map behavior, and privacy implications before adopting it in a real product.