---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-marker-workflows-reference"
title: "Agent Markers debugging workflows: practical reference"
---

# Agent Markers debugging workflows: practical reference

## Agent Setup Prompt

```text
Set up the agent-markers files and configuration for this browser project, then verify the setup before investigating any specific bug.

1. Inspect the existing agent-markers package and demo files first:
   - packages/client/src/index.ts
   - packages/client/src/collector.ts
   - packages/client/src/types.ts
   - packages/client/src/capture/console.ts
   - packages/client/src/capture/fetch.ts
   - packages/client/src/capture/errors.ts
   - packages/client/src/serialize.ts
   - apps/demo/src/main.ts
   - apps/demo/src/viewer.ts
   - scripts/smoke-demo.mjs
   - docs/WORKSHOP.md

2. If the package or demo is missing, scaffold the smallest matching structure. If files already exist, preserve the current API where possible and extend it only as needed.

3. Define or confirm the core schema:
   - DebugSession: one bounded run with sessionId, appName, schemaVersion, CapturedEvent[], and DebugMoment[]
   - CapturedEvent: id, sequence, timestamp, type, and metadata for console, fetch, error, manual, DOM, screenshot, or app events
   - DebugMoment: id, label, note, optional nextAction, timestamp, and nearbyEventIds that reference CapturedEvent ids
   - export JSON: a JSON-serializable packet that can be saved, attached to a test run, or passed to another agent

4. Implement or confirm createAgentMarkers in packages/client/src/index.ts. It should accept appName, exposeGlobal, and capture options for console, fetch, and errors. It should return mark(...), export(), and stop().

5. Implement console, fetch, error, and manual capture:
   - console capture records log/warn/error metadata without creating recursive logging loops
   - fetch capture records URL, method, status, timing, and failure metadata
   - error capture records thrown errors and unhandled rejections
   - manual capture records marker labels, notes, nextAction, and timing
   - all captured events should receive stable ids and sequence numbers

6. Add privacy-safe defaults:
   - capture metadata by default
   - do not export storage values, cookies, tokens, request bodies, response bodies, private DOM text, or screenshots unless deliberately enabled and reviewed
   - redact sensitive query params, headers, stack paths, and visible private text before saving export JSON
   - include redaction notes in the exported packet

7. Implement the collector in packages/client/src/collector.ts. Store events in order, enforce a maximum event count, and calculate nearbyEventIds for each DebugMoment using sequence or timestamp proximity.

8. Implement serialize.ts so export() always returns valid JSON without circular references. Optional DOM or screenshot fields should be marked unavailable when no hook is configured.

9. Wire createAgentMarkers into the demo app in apps/demo/src/main.ts with exposeGlobal: true for dev/test and capture enabled for console, fetch, and errors. Add a manual marker entrypoint such as a debug button or keyboard shortcut that calls markers.mark({ label, note, nextAction }).

10. Wire apps/demo/src/viewer.ts so the current session can be exported, displayed, copied, or downloaded as JSON.

11. Expose the dev/test global surface when configured:
   - window.__AGENT_MARKERS__.mark(...)
   - window.__AGENT_MARKERS__.export()
   - window.__AGENT_MARKERS__.stop()

12. Add test-runner export. In a Playwright-style test or equivalent, wait until the app is ready, call window.__AGENT_MARKERS__.mark(...), export the session with page.evaluate, and attach or save agent-markers.json. Assert markers.length > 0, a non-empty note exists, nearbyEventIds is present, and console/fetch/error/manual events appear when enabled.

13. Add bounded replay packet setup for one marker. The packet should include schemaVersion, sessionId, markerId, markerCutoffSeq, nearbyEventIds, filtered console/fetch/error/manual evidence, optional DOM/screenshot availability, included and excluded boundaries, maximum event count, redaction status, and the first verification command. Do not build a full recorder.

14. Update scripts/smoke-demo.mjs so it can launch or exercise the demo, create one marker, trigger at least one console event, fetch event, and error event where practical, export JSON, parse it, and confirm the packet is non-empty.

15. Verify with the available project commands:
   - npm test
   - npm run typecheck
   - npm run build
   - npm run smoke:demo

16. Confirm setup worked:
   - createAgentMarkers imports and initializes
   - mark() creates a DebugMoment with a specific note
   - nearbyEventIds is non-empty after nearby capture activity
   - exported events include console, fetch, error, and manual types when enabled
   - export JSON parses cleanly
   - window.__AGENT_MARKERS__ is available in dev/test only
   - stop() restores patched console, fetch, and error listeners
   - test-runner export saves or attaches agent-markers.json
   - privacy defaults exclude sensitive values

Report the files changed, setup choices, verification commands and results, sample export path, privacy boundaries, unavailable hooks, and any failed checks. If setup checks fail, stop and report the blocker. Do not debug a specific product bug until the setup and verification pass.
```

## Big Idea

Start by sending cheap perspective-based agents through weird paths. Then use
agent markers to capture the exact moment that should become a bounded debug
packet.

Core pattern:

```text
5 Monkeys QA -> mark -> capture -> explain -> review/export
```

The 5 Monkeys pattern finds strange states a happy-path check would miss. Agent
markers turn one of those strange states into evidence another agent can use.

An agent marker is a human-intent anchor inside a debugging workflow.

It answers:

- why this moment mattered
- what evidence was nearby
- what should be inspected next
- what the next human or agent should not waste time guessing

Agent markers are not full replay systems. They are bounded debug packets.

## Try This Now

Create one marker for a checkout UI bug:
`window.__AGENT_MARKERS__.mark({ label: "checkout disabled unexpectedly", note: "Expected submit to enable after terms and shipping were selected." })`
Export the session and check that the marker has nearby evidence, not just a label.

## Start With 5 Monkeys

Use 5 Monkeys before marker capture when the bug is vague, stateful, or hidden
behind normal user behavior.

Assign one lens per pass:

| Lens | What It Tries |
| --- | --- |
| expert power user | shortcuts, fast navigation, hidden affordances |
| brand-new first-time user | confusion, missing affordances, unclear copy |
| inexperienced user | accidental clicks, mistaken paths, recovery failures |
| impatient returning user | rapid clicks, skipped steps, partial flows |

Make each pass explore weird paths:

- keyboard shortcut sequences
- back/forward navigation mid-flow
- repeated or rapid clicks on one control
- toggling modes back and forth
- starting a flow, then bailing out
- refreshing or re-entering with partial state

Write each pass to a discardable QA note such as `.notes/qa-01.md`. Collate the
findings, keep only useful bugs, and mark the one moment that best captures the
state failure.

Then capture that moment with agent markers:

```text
weird state found -> human marks the decisive moment -> export nearby evidence
```

Do not replace stable business-logic tests with 5 Monkeys. Use it to discover
UI and state failures that tests and logs did not already isolate.

## Files To Inspect

Agent markers project references:

```text
packages/client/src/index.ts
packages/client/src/collector.ts
packages/client/src/types.ts
packages/client/src/capture/console.ts
packages/client/src/capture/fetch.ts
packages/client/src/capture/errors.ts
packages/client/src/serialize.ts
apps/demo/src/main.ts
apps/demo/src/viewer.ts
scripts/smoke-demo.mjs
docs/WORKSHOP.md
```

## When To Reach For This

Use markers when logs are real but the important moment still needs human context.

| Use Markers For | Why |
| --- | --- |
| checkout bug | mark the exact UI state where expected and actual diverge |
| auth/session refresh issue | capture nearby fetch/error/console evidence around the failure |
| billing admin UI failure | attach human expectation to the visible broken state |
| flaky browser test | export a debug packet from the test runner |
| design/debug review | pair screenshot/DOM hooks with a human explanation |
| long agent debugging session | leave explicit breadcrumbs for the next pass |

Skip markers when:

- one failing unit test already isolates the bug
- a stack trace points to one obvious line
- no one can explain why the moment matters
- the capture would expose sensitive data without redaction
- the task needs full deterministic replay rather than a bounded debug packet

## How This Used To Work

What you used to expect:

```text
If enough logs are captured, the agent can infer the important moment.
```

What the workflow gives you now:

```text
Logs show events. A marker ties a specific moment to human intent, nearby
evidence, and the next debugging question.
```

What you used to expect:

```text
A screenshot or console dump is enough context.
```

What the workflow gives you now:

```text
The useful packet combines the marker note, nearby console/fetch/error/manual
events, optional DOM or screenshot capture, privacy boundaries, and an export.
```

## The Mental Model

```text
DebugSession
-> CapturedEvent[]
-> DebugMoment[]
-> export JSON
-> agent prompt / test artifact / work unit
```

| Concept | Meaning |
| --- | --- |
| `DebugSession` | one bounded debugging run |
| `CapturedEvent` | console, fetch, error, manual, DOM, screenshot, or app event |
| `DebugMoment` | the human marker: label, note, timestamp, nearby evidence |
| `nearbyEventIds` | event ids around the marked moment |
| export JSON | portable debug packet |
| `stop()` | cleanup that restores patched browser APIs |

## Basic Browser Setup

Create markers in a browser app:

```ts
import { createAgentMarkers } from "@agent-markers/client";

const markers = createAgentMarkers({
  appName: "checkout-app",
  exposeGlobal: true,
  capture: {
    console: true,
    fetch: true,
    errors: true,
  },
});
```

Expose a manual marker action:

```ts
document.querySelector("#mark-debug")?.addEventListener("click", () => {
  markers.mark({
    label: "checkout payment method disappeared",
    note: "Expected saved payment selector to stay visible after refresh.",
  });
});
```

Export:

```ts
const session = markers.export();
console.log(JSON.stringify(session, null, 2));
```

Clean up patched APIs:

```ts
markers.stop();
```

## Global Test Surface

In dev/test, expose the marker surface:

```ts
createAgentMarkers({
  appName: "checkout-app",
  exposeGlobal: true,
});
```

Then inspect from the browser console or a test runner:

```js
window.__AGENT_MARKERS__.mark({
  label: "checkout failure",
  note: "Expected saved cards to render before submit.",
});

const session = window.__AGENT_MARKERS__.export();
session.markers.length;
```

Use the global for test export, not as the only application API.

## Capture Types

| Capture | What It Adds | Watch For |
| --- | --- | --- |
| console | logs, warnings, errors | noisy output |
| fetch | request URL, method, status, timing | request/response bodies may be sensitive |
| errors | thrown errors and unhandled rejections | stack traces may include private paths |
| manual | human-entered labels and notes | must be specific |
| DOM hook | optional host-provided DOM snapshot | avoid private text |
| screenshot hook | optional host-provided image capture | unavailable in some environments |
| storage metadata | keys/counts, not full values by default | never dump secrets by accident |

Privacy rule:

```text
Capture metadata by default. Capture values only when deliberately enabled and safe.
```

## Marker Shape

A useful marker has:

```json
{
  "label": "checkout saved card missing",
  "note": "Expected saved payment methods to appear after login refresh; actual UI shows empty selector.",
  "nextAction": "Inspect auth refresh state, checkout payment query, and recent fetch events."
}
```

Weak marker:

```json
{
  "label": "broken"
}
```

Better marker:

```json
{
  "label": "saved payment selector empty after refresh",
  "note": "At this moment the user is logged in, the account menu shows the correct user, but checkout has no saved cards.",
  "nextAction": "Compare account payment fetch response with checkout payment state."
}
```

## Export A Debug Packet

Export from browser:

```js
const session = window.__AGENT_MARKERS__.export();
console.log(JSON.stringify(session, null, 2));
```

Save in a test:

```ts
const session = await page.evaluate(() => window.__AGENT_MARKERS__.export());
await testInfo.attach("agent-markers.json", {
  body: JSON.stringify(session, null, 2),
  contentType: "application/json",
});
```

Or write to disk in a local script:

```js
const session = await page.evaluate(() => window.__AGENT_MARKERS__.export());
await fs.promises.writeFile(
  "artifacts/agent-markers/checkout-session.json",
  JSON.stringify(session, null, 2)
);
```

## Verify The Project

Common checks:

```bash
npm test
npm run typecheck
npm run build
npm run smoke:demo
```

What to look for:

- marker can be created
- marker has a human explanation
- nearby events are linked with `nearbyEventIds`
- console/fetch/error/manual events appear when enabled
- storage values are not dumped by default
- export JSON is valid
- `stop()` restores patched browser APIs
- test runner can access `window.__AGENT_MARKERS__`

## Turn A Marker Export Into An Agent Prompt

Prompt shape:

```markdown
# Debug Prompt From Agent Marker

## Source Artifact

- marker export:
- schema version:
- marker id:
- marker label:

## Human Explanation

- expected:
- actual:
- why this moment matters:
- next action:

## Nearby Evidence

- console:
- fetch:
- error:
- manual:
- screenshot:
- DOM:

## Privacy Boundary

- storage values exported? no
- request bodies exported? no
- response bodies exported? no
- private text removed:

## Task

Find the smallest likely bug path and propose the first verification command.
Do not invent app state that is not in the marker packet.
```

## Bounded Replay Capsule

Do not build a full recorder. Design the smallest packet that makes the marked moment inspectable.

```markdown
# Bounded Replay Capsule

- schemaVersion:
- markerId:
- sessionId:
- markerCutoffSeq:
- nearbyEventIds:
- console:
- fetch:
- errors:
- manual:
- screenshot:
- dom:
- redaction:

## Boundaries

- included:
- excluded:
- maximum event count:
- privacy rules:

## How To Use It

- agent prompt:
- human review:
- verification command:
```

## App-Specific Marker Flow

An app may wire a shortcut such as `Ctrl+M` to create durable marker evidence.

Conceptual flow:

```text
Ctrl+M
-> create marker id
-> capture screenshot if available
-> open note/explanation UI
-> save human explanation
-> write durable app logs
```

Expected log strings:

```text
dev_marker
dev_marker_explanation
```

Inspection shape:

```bash
rg -n "dev_marker|dev_marker_explanation" <app-log-path>/latest-session.jsonl
```

Keep this generic:

- one marker id shared across marker and explanation
- screenshot optional
- explanation required
- bounded nearby evidence
- clear next action

## Ask The Agent This

Add markers to a browser bug investigation:

```text
Add agent markers to the checkout browser flow.

Capture console, fetch, errors, and manual markers. Expose
`window.__AGENT_MARKERS__` in dev/test. Add a marker for the moment saved
payment methods disappear after auth refresh. Export JSON and show how to
confirm nearbyEventIds, privacy defaults, and marker explanation.
```

Turn export into a debug prompt:

```text
Use this agent-marker export as the bounded debug packet.

Focus on the marked checkout failure. Summarize the human explanation, nearby
console/fetch/error/manual evidence, privacy boundaries, and the first
verification command. Do not infer app state that is not in the packet.
```

Write a test export:

```text
Create a Playwright-style test path that triggers the checkout bug, calls
`window.__AGENT_MARKERS__.mark(...)`, exports the session JSON, and attaches it
as a test artifact. Include the checks that prove marker count, nearbyEventIds,
and event types are present.
```

## What To Confirm / How To Know It Worked

| Goal | Confirmation |
| --- | --- |
| marker client installed | app imports `createAgentMarkers` |
| marker created | export has `markers.length > 0` |
| explanation present | marker has a specific `note` |
| nearby evidence linked | marker has non-empty `nearbyEventIds` |
| console captured | exported events include console type |
| fetch captured | exported events include fetch type |
| errors captured | exported events include error type |
| privacy default safe | storage values are absent unless deliberately enabled |
| global test surface works | `window.__AGENT_MARKERS__.export()` returns session |
| export saved | JSON artifact exists and is non-empty |
| cleanup handled | `stop()` called when patching should end |
| project verifies | `npm test`, `npm run typecheck`, `npm run build`, `npm run smoke:demo` |

## If It Goes Wrong

### Marker Has No Note

Add expected/actual context.

```text
What should have happened:
What happened:
Why this moment matters:
Next action:
```

### Export Has Too Many Raw Logs

Focus on one marker id and its nearby events. Increase event limits deliberately, not by default.

### `nearbyEventIds` Is Empty

Mark closer to the failure or adjust the nearby event window.

### Sensitive Storage Values Were Captured

Redact and rebuild the export. Capture storage metadata, not values, unless safe and intentional.

### Console/Fetch Remains Patched

Call:

```ts
markers.stop();
```

### Test Runner Cannot Export

Confirm `exposeGlobal: true` in dev/test and wait for app readiness before reading `window.__AGENT_MARKERS__`.

### Screenshot Or DOM Hook Is Missing

Mark it unavailable. Do not pretend a screenshot or DOM snapshot exists.

## References And Resources

- Agent marker client entry: `packages/client/src/index.ts`
- Collector source: `packages/client/src/collector.ts`
- Types: `packages/client/src/types.ts`
- Demo app: `apps/demo/src/main.ts`
- Viewer/export UI: `apps/demo/src/viewer.ts`
- Smoke script: `scripts/smoke-demo.mjs`
- Playwright docs: https://playwright.dev/docs/test-assertions
- Cypress docs: https://docs.cypress.io/

## Related resources

- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
- [Resource directory and portable download](/topics/codex-resources/)

## Original references

- [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
