You've probably seen the routine. The agent changes some code, runs the formatter, the type checker, and the tests, everything comes back green, and you get some version of "Implemented and verified."

But verified how, exactly? A passing test suite is useful evidence, but it isn't the same as opening the app and using the thing that just changed.

I've had plenty of changes where the code made sense and the tests passed, and the UI still had the kind of problem a person spots in about three seconds. A control overlapping something else. A selected state that exists in the store but isn't highlighted on screen. Reset working for one path and not another. A filter that updates state but leaves the old data on the page. Save looking fine until you refresh. A map layer drawn in the wrong order. A modal that technically opens but doesn't fit on the screen.

The agent had tested its code, but nobody had tested the application. So I started making browser review part of the definition of done for anything user-facing, and a few weeks in, that habit turned into a tool. I'll get to that near the end.

In this article, you'll learn how to give a coding agent a real browser with Playwright MCP, and how to write the instructions that make it test the change it just made instead of confirming that a page loads.

You'll see how to have the agent start your app the way your project already starts it, how to split those instructions between AGENTS.md and a reusable skill, why a separate reviewer agent catches bugs the author misses, and how to make the agent clean up only what it started.

In the last part, I'll walk through katalepsis, the open source tool this turned into, including how it decides whether a check really passed.

Table of Contents

• Prerequisites

• The Loop Agents Are Missing

• Why a Browser on Its Own Falls Short

• How to Start the Real App

• Where the Instructions Live

• Why the Reviewer Should Work Independently

• Clean Up After Yourself and Only Yourself

• When a Skill Stopped Being Enough

• How to Try katalepsis

• How katalepsis Works Under the Hood

• What Happened When I Used It

• Where I Landed

Prerequisites

This isn't a beginner tutorial, so it helps to have:

• Some experience with a coding agent that supports MCP (Model Context Protocol), such as Claude Code, Codex, or Cursor, and an idea of how you give it instructions.

• A web app you can run locally with a dev script, written in JavaScript or TypeScript. The examples use a Node project with pnpm, but nothing depends on a specific framework.

• Basic Playwright knowledge: what a test, a locator, and an assertion look like. You don't need an existing test suite to follow the first half.

• Node.js 20 or newer for Playwright MCP, and Node.js 22.12 or newer plus Git if you want to install katalepsis.

• Comfort with the terminal and Git, since the agent will be starting processes and checking git status.

The Loop Agents Are Missing

Coding agents got useful quickly in large part because they already have a decent feedback loop for code. They read, edit, and run the formatter and tests, read the failure, and try again. Nobody has to get it right in one heroic attempt.

For frontend work, the clear missing input is the frontend itself. The loop I want goes a bit further: edit the code, run the tests, start the app, use the changed feature, look at what happened, fix whatever's broken, and then use it again.

That last step matters more than you might think. Agents are very comfortable telling you a fix "should now work", and I'd rather they just open the page again and find out.

Playwright MCP is a good way to give them that. I already used Playwright for E2E tests, but the MCP server is useful for a different reason: it hands the agent a browser directly. It can open localhost, read the page, find controls, click and type, check what changed, and take screenshots.

That isn't the same as asking the agent to run pnpm playwright test. The test suite tells you whether the scenarios you already wrote down still pass. Browser review asks what this particular change could have affected and goes to look.

If an agent refactors some shared map-layer utilities, the tests might cover a few helpers. But from the diff, it can also work out that the code runs during initial render, selection, filtering, and reset, and try each of those. That's a lot closer to how I review my own frontend work.

Setup is small. You need Node 20 or newer and an MCP-capable client:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

A quick sanity check is to ask the agent to open the Playwright TodoMVC demo, add a todo called "Browser QA," and confirm it shows up. If it manages that, it has a browser. What it does with one is the harder part.

Why a Browser on Its Own Falls Short

Giving an agent a browser only gives it the ability to look. It doesn't tell the agent what to look at, how far to go, or what counts as proof, and without that it falls back to the cheapest thing that technically involves a browser. An agent with Playwright can still do hilariously weak QA. I've had reports like this:

Opened /route.
Page loaded successfully.
Browser verification complete.

That's a report about opening a page, not about testing a change. Nothing in it would have caught any of the bugs from the start of this article.

So the browser needed instructions to go with it. What follows are the rules I wrote for how an agent should review its own frontend work: what to test, what to check, and what evidence to bring back. They started as a few lines I kept repeating in prompts, and they later became the browser-review skill you'll see in the next sections.

The first rule I settled on is that the review has to come from the change. If it changed a filter, use the filter. If it changed reset logic, change some state first and then reset it. If it touched persistence, refresh the page. If it changed a modal, open and close the modal, and if it changed responsive layout, resize the viewport.

That all sounds obvious when a person says it, but it isn't obvious at all if your agent instructions just say "verify that the app works".

In practice, this means the agent reads the diff and turns it into a short test plan before it touches the browser. For a change to a filter bar, the plan I'd expect looks something like this:

Changed: src/features/projects/FilterBar.tsx, src/features/projects/useFilters.ts

Plan:
1. Open /projects and note how many rows are showing.
2. Filter by Status: Active. Every row should say Active.
3. Add Owner: me on top. The list should narrow again.
4. Clear filters. The original row count should come back.
5. Apply a filter and refresh. The filter lives in the URL, so it should survive.

Then it carries out that plan through the browser tools Playwright MCP exposes. A trimmed version of the calls for the first few steps looks like this:

browser_navigate   { "url": "http://localhost:5173/projects" }
browser_snapshot   {}                      → table with 40 rows
browser_click      { "element": "Status filter", "ref": "e14" }
browser_click      { "element": "Active option", "ref": "e31" }
browser_snapshot   {}                      → table with 12 rows, all "Active"
browser_click      { "element": "Clear filters", "ref": "e15" }
browser_snapshot   {}                      → table with 40 rows

The ref values come from the accessibility snapshot, which is how the agent finds a control without guessing at CSS selectors.

This paid off on a PR that fixed a cursor getting stuck in its hover state on an interactive map. The PR's new unit tests passed against the old code too, so they didn't prove the fix did anything. What did prove it was the agent opening the app, moving on and off the interactive layers, and watching the cursor change and reset exactly when it should.

The second rule is to check the end result rather than the interaction. "I clicked Reset and nothing threw" doesn't tell you much. What you actually care about is that reset puts things back the way they were. Same with saving: the real claim is that you can change a setting, save, refresh, and it's still there.

Written as a Playwright test, that claim looks like this. The important line is the last one, which runs after the reload:

import { test, expect } from "@playwright/test";

test("weekly digest setting survives a reload", async ({ page }) => {
  await page.goto("/settings/notifications");
  await page.getByRole("switch", { name: "Weekly digest" }).click();
  await page.getByRole("button", { name: "Save" }).click();

  await page.reload();

  await expect(page.getByRole("switch", { name: "Weekly digest" })).toBeChecked();
});

The agent doesn't need to write this test to follow the rule. Through MCP it does the same thing by hand: click, save, browser_navigate to the same URL, and read the switch's state from a fresh snapshot.

I also ask for different evidence depending on the question. Whether the URL changed, a button is disabled, or a dialog opened is a question for the DOM and browser state, not a screenshot. Whether that dialog is clipped, two things overlap, or text wraps badly on a phone is a visual question, and that's where screenshots are useful. Sometimes you need both, since a modal can sit happily in the DOM while being unusable on screen.

For a layout change, that means resizing and capturing what a person would actually see:

browser_resize            { "width": 375, "height": 812 }
browser_click             { "element": "Export button", "ref": "e22" }
browser_take_screenshot   { "filename": "export-dialog-375.png" }
browser_resize            { "width": 1440, "height": 900 }
browser_take_screenshot   { "filename": "export-dialog-1440.png" }

While it's in there, the agent may as well look at the console and, when the feature depends on an API call, the network. I only care about errors the change introduced, though. A warning that's been on main for six months shouldn't derail every review, and a client-only transition doesn't need a network audit. If a save that "worked" actually got a 500, I want to hear about it.

browser_console_messages and browser_network_requests return what the page logged and requested, so a failed save shows up as a line like this even when the UI looked fine:

[PUT] http://localhost:5173/api/settings => [500] Internal Server Error

Put together, the rules turn the weak report from the start of this section into something I can actually check:

Route: /settings/notifications
Did: turned on "Weekly digest", clicked Save, reloaded the page.
Checked: switch still on after reload (aria-checked="true");
  PUT /api/settings returned 200; no new console errors.
Screenshots: settings-375.png, settings-1440.png (label wraps cleanly on mobile)
Tests: pnpm test settings (14 passed)
Found and fixed: Save stayed disabled after the first save. Fixed in
  SettingsForm.tsx, then went through the flow again.

How to Start the Real App

The agent can't test anything until the app is running, and this is where it's most tempting for it to take shortcuts.

I didn't want to write "run pnpm dev" into every repository, so the procedure tells the agent to work out how the project starts. It checks the dev script in package.json first, then whatever the README documents, and only falls back to an existing Docker setup if the app can't reasonably run otherwise.

The procedure here is the "Start the application" section of the browser-review skill, which you'll see in full in the next section. In a typical Vite or Next.js project, following it looks something like this:

# 1. How does this project start?
jq .scripts package.json
# {
#   "dev": "vite",
#   "build": "vite build",
#   "test": "vitest run",
#   "e2e": "playwright test"
# }

# 2. Start the dev server in the background, in a temp folder the agent owns,
#    and record the PID so it can stop exactly this process later.
QA_DIR=$(mktemp -d)
pnpm dev --port 5173 > "$QA_DIR/dev.log" 2>&1 &
echo $! > "$QA_DIR/dev.pid"

# 3. Wait until the server answers before opening a browser.
until curl -sf http://localhost:5173 > /dev/null; do sleep 1; done

If there's no dev script, the README is next, and if the README says the app needs Postgres and Redis from docker compose up, the agent uses that compose file and records the containers it started. It doesn't write a new one.

What I really don't want is the agent changing the app to make it easier to test. No temporary auth bypass, no fake server, no edits to .env, and no throwaway route that exists only because it couldn't work out the real setup. The point is to exercise the software I'm actually shipping.

This is the kind of change I mean, and agents really do reach for it when a login page is in the way:

- if (!session) redirect("/login");
+ if (!session && process.env.NODE_ENV !== "development") redirect("/login");

If the agent can't get past authentication with the project's documented test account or seed data, the right move is to stop and report that browser review is blocked and why. A blocked review is honest. A review of an app with its auth switched off isn't a review of my app.

Where the Instructions Live

My first instinct was to keep adding to AGENTS.md. It already held the rules every agent in the repo should know: structure, conventions, testing philosophy, keep changes surgical, and no pointless comments.

I was about to add another hundred lines about starting the app, browser setup, what to click, screenshots, console errors and teardown...but at some point that file stops being instructions and turns into a small religious text.

It helps to know how each of these files is actually used. AGENTS.md is a plain Markdown file that coding agents such as Codex read automatically at the start of every session in that repository, and Claude Code does the same with CLAUDE.md. Everything in it lands in the agent's context for every task, whether the task is a CSS fix or a database migration. So it costs context on every run, and it applies everywhere.

A skill works differently. It's a folder with a SKILL.md file that starts with a short name and description. At the start of a session the agent only sees that name and description, a line or two per skill. When a task matches the description, or another instruction points at the skill, the agent reads the rest of the file and follows it. So you can have a long, detailed procedure that costs almost nothing until it's needed.

What I landed on is treating AGENTS.md as the constitution and skills as the playbooks. A constitution is short, applies to everything, and says what must be true without explaining how to do it. A playbook is a step-by-step procedure for one kind of situation, and you only pull it out when you're in that situation.

In this setup, AGENTS.md says that user-visible work isn't done until it's been checked in a browser, and the browser-review skill says how to do the checking:

/
├── AGENTS.md
└── .agents/
    └── skills/
        ├── browser-review/
        │   └── SKILL.md
        ├── pr-review/
        │   └── SKILL.md
        └── grill-me/
            └── SKILL.md

The rule in AGENTS.md stays short and always visible:

## Browser Verification

User-visible work is not complete until the affected behavior has been
verified in the running application.

For user-visible changes, follow `.agents/skills/browser-review/SKILL.md`.

A successful build, type check, unit test suite, or E2E test suite does
not replace browser verification.

Do not commit browser-verification artifacts. Stop anything you started
for verification and clean up before hand-off.

The skill holds the procedure and only gets loaded when it's needed. I use Codex and Claude Code, so there's one global AGENTS.md that Claude's CLAUDE.md imports, and one shared skills folder both of them read. Whichever agent I'm in that day, it follows the same playbook.

The import is a single line, because Claude Code lets CLAUDE.md pull in another file with @:

@~/.codex/AGENTS.md

Here's a shortened version of the one I first wrote:

---
name: browser-review
description: Verify user-visible changes in the running application with Playwright MCP.
---

# Browser Review

## Before verification

Run `git status --short` and remember what was already there. Don't touch
pre-existing work.

Read the task and the diff. Work out the affected routes, the changed flow,
the loading, empty, error, selected and disabled states that matter,
whether anything needs to survive a refresh, and what nearby behavior
could regress.

## Start the application

Use the repository's dev script, then its documented local setup, then its
existing Docker setup. Don't invent a new startup config and don't change
app behavior to make QA easier. Record every process and container you start.

## Exercise the change

Don't stop once the page loads. Go through the whole changed flow and check
the final result. Use browser or DOM state for functional claims and
screenshots for visual ones. Report new relevant console errors and failed
requests, not old warnings.

If something is broken, fix the smallest cause, rerun the affected tests
and go through the flow again. Don't assume the fix works.

## Cleanup

Teardown is required even when verification fails. Close browsers, stop
servers and containers, and delete screenshots, traces and other artifacts,
but only the ones you created. Run `git status --short` again before
hand-off. Never run `git add`, `git commit` or `git push`.

## Report

Say which routes you tested, what you did, which states you checked, what
tests you ran and what you found and fixed. If you couldn't finish, say why.

None of that is clever. The value is that it's the default expectation, so I'm not relying on the agent to decide by itself that it should open a browser.

Why the Reviewer Should Work Independently

The clear weakness is that the agent deciding whether the work is done is the same one that wrote it. That's still worth something, since I test my own code too, but it starts with a theory of how its implementation works.

By theory I mean the author's mental model of its own change: which code it touched, what it believes that code affects, and, just as important, what it believes it didn't affect. Its test plan comes straight from that model. So it tests the paths it meant to change, they work, and it never looks at the path it didn't realize was involved. That's the same blind spot people have when they test their own code, and it's exactly where the bugs that survive review tend to live.

So when a second agent reviews a branch, I tell it to work out the test scope for itself. My global rules now require a fresh reviewer with no conversation history: it gets the original request, the diff, and the review skill, and nothing about why the author thinks it works. It decides what the code could affect and tests that, without leaning on the author's screenshots, QA notes, or green test run.

The prompt for that reviewer is short on purpose:

You are reviewing a branch you did not write.

Original request:
  Make the E2E app URL configurable through E2E_BASE_URL so the
  tests can run against any port.

Run `git diff main...HEAD` to see the change. Follow the browser-review
skill. Work out for yourself what this change could affect, test that,
and report what you checked with evidence.

The best catch so far came from a PR that made an end-to-end test setup's app URL configurable. The reviewer noticed the seeded test data still hardcoded image URLs to the old port, and running the app on a different port confirmed it. Three image requests went to the wrong port and failed, and the page quietly rendered fallback cards where the images should have been. Nothing threw.

Simplified, the global setup looked like this after the change:

// e2e/global-setup.ts
const baseURL = process.env.E2E_BASE_URL ?? "http://localhost:8080";

await seedDatabase({
  media: [
    { id: "m1", url: "http://localhost:8080/test-media/cover-1.jpg" },
    { id: "m2", url: "http://localhost:8080/test-media/cover-2.jpg" },
    { id: "m3", url: "http://localhost:8080/test-media/cover-3.jpg" },
  ],
});

The author's theory was "the app URL now comes from E2E_BASE_URL", and every test it ran used the default port, where the hardcoded URLs happened to be right. The reviewer had no such theory. It read the whole setup file the diff touched, ran the app on port 8081, and came back with this:

Found: seeded media URLs in e2e/global-setup.ts still point at :8080.
Ran the app with E2E_BASE_URL=http://localhost:8081.
Network: 3 requests to http://localhost:8080/test-media/... failed
  (net::ERR_CONNECTION_REFUSED).
Screen: the gallery rendered 3 fallback cards instead of images
  (gallery-8081.png).
Suggested fix: build the seeded URLs from E2E_BASE_URL, or make them
  relative.

The fix was one line per URL:

{ id: "m1", url: new URL("/test-media/cover-1.jpg", baseURL).href },

A test that checks the cards exist passes either way, because a fallback card is still a card. You only see it by looking at the page and the network tab, which is the whole argument of this article in one bug.

Clean Up After Yourself and Only Yourself

Once agents can start servers and browsers, cleanup is part of the design. Otherwise every session leaves a layer behind: a stray node process, a Chromium window, screenshots, a Playwright trace, a temporary auth file, or a Docker container.

"Clean everything" is the wrong fix, though. pkill node isn't cleanup, it's an agent going on a small rampage, and it'll happily kill the dev server you started in another terminal. git clean -fd will delete an untracked file that has nothing to do with the agent.

The rule is to clean up what you created and leave everything else alone, and the git status before and after is there so browser QA doesn't quietly end up in my next commit.

This is why the startup step records a PID in a temp folder. Cleanup can then be precise:

# Not cleanup
pkill node
git clean -fd

# Cleanup
kill "$(cat "$QA_DIR/dev.pid")"
rm -rf "$QA_DIR"

And this is roughly what I expect to see at the end of a review:

Cleanup
- Stopped the dev server I started (pid 48213, pnpm dev --port 5173).
- Closed the Playwright MCP browser.
- Deleted export-dialog-375.png and export-dialog-1440.png.
- Left running: pid 39102 (pnpm dev on :3000). It was already running
  before I started, so it isn't mine.

git status --short before review:
 M src/features/export/ExportDialog.tsx
?? notes/todo.md

git status --short after cleanup:
 M src/features/export/ExportDialog.tsx
?? notes/todo.md

The two git status blocks match, so nothing from the review leaked into the working tree, and the untracked notes file that was already there is still there.

I didn't make this rule up in the abstract, either. While building the tool I'm about to describe, the agent testing it ran a cleanup command that closed every Playwright browser on my machine, not just its own. To be fair, it owned up to it in its summary.

When a Skill Stopped Being Enough

The skill worked, in the sense that agents started actually opening the app. But what I got back was still prose. The agent would tell me it opened the page, clicked through the flow and everything looked right, and I had to take its word for it.

It's the same problem I started with, just one level up. I didn't want a nicer sentence about the browser. I wanted the evidence: what was checked, what passed, what failed, and the screenshots and traces to back it up, in a form I could drop into a PR for whoever reviews it.

So I wrote a build plan and spent a Saturday building it, pairing with Claude Code through milestones and independent review rounds. It's called katalepsis, the Stoic word for grasping something so clearly you can't be wrong about it, which felt like a fair bar for a pull request.

You point it at a preview URL and it writes a report: HTML, Markdown you can paste into the PR, and a JSON manifest.

It does two things. katalepsis run runs your existing Playwright tests against the preview, and Playwright's result is final. katalepsis sorts, redacts and bundles it, and never reinterprets an assertion.

katalepsis verify takes plain-English checks for behavior nobody has written a test for, and a model drives a real browser with your own Anthropic, OpenAI, or OpenRouter key. There's also an MCP server, so the agent that just made a change can run either one itself and read the report back.

How to Try katalepsis

katalepsis isn't on npm yet, so the installer clones the repository and builds it. It needs Node 22.12 or newer, Git, and pnpm 10 (or corepack, which ships with Node):

curl -fsSL https://www.katalepsis.glamboyosa.xyz/install.sh | sh

That puts two launchers, katalepsis and katalepsis-mcp, in ~/.local/bin.

To run your existing tests against a preview, your Playwright config has to use the URL katalepsis passes in. It's also worth turning on failure evidence so the report has something to show:

// playwright.config.ts
use: {
  baseURL: process.env.KATALEPSIS_BASE_URL ?? "http://localhost:3000",
  screenshot: "only-on-failure",
  video: "retain-on-failure",
  trace: "retain-on-failure",
},

The repository includes a small demo app, a signup form with a deliberate bug: submitting the empty form does nothing instead of showing an error. It has three Playwright tests. Here's a real run against it:

$ katalepsis run --cwd apps/demo-form --url http://127.0.0.1:4173
katalepsis: FAILED
  2 passed, 1 failed, 0 blocked, 0 not tested
  Preview commit: not reported, so unconfirmed
  Report: artifacts/katalepsis/2026-10-19T08-21-25-288Z-3dba5a/report.html
  Markdown: artifacts/katalepsis/2026-10-19T08-21-25-288Z-3dba5a/report.md

The Markdown report is meant to be pasted into a PR. The top of it looks like this:

# katalepsis report: Failed

**2 passed, 1 failed, 0 blocked** out of 3 checks run.

- Preview: http://127.0.0.1:4173/
- Preview commit: not reported, so unconfirmed
- Runner: katalepsis 0.1.0, Playwright 1.63.0, Node 22.22.0

## Checks

| Status | Check | Project | Location | Duration |
| --- | --- | --- | --- | --- |
| Failed | signup form › empty submission shows a required-field error | chromium | signup.spec.ts:8 | 3.2 s |
| Passed | signup form › valid submission shows a confirmation | chromium | signup.spec.ts:13 | 418 ms |
| Passed | signup form › malformed email shows an email error and does not submit | chromium | signup.spec.ts:20 | 449 ms |

### Failed: signup form › empty submission shows a required-field error

- Failure type: assertion
- Evidence: screenshot, video, log, trace

Below that, it includes Playwright's own failure message (getByRole('alert') never appeared) and a list of limitations, such as the preview not reporting which commit it was built from.

For behavior without a test, you write checks in plain English. Each one has an intent, which is what to do, and a pass condition, which is what must be true at the end:

{
  "checks": [
    {
      "id": "empty-form",
      "name": "Empty form validation",
      "intent": "Submit the signup form without filling it",
      "passCondition": "A required-field error is visible"
    },
    {
      "id": "invalid-email",
      "name": "Invalid email",
      "intent": "Fill the name, enter an invalid email address and submit",
      "passCondition": "An email validation error is visible and the success confirmation is not shown"
    }
  ]
}

Then you give katalepsis a key and run them. The key is stored in your OS keychain or read from an environment variable, and it's never passed on the command line:

$ katalepsis auth set openrouter
$ katalepsis verify --cwd apps/demo-form --url http://127.0.0.1:4173 --checks checks.json \
    --provider openrouter --model anthropic/claude-haiku-5.5
katalepsis: FAILED (openrouter/anthropic/claude-haiku-5.5)
  2 passed, 1 failed, 0 blocked
  Preview commit: not reported, so unconfirmed
  Report: artifacts/katalepsis/2026-10-10T12-45-05-343Z-b51a0a/report.html

The demo's full checks.json has three checks, and the agent checks find the same empty-form bug the Playwright test did, without anyone having written that test.

Finally, so the coding agent can do all of this itself, you register the MCP server. With Codex, that's:

codex mcp add katalepsis -- katalepsis-mcp --root /path/to/your-app

The server exposes three tools, verification_run_tests, verification_check_browser, and verification_get_report, and only works inside the folder you give it. In practice the agent's instruction becomes something like "after changing the signup form, run verification_check_browser with a check for the change and paste the Markdown report into your summary."

How katalepsis Works Under the Hood

A few of the decisions came straight out of the problems in this article. Here's how they work in the code.

katalepsis is a TypeScript monorepo with five packages:

• core (the result schema, the Playwright runner, and the report renderers)

• agent (the browser tools and evidence rules for verify)

• credentials (keys and preferences)

• mcp (the MCP server)

• cli

It uses Effect for the parts where errors, cancellation, and dependencies matter, such as running Playwright and probing the preview, and Effect Schema for the report format. The model loop in verify uses the Vercel AI SDK, so the same code works with Anthropic, OpenAI, and OpenRouter.

The Report is a Schema, Not a Log

Every run, whether it came from Playwright or from a model, decodes into the same VerificationRun structure before anything is written. A trimmed version of a single check looks like this:

export const CheckStatus = Schema.Literals(["passed", "failed", "blocked"]);

export const VerificationCheck = Schema.Struct({
  id: Schema.String,
  source: Schema.Literals(["playwright-test", "agent"]),
  title: Schema.String,
  status: CheckStatus,
  flaky: Schema.Boolean,
  failure: Schema.NullOr(Schema.Struct({ code: FailureCode, message: Schema.String })),
  attempts: Schema.Array(Attempt),
  evidence: Schema.Array(BundlePath),
});

Tests that never ran go into a separate notTested list with a reason, which is how you end up with four outcomes: passed, failed, blocked, or not tested. Every evidence file is stored with its SHA-256 hash, and BundlePath rejects absolute paths and .., so a report can't point outside its own folder.

Blocked isn't Failed

If the preview is down, you get one blocked run, not three failed tests that send you hunting for bugs that don't exist. Before starting Playwright, katalepsis requests the preview URL once. This is the core of that probe:

const UNAVAILABLE_STATUSES = new Set([502, 503, 504]);

const response = await fetch(url, {
  redirect: "manual",
  signal: AbortSignal.any([signal, AbortSignal.timeout(30_000)]),
});
if (UNAVAILABLE_STATUSES.has(response.status)) {
  return { reachable: false, reason: `the preview answered with HTTP ${response.status}` };
}

A network error or a gateway status blocks every selected test, and Playwright never starts. Pointing the demo at a port with nothing on it gives you this:

$ katalepsis run --cwd apps/demo-form --url http://127.0.0.1:4999
katalepsis: BLOCKED
  0 passed, 0 failed, 3 blocked, 0 not tested
  preview-unavailable: http://127.0.0.1:4999/ did not respond (connect ECONNREFUSED 127.0.0.1:4999). Playwright was not run.

Playwright's Verdict is Final

run starts the project's own Playwright with --reporter=json and reads the result file, rather than reimplementing anything. Playwright already marks a test that passed on retry as flaky, so katalepsis keeps that flag and lists every attempt.

What it does add is classification. A failure whose message names the preview's own origin as unreachable becomes blocked, but a dead third-party API stays failed, because that's a real problem with your app. A browser that couldn't launch is blocked too, which is exactly what I got the first time I ran the demo for this article on a machine with the wrong browser build installed.

The Model Doesn't Get to Call Something a Pass

The model in verify can click and type and read the page, but it doesn't get to call something a pass. A check only passes if the model points to a browser assertion that katalepsis ran, that passed, and that shows something that wasn't on the page before the model acted. Otherwise it comes back blocked.

Here's how that works. The model only gets a small set of tools: navigate, snapshot, click, fill, press, assert, and finish. assert doesn't return the model's opinion. katalepsis runs the check in the browser itself, takes a screenshot, and records the result with an ID like a3. When the model calls finish, it has to cite those IDs:

finish: tool({
  description: "Report the verdict once, citing assertion IDs such as a1.",
  inputSchema: schema(
    Schema.Struct({
      verdict: Schema.Literals(["passed", "failed", "blocked"]),
      summary: Schema.String,
      assertionIds: Schema.Array(Schema.String),
    }),
  ),
  execute: (verdict) => {
    onFinish(verdict);
    return "Recorded.";
  },
}),

Then a plain function, decideOutcome, compares the claim with the evidence. A trimmed version of the pass rule:

if (!cited.every((assertion) => assertion.passed)) {
  return "The agent reported a pass, but a cited assertion failed.";
}
const shown = cited.filter((assertion) => assertion.expectation === "visible");
if (shown.length === 0) {
  return "The agent reported a pass citing only hidden or URL assertions.";
}
if (!observeOnly && shown.every((assertion) => assertion.trueAtStart === true)) {
  return "The agent reported a pass, but everything it cited was already on the page before it acted.";
}

Any of those messages turns the check into blocked with the code no-evidence. Citing an assertion ID that never ran is blocked too. The function also blocks a pass if an uncited assertion failed after the last cited one, because the latest evidence disagrees with the verdict.

That trueAtStart condition exists because one of the models I tested tried to prove a form worked by citing the label of the email field, which had been there all along. T

o catch it, each check opens two copies of the start page in separate browser contexts. The model works in one, and the other stays untouched. When the model asserts that something is visible, katalepsis looks for the same element on the untouched copy, and if it's there too, the assertion gets trueAtStart: true and can't carry a pass on its own.

One Action at a Time

The first live runs also caught parallel tool calls stepping on each other, and a name ending up typed into the email field. Models like to send several tool calls at once, and two fill calls racing each other type into whichever field has focus. The fix is a promise queue that every browser action goes through:

private exclusive<A>(action: () => Promise<A>): Promise<A> {
  const next = this.queue.then(action, action);
  this.queue = next.catch(() => undefined);
  return next;
}

Each action waits for the previous one to settle, whether it succeeded or failed, and a failure doesn't poison the queue for the next action.

Budgets and Boundaries

Each agent check runs in its own browser context with tracing on, so the report always has a trace to replay. Navigation is limited to the preview's origin plus anything you allow with --allow-origin. The model has a step limit (--max-steps, 15 by default), a token limit (--max-tokens, 200,000), and a time limit (--check-timeout, 120 seconds), and running out of any of them is reported as blocked with the reason, not as a failure. Query strings are redacted from URLs in the report.

How it Was Built

Before writing code, I wrote a build plan split into milestones. M0 was a review of how two of my earlier projects handled credentials and providers, plus the first architecture decision record and the monorepo tooling. M1 was the Playwright runner and the report, M2 was agent checks with your own key, and M3 was the MCP server. Each milestone ended with a fresh agent with no history reviewing the work against the plan, the same independent-reviewer rule from earlier in this article.

Those reviews shaped the tool more than the plan did. The first one came back with 15 findings, including the rule that only an unreachable preview counts as blocked while other hosts stay failed. The M2 review found that a model could get a pass by citing an assertion that proved nothing, which is where the stricter pass rule and the untouched copy of the page came from. The M3 review found that a client quitting mid-run left Playwright and its browsers running, and that a crafted symlink could let the report tool read files outside the project. All of those are fixed and covered by tests now.

What Happened When I Used It

Before telling anyone about it, I ran it against two of my own projects. Conclave's suite came back with 95 passed. A larger app came back with 137 passed and one failure, an assertion on a zoom level that was slightly off.

That was a test I already had and hadn't noticed was failing, so katalepsis didn't find the bug so much as make it impossible to miss. Both projects also hardcoded their baseURL, which meant their tests never touched the URL I passed in. katalepsis now warns about that, because a green run against the wrong server is worse than no run.

After I posted it on LinkedIn, someone in the comments pointed out that the commit you have checked out isn't necessarily the commit the preview was built from. They were right, so the report now records both and marks them confirmed, mismatched, or unknown, and a mismatch blocks a run that would otherwise pass, since a green run against a stale preview tells you nothing about your diff.

The preview reports its commit with an x-commit-sha response header or a <meta name="commit-sha"> tag, which the same probe that checks availability reads. If your host can't do either, you can pass --preview-commit yourself.

I'm dogfooding it in the same instructions this article describes. The browser-review skill now tells my agents to run katalepsis first, and to fall back to plain browser automation for what it can't check yet: field values, persistence, console and network, and layout across viewports.

The first Codex session to pick that up went looking for a "katalepsis skill" because of how I'd worded the line in AGENTS.md, didn't find one, and fell back to its old browser review. Wrong for a silly reason, but the fallback did exactly what it was supposed to, and the fix was saying plainly that katalepsis is a CLI and browser-review is the skill.

A few days later I used it on a real work branch, a change that made GeoJSON the main download button and moved CSV and KML into a dropdown. The agent stopped before running anything, because verify sends page content to the model provider and my rules say it needs my OK before doing that for an app. That's the behavior I want

With seeded synthetic data and an explicit OK, the check passed: one visible primary button, and the other formats showing up once the dropdown opened, with the screenshots and trace in the report. The skill still keeps pages with real data on the fallback path.

Where I Landed

Not every task needs any of this. I don't need Playwright to confirm a Markdown typo got fixed, and a backend refactor that can't change what renders doesn't need Chromium. I do want it for components, forms, navigation, dialogs, client state, maps, filtering, responsive layout, persistence, and any user-visible bug fix.

My rule of thumb is that if you're making a claim about how the UI behaves at runtime, the runtime UI should be part of the evidence.

None of this replaces good tests, code review, or me looking at changes that matter. It just adds the feedback loop that was missing. The agent already has the repository and the shell, and it knows what it changed. With a browser it can start answering whether the thing it built actually works, and with a report it can show me instead of telling me. If it can write the button, it can click it and show me what happened before it says it's done.

katalepsis is MIT licensed and on GitHub. If an agent check ever gives you a result you don't believe, I'd like to hear about it.

Every small change ("move this bullet up", "delete that line", "this link is dead") goes through you, the person with the code editor, even though the person requesting the change knows exactly what they want.

I ran into this maintaining a family member's résumé as a single static HTML file. The design was done. The content was theirs. But every revision, whether it was reordering a role, adding a certification, fixing a link, or nudging a print page break, meant another round of "send me the change, I'll edit the file." After the tenth round, the fix became obvious: make the page edit itself.

In this article, you'll build an in-browser editing layer for a static HTML page using contenteditable, about a hundred lines of vanilla JavaScript, and no build step. The person editing can change any text, reorder or delete any block, add new content, edit links, control print pagination, and print to PDF. A refresh restores the original file, untouched.

Table of Contents

• Prerequisites

• What You Will Learn

• What Iscontenteditable?

• Why Not a React App?

• How to Prepare the Markup for Reordering

• How to Attach Controls to Every Block

• How to Show Controls Only on the Innermost Block

• How to Move and Delete Blocks

• How to Edit Links Insidecontenteditable

• How to Let Users Control Print Pagination

• How to Add New Content from Templates

• Why Nothing Persists

• Conclusion

Prerequisites

To follow along, you should have:

• Working knowledge of HTML and CSS, including CSS Grid and @media print

• Basic understanding of JavaScript DOM APIs (querySelector, event listeners, creating elements)

• No frameworks, libraries, or build tools. That's the point.

What You Will Learn

• What contenteditable gives you for free, and where it stops

• How to attach move/delete controls to repeatable blocks with one reusable function

• How to show controls only on the innermost hovered block using :has()

• How to reorder DOM nodes without a framework, and the markup prep that makes it safe

• How to edit link URLs inside an editable region

• How to let users place print page breaks themselves

• How to add new content from templates, with placeholder text pre-selected

• Why "nothing persists" can be a feature, not a limitation

What Is contenteditable?

contenteditable is an HTML attribute that turns any element into an editable region. The browser handles the hard parts: caret placement, text selection, typing, deletion, clipboard, and undo history.

<div class="page" contenteditable="true" spellcheck="false">
  <!-- the entire document -->
</div>

That one attribute gets you further than you might expect. Clicking any paragraph places a caret. Cmd+Z undoes typing. Pressing Enter inside a <ul> creates a new <li>. The browser understands list semantics natively, so "add a bullet by pressing Enter" works with zero code.

But contenteditable alone isn't an editor. It has no concept of blocks. It won't move a job entry above another one, delete a card cleanly, or change an href. Clicking a link inside an editable region just places the caret in its text. Everything structural is on you. The rest of this article is about filling that gap.

Why Not a React App?

The obvious alternative is to rebuild the page as a "real" app: components, state, a form per section, and an export button. I decided against it, and the tradeoff is important.

The file lives in a public/ folder and is served as a static asset. It works from a URL, from disk, or from an email attachment. It has no dependencies to install, no build to run, and no way to rot when a toolchain updates.

The editing needs are small and bounded: change text, move blocks, delete blocks, add blocks, and print. That's DOM manipulation, the thing the DOM API is already good at.

A framework earns its complexity when state outlives the DOM: persistence, collaboration, validation, and syncing. This page has none of those requirements. When your state is the DOM and the lifetime is one session, a framework is an extra layer that buys you nothing.

How to Prepare the Markup for Reordering

Before writing any JavaScript, look at your markup for anything positional, meaning elements that only make sense between other elements. In my case, jobs were separated by <hr> dividers:

<div class="job">...</div>
<hr class="divider">
<div class="job">...</div>

The moment blocks can move or be deleted, separators like this become landmines. Delete a job and its divider survives as an orphaned line. Move a job and the divider stays behind.

The fix is to delete the <hr> elements entirely and derive the separator from adjacency:

.section .job + .job {
  border-top: 0.5px solid var(--rule);
  padding-top: 18px;
}

The sibling combinator draws a rule above every job that follows another job. Reorder them, delete them, add new ones, and the separators are always exactly where they should be, because they're computed from structure rather than stored in it. This is the same principle as deriving state instead of duplicating it, applied to CSS.

How to Attach Controls to Every Block

Each movable block gets a small control cluster with move up, move down, and delete actions, injected by one reusable function:

const SELECTORS = ['.section', '.job', '.bullets li', '.cert-card', '.skills-row', '.edu-row'];
const BREAKABLE = new Set(['.section', '.job']);

function makeBlock(el, sel) {
  el.classList.add('blk');
  el.dataset.sel = sel;
  const ctl = document.createElement('span');
  ctl.className = 'ctl';
  ctl.setAttribute('contenteditable', 'false');
  ctl.innerHTML =
    '<button data-act="up" data-tip="Move this up">↑</button>' +
    '<button data-act="down" data-tip="Move this down">↓</button>' +
    (BREAKABLE.has(sel) ? '<button data-act="brk" data-tip="Page break: start a new printed page here">⇟</button>' : '') +
    '<button data-act="del" data-tip="Remove this. Refresh to bring it back">×</button>';
  el.appendChild(ctl);
}

SELECTORS.forEach(sel => {
  page.querySelectorAll(sel).forEach(el => makeBlock(el, sel));
});

A few design decisions are worth calling out.

First, contenteditable="false" on the control cluster. Editable regions inherit. Everything inside the page is editable unless you opt out. Without this, the user could place a caret inside your buttons and delete them like text.

Second, el.dataset.sel records which selector matched. This matters later: when a block moves, it should only swap with siblings of its own kind. A bullet moves among bullets, a job among jobs. Storing the selector on the element makes that check trivial.

Third, the controls live inside the block they control. That gives you positioning for free, with position: absolute against the block's own position: relative, and means a block carries its controls with it wherever it moves.

How to Show Controls Only on the Innermost Block

Blocks nest: a bullet sits inside a job, which sits inside a section. Hovering a bullet technically hovers all three, and naïve CSS shows three control clusters at once. The result is visual noise exactly where the user is trying to focus.

Modern CSS solves this in one line:

.blk:hover:not(:has(.blk:hover)) > .ctl { display: inline-flex; }

Read it inside out: show a block's controls when it's hovered, unless some descendant block is also hovered, in which case that deeper block wins. Hover a bullet, you get bullet controls. Hover the job's title (outside any bullet), you get job controls. One rule, no JavaScript.

:has() is supported in every current browser, but a fallback costs one more rule:

@supports not selector(:has(*)) {
  .blk:hover > .ctl { display: inline-flex; }
}

Older browsers get the noisier all-ancestors behavior instead of no controls at all. Degrade loudly, not silently.

How to Move and Delete Blocks

With controls attached, the actual reordering is short. One delegated listener handles every button on the page:

function siblings(el) {
  return [...el.parentElement.children].filter(c =>
    c.classList.contains('blk') && c.dataset.sel === el.dataset.sel);
}

page.addEventListener('click', e => {
  const btn = e.target.closest('.ctl button');
  if (!btn) return;
  e.preventDefault();
  const el = btn.closest('.blk');
  const sibs = siblings(el);
  const i = sibs.indexOf(el);
  const act = btn.dataset.act;
  if (act === 'up' && i > 0) sibs[i - 1].before(el);
  else if (act === 'down' && i < sibs.length - 1) sibs[i + 1].after(el);
  else if (act === 'del') el.remove();
  else if (act === 'brk') el.classList.toggle('page-break');
});

siblings() is where dataset.sel pays off: it filters the parent's children down to blocks of the same kind, so a job can never swap into the middle of a bullet list. before() and after() move the live node with no cloning or re-rendering, and the block's own controls travel with it.

There's one subtle bug to prevent. Clicking a button inside an editable region moves the text caret first, which can scroll the page or collapse a selection. Suppress it at mousedown, before the browser acts:

page.addEventListener('mousedown', e => {
  if (e.target.closest('.ctl, .add-btn')) e.preventDefault();
});

Forgetting this is the kind of thing you only notice as a vague feeling that clicking buttons "jumps." It's worth ruling out before it ships.

How to Edit Links Inside contenteditable

Inside an editable region, single-clicking a link places the caret instead of navigating. That's correct for text editing but leaves no way to change the URL itself. The href isn't text, it's an attribute.

Double-click is unclaimed real estate, so hang URL editing off it:

page.addEventListener('dblclick', e => {
  const a = e.target.closest('a');
  if (!a) return;
  e.preventDefault();
  const url = prompt('Link URL (leave empty to remove the link):', a.getAttribute('href'));
  if (url === null) return;
  if (!url.trim()) a.replaceWith(document.createTextNode(a.textContent));
  else a.setAttribute('href', url.trim());
});

Yes, prompt(). It's unfashionable, but consider what a custom modal would cost: markup, styles, focus management, and an escape handler, all for a dialog that asks one question. prompt() is native, keyboard-accessible, and can't break.

The empty-string branch is a nice touch: it unwraps the link entirely, replacing it with its own text, so "remove this link" doesn't require knowing any HTML.

Since none of this is discoverable, tell the user. A title attribute on every link ("Double-click to change this link") surfaces the affordance exactly where it's needed.

How to Let Users Control Print Pagination

If the document's destination is a printed PDF, page breaks are content decisions, like "start my Skills section on page three," and the user should own them. CSS makes the break itself easy:

@media print {
  .page-break { break-before: page; page-break-before: always; }
  .job { break-inside: avoid; page-break-inside: avoid; }
}

The interesting part is the interface. The ⇟ button you saw in makeBlock just toggles the page-break class on a job or section. On screen, the class renders as a dashed accent line above the block, a visible seam showing where the printed page will end:

.page .page-break {
  border-top: 1.5px dashed var(--accent) !important;
  padding-top: 14px !important;
}

@media print {
  .page .page-break { border-top: none !important; padding-top: 0 !important; }
}

The dashed line exists only on screen. In print it vanishes and the actual break takes its place. The user toggles, glances at the seam, and prints. Nobody edits CSS to re-paginate a document, and just as importantly, nobody asks me to.

The same @media print block hides every piece of editing chrome (.toolbar, .ctl, .add-btn { display: none !important; }), so the printed output is indistinguishable from the original static page.

How to Add New Content from Templates

Editing and deleting only go so far. Eventually someone needs a new bullet, a new role, or a new certification. Each repeatable container gets a dashed "+ Add" button that builds a blank block from a template:

skillsSection.appendChild(newAddBtn('+ Add skill row', 'Adds a blank row. Type over the placeholder.', btn => {
  const row = document.createElement('div');
  row.className = 'skills-row';
  row.innerHTML =
    '<span class="skill-label">Label</span>' +
    '<span class="skill-items">Skill one, skill two, skill three</span>';
  skillsSection.insertBefore(row, btn);
  makeBlock(row, '.skills-row');
  selectText(row.querySelector('.skill-label'));
}));

Two details here do most of the work.

New blocks go through the same makeBlock as everything parsed at load. There is exactly one code path for "this is a block now", so added content is immediately movable and deletable. For roles it gets its own nested "+ Add bullet" button.

If you find yourself writing a second registration path for dynamic content, stop. You're about to fork behavior that must stay identical.

And selectText pre-selects the placeholder:

function selectText(node) {
  const range = document.createRange();
  range.selectNodeContents(node);
  const sel = getSelection();
  sel.removeAllRanges();
  sel.addRange(range);
}

Click "+ Add skill row" and the word Label is already highlighted, so typing replaces it. No clicking into the field, no manually deleting placeholder text, and no placeholders accidentally left in the printed document.

One caveat: select the text node, not the block. The block contains your contenteditable="false" control cluster, and a selection spanning it will delete your buttons along with the placeholder on the first keystroke.

Why Nothing Persists

Every edit lives in the DOM and dies on refresh. That sounds like the missing feature, but it's the design.

The workflow this page serves is: open, adjust, print to PDF, close. The PDF is the artifact. The page is a template you stamp from. Ephemerality gives you a free, bulletproof undo-everything (refresh), zero risk of a half-finished edit becoming the new baseline, and a canonical version that always matches source control.

The toolbar says it plainly: "Nothing is saved. Refresh resets everything." Stated upfront, it reads as a guarantee rather than a gotcha.

Persistence would also be the complexity cliff. The moment edits survive refresh you inherit serialization, versioning, merge conflicts with the source file, and "which copy is real?" Those are the exact problems this design exists to avoid.

Conclusion

You now have a static HTML page that edits itself: contenteditable for text, one makeBlock function for structure, :has() for focused hover controls, a class toggle for print pagination, and templates with pre-selected placeholders for new content. Around a hundred lines of JavaScript, with no dependencies and no build.

Just as important is knowing when this approach stops being right. If edits must persist, if multiple people edit concurrently, or if the content needs validation and workflow, you've outgrown the DOM-as-state model. In those cases, reach for a real application and a database.

But for the wide middle ground of documents that one person adjusts and prints, such as résumés, invoices, certificates, and programmes, the browser already ships the editor. You just have to turn it on.

Connections drop, proxies buffer responses, and mobile networks switch from WiFi to cellular mid-stream. If your streaming code doesn't plan for this, the user sees a response that just stops, with no error and no recovery.

In this article, you'll use an open source TypeScript library called Ore as a practical example of how to build a streaming client that handles real-world network conditions: automatic retries, the official Server-Sent Events (SSE) parsing spec, and clean integration with React and React Server Components.

By the end, you'll understand how async generators, the Fetch API, and the SSE spec fit together to build something far more reliable than a basic fetch and response.body.getReader() loop.

Table of Contents

1. Prerequisites

2. What You Will Learn

3. What Is Server-Sent Events?

4. Why Build a Custom Streaming Client?

5. How to Stream Raw Chunks with an Async Generator

6. How to Parse Server-Sent Events by Hand

7. How to Implement Reconnection with Last-Event-ID

8. How to Handle Retries with Backoff

9. How to Use This with React

10. How to Use This with React Server Components

11. Conclusion

Prerequisites

To follow along, you should have:

• A working understanding of TypeScript

• Familiarity with fetch, ReadableStream, and async/await

• Basic knowledge of React (for the React-specific sections)

What You Will Learn

• How to stream raw text or bytes from a fetch response using async generators

• How to parse the Server-Sent Events spec by hand, field by field

• How to implement automatic reconnection with Last-Event-ID so you don't lose events

• How to handle retries with exponential backoff

• How to integrate a streaming client with React state and React Server Components

What Is Server-Sent Events?

Server-Sent Events (SSE) is a web standard for one-way streaming from server to client over a single HTTP connection. Unlike WebSockets, it's plain HTTP, which means it works through existing infrastructure like load balancers and proxies without special configuration.

An SSE response looks like this on the wire:

event: update
id: 42
data: {"status": "processing"}

event: update
id: 43
data: {"status": "complete"}

Each event is separated by a blank line. The data field carries the payload, event names the event type, and id lets the client track its position in the stream for reconnection.

The browser has a built-in EventSource API for this, but it has real limitations: no custom headers, no POST requests, and inconsistent reconnection behavior across browsers. For anything beyond the simplest case, you often need to parse the stream yourself.

Why Build a Custom Streaming Client?

Many streaming use cases, like AI chat responses, don't use the SSE spec at all. They're just raw chunks of text arriving over time. Other cases, like live notifications, genuinely benefit from the structure SSE provides: named events, IDs for resumption, and a server-controlled retry interval.

Ore handles both with two separate functions:

• stream() for raw text or byte streaming, with no assumptions about format

• streamSSE() for spec-compliant SSE parsing

Both are async generators, so consuming either looks the same from the call site:

for await (const chunk of stream("https://api.example.com/chat")) {
  console.log(chunk);
}

How to Stream Raw Chunks with an Async Generator

The simplest case is streaming raw text. This is useful for AI responses or log tails where there's no event structure, just a sequence of bytes arriving over time.

Here's the core of stream():

export async function* stream(
  url: string,
  options?: StreamOptions
): AsyncGenerator<string | Uint8Array, void, unknown> {
  const { headers, retries = 3, signal, decode = true } = options || {};

  let retryCount = 0;

  while (retryCount <= retries) {
    try {
      const response = await fetch(url, { method: "GET", headers, signal });

      if (!response.body) {
        throw new Error("Response body is null");
      }

      const reader = response.body.getReader();
      const decoder = new TextDecoder();

      try {
        while (true) {
          const { done, value } = await reader.read();
          if (done) break;
          yield decode ? decoder.decode(value, { stream: true }) : value;
        }
      } finally {
        reader.releaseLock();
      }

      return;
    } catch (error: any) {
      if (signal?.aborted) throw error;
      retryCount++;
      if (retryCount > retries) {
        throw new Error(`Max retries exceeded. Last error: ${error.message}`);
      }
      await new Promise((r) => setTimeout(r, 1000 * retryCount));
    }
  }
}

A few design decisions are worth calling out.

The function is an async generator (async function*), so the caller can use for await...of instead of managing a reader and a loop manually. That's the difference between exposing a raw ReadableStream and exposing something pleasant to consume.

The finally block always releases the reader lock, even if the loop exits early through a break or an exception. Forgetting this is a common source of stream leaks.

The retry loop only catches errors from the fetch call and the read loop. If the AbortSignal was the cause of the failure, it rethrows immediately rather than retrying, since retrying a deliberate cancellation makes no sense.

How to Parse Server-Sent Events by Hand

The SSE spec is a simple text format, but parsing it correctly means handling several edge cases: events split across multiple data lines, comment lines starting with a colon, fields with no value, and incomplete lines at the end of a chunk.

Here's the core state machine inside streamSSE():

let buffer = "";
let currentEvent: Partial<SSEEvent> = { data: "", event: null, id: null };
let hasData = false;

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split(/\r\n|\r|\n/);
  buffer = lines.pop() || ""; // keep the last incomplete line for the next chunk

  for (const line of lines) {
    if (line === "") {
      if (hasData) {
        const event: SSEEvent = {
          id: currentEvent.id ?? lastEventId,
          event: currentEvent.event ?? null,
          data: currentEvent.data!.endsWith("\n")
            ? currentEvent.data!.slice(0, -1)
            : currentEvent.data!,
          retry: currentEvent.retry,
        };
        if (event.id) lastEventId = event.id;
        yield event;
        currentEvent = { data: "", event: null, id: null };
        hasData = false;
      }
      continue;
    }

    if (line.startsWith(":")) continue; // comment line, ignore

    const colonIndex = line.indexOf(":");
    const field = colonIndex === -1 ? line : line.slice(0, colonIndex);
    let valueStr = colonIndex === -1 ? "" : line.slice(colonIndex + 1);
    if (valueStr.startsWith(" ")) valueStr = valueStr.slice(1);

    switch (field) {
      case "data":
        currentEvent.data += valueStr + "\n";
        hasData = true;
        break;
      case "event":
        currentEvent.event = valueStr;
        break;
      case "id":
        if (valueStr.indexOf("\0") === -1) currentEvent.id = valueStr;
        break;
      case "retry":
        const retry = parseInt(valueStr, 10);
        if (!isNaN(retry)) retryInterval = retry;
        break;
    }
  }
}

A network chunk doesn't respect line boundaries. A single read() call might end mid-line, so the last, possibly incomplete line is held back in buffer and prepended to the next chunk rather than processed early. This is the part of SSE parsing that's easy to get wrong if you reach for a naïve response.text() and a string split.

The blank line is what ends an event. SSE events don't have a fixed-length header. The spec says a blank line marks the boundary, so the parser only yields an event once it has seen one.

The id field is rejected outright if it contains a null byte, per the spec. That's a small detail that almost no hand-rolled implementation gets right on the first try.

How to Implement Reconnection with Last-Event-ID

This is the part of SSE that gives it a real advantage over a plain fetch stream: built-in support for resuming after a disconnect without losing your place.

let lastEventId: string | null = null;

while (retryCount <= retries) {
  const headers = { ...customHeaders };
  if (lastEventId) {
    (headers as any)["Last-Event-ID"] = lastEventId;
  }

  const response = await fetch(url, { method: "GET", headers, signal });
  // ... read and parse events, updating lastEventId as they arrive
}

Every time an event with an id field arrives, lastEventId is updated. If the connection drops and the client reconnects, it sends Last-Event-ID in the request headers. A well-behaved server can use that header to resume the stream from the right point instead of replaying everything or skipping ahead.

This only works if the server actually honors the header, so it's a contract between client and server, not something the client can guarantee alone. But having the client track and send it correctly is the necessary half of that contract.

How to Handle Retries with Backoff

Both stream() and streamSSE() retry on failure, but they do it slightly differently based on what failed.

stream() uses a simple linear backoff tied to the retry count:

await new Promise((resolve) => setTimeout(resolve, 1000 * retryCount));

streamSSE() respects the server-specified retry field from the SSE spec when one is provided, falling back to a default otherwise:

let retryInterval = 1000;
// ... updated from the "retry" field if the server sends one
await new Promise((r) => setTimeout(r, retryInterval));

Letting the server influence the retry interval matters in practice. A server under load can tell clients to back off longer, which is exactly the kind of cooperative behavior the SSE spec was designed to support.

In both functions, an aborted AbortSignal always short-circuits the retry loop. Treating a deliberate cancellation as a retryable failure is a common bug, and the fix is just checking signal?.aborted before deciding to retry.

How to Use This with React

Because both functions are async generators, integrating with React state is a matter of looping and calling setState per chunk:

function ChatComponent() {
  const [messages, setMessages] = useState("");

  useEffect(() => {
    const controller = new AbortController();

    (async () => {
      try {
        for await (const chunk of stream("/api/chat", { signal: controller.signal })) {
          setMessages((prev) => prev + chunk);
        }
      } catch (err: any) {
        if (err.name !== "AbortError") console.error(err);
      }
    })();

    return () => controller.abort();
  }, []);

  return <div>{messages}</div>;
}

The cleanup function calling controller.abort() is doing real work here. Without it, navigating away from the component while a stream is still active leaves the fetch running in the background, updating state on an unmounted component.

How to Use This with React Server Components

Because the generator yields values one at a time, you can also drive a recursive Suspense boundary directly from the async iterator, streaming HTML to the client as each chunk arrives:

async function StreamViewer({ iterator }: { iterator: AsyncIterator<string> }) {
  const { value, done } = await iterator.next();
  if (done) return null;

  return (
    <span>
      {value}
      <Suspense>
        <StreamViewer iterator={iterator} />
      </Suspense>
    </span>
  );
}

export default function Page() {
  const dataStream = stream("https://api.example.com/stream");
  const iterator = dataStream[Symbol.asyncIterator]();

  return (
    <Suspense fallback="Loading...">
      <StreamViewer iterator={iterator} />
    </Suspense>
  );
}

Each recursive call awaits the next chunk and renders a nested Suspense boundary for the rest. React streams each piece of HTML to the client as it resolves, rather than waiting for the entire response.

Conclusion

A reliable streaming client needs to handle more than the success path. Connections drop, chunks arrive split across line boundaries, and cancellation needs to be distinguished from failure.

Ore's approach to this is built from a small set of ideas:

• Expose streams as async generators so consumers can use for await...of

• Parse SSE by hand, field by field, respecting the spec's blank-line event boundaries and buffering incomplete lines across chunks

• Track Last-Event-ID so reconnection can resume rather than restart

• Treat retries and cancellation as separate concerns

• Stay framework-agnostic at the core, with thin integration points for React and React Server Components

That combination is what separates a streaming client that works in a demo from one that holds up against real network conditions. You can explore the full source code at github.com/glamboyosa/ore.

Some work is slow. Some work can fail. Some work should happen later. Sending emails, resizing images, processing webhooks, generating reports, and retrying third-party APIs are all good examples.

These tasks are usually handled by a background job system.

In this article, you'll use an open source Go project called Swig as a practical example of how a PostgreSQL-backed job queue works in practice.

By the end, you'll understand how to build a background job queue with Go and PostgreSQL, and why PostgreSQL is more capable than most developers realize.

Table of Contents

1. Prerequisites

2. What You Will Learn

3. What Is a Job Queue?

4. Why Use PostgreSQL for a Queue?

5. Swig's Architecture

6. How to Represent Jobs in PostgreSQL

7. How to Define a Worker in Go

8. How to Register Workers Without Sharing State

9. How to Add a Job

10. How to Handle Multiple Workers Safely

11. How to Use Goroutines for Concurrent Workers

12. How to Wake Workers with LISTEN/NOTIFY

13. How to Elect a Leader with Advisory Locks

14. How to Handle Failed Jobs

15. How to Abstract the Database Driver

16. Conclusion

Prerequisites

To follow along, you should have:

• Basic familiarity with Go (structs, interfaces, goroutines)

• A working understanding of PostgreSQL and SQL

• Go installed (1.21 or later)

• A PostgreSQL instance available locally or remotely

What You Will Learn

• How to represent and store jobs in PostgreSQL

• How to claim jobs safely across concurrent workers using FOR UPDATE SKIP LOCKED

• How to wake workers efficiently using LISTEN/NOTIFY

• How to elect a leader across instances using advisory locks

• How Go interfaces, goroutines, contexts, and transactions fit together in a real system

What Is a Job Queue?

A job queue is a system that stores work to be done later.

Your application adds a job to the queue. A worker takes a job from the queue and runs it.

For example, when a user signs up, your application might create the user immediately and then add a job like this:

{
  "kind": "send_welcome_email",
  "payload": {
    "to": "user@example.com",
    "subject": "Welcome!"
  }
}

A background worker later picks up that job and sends the email. This keeps the user request fast. The signup route doesn't need to wait for the email provider before returning a response.

A job queue usually needs to answer a few important questions:

• Where are jobs stored?

• How do workers find jobs?

• How do you stop two workers from processing the same job?

• How do you retry failed jobs?

• How do you shut workers down safely?

• How do you keep job creation consistent with application data?

Swig answers those questions with Go and PostgreSQL.

Why Use PostgreSQL for a Queue?

Many job queues use Redis, RabbitMQ, SQS, or Kafka. Those are all useful tools. But many applications already depend on PostgreSQL. If your app already has Postgres, you may not want to operate another service just to run background jobs.

PostgreSQL gives you several features that are surprisingly useful for queues:

• Tables for durable job storage

• Transactions for atomic writes

• Row locks for safe concurrent processing

• SKIP LOCKED for letting workers claim different jobs

• LISTEN/NOTIFY for waking workers when new jobs arrive

• Advisory locks for leader election

• JSONB for flexible job payloads

The tradeoff is important. A PostgreSQL-backed queue isn't trying to replace Kafka for event streaming or RabbitMQ for complex routing. It makes common application background jobs simple, reliable, and easy to operate without adding infrastructure.

Swig's Architecture

At a high level, Swig has five parts:

1. A swig_jobs table in PostgreSQL

2. Go workers that process jobs

3. A worker registry that maps job names to worker types

4. A driver layer that supports both pgx and database/sql

5. A leader loop for shared maintenance work

The basic flow looks like this:

1. Your app calls AddJob

2. Swig serializes the job payload to JSON

3. Swig inserts a row into swig_jobs

4. PostgreSQL sends a notification that a job was created

5. A Go worker wakes up and tries to claim one pending job

6. PostgreSQL row locks ensure only one worker claims that row

7. The worker runs the job

8. Swig marks the job as completed or failed

The hard parts are concurrency, failure, connection lifecycle, and shutdown. That's where Go and PostgreSQL work together.

How to Represent Jobs in PostgreSQL

A simplified version of Swig's job table looks like this:

CREATE TABLE swig_jobs (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  kind TEXT NOT NULL,
  queue TEXT NOT NULL,
  payload JSONB NOT NULL,
  status TEXT NOT NULL DEFAULT 'pending',
  priority INTEGER NOT NULL DEFAULT 0,
  attempts INTEGER NOT NULL DEFAULT 0,
  max_attempts INTEGER NOT NULL DEFAULT 3,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  scheduled_for TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  instance_id UUID,
  worker_id UUID,
  locked_at TIMESTAMPTZ,
  last_error TEXT,
  last_error_at TIMESTAMPTZ
);

Each row is one job. The important columns are:

• kind: the type of job, such as send_email

• payload: the JSON data needed to run the job

• status: whether the job is pending, processing, completed, or failed

• attempts: how many times the job has been tried

• scheduled_for: when the job is allowed to run

• locked_at: when the job was claimed

The table is the source of truth. PostgreSQL notifications can wake workers, but notifications aren't the durable queue. The rows in swig_jobs are.

How to Define a Worker in Go

In Swig, a worker is a Go type that knows how to process one kind of job.

Here's a simple email worker:

type EmailWorker struct {
    To      string `json:"to"`
    Subject string `json:"subject"`
    Body    string `json:"body"`
}

func (w *EmailWorker) JobName() string {
    return "send_email"
}

func (w *EmailWorker) Process(ctx context.Context) error {
    fmt.Printf("Sending email to %s with subject %s\n", w.To, w.Subject)
    return nil
}

There are two important methods:

• JobName tells Swig what kind of job this worker handles

• Process contains the actual work

The struct fields are also the job arguments. When you enqueue an EmailWorker, Swig serializes the struct into JSON and stores it in PostgreSQL. Later, a worker claims the row, unmarshals the JSON back into a fresh EmailWorker, and calls Process.

Go Interfaces

Go interfaces describe behavior. Swig doesn't need to know the exact concrete type of every worker. It only needs to know that a worker can provide a job name and process a job:

type Worker interface {
    JobName() string
    Process(context.Context) error
}

If a type has those methods, it satisfies the interface with no explicit declaration required. This is one of the reasons interfaces are so useful in Go. They let you design around behavior instead of inheritance.

How to Register Workers Without Sharing State

Swig has a worker registry that maps a job name to a worker type:

registry := workers.NewWorkerRegistry()
registry.RegisterWorker(&EmailWorker{})

Later, when a job row says kind = 'send_email', Swig looks up the registered worker and runs it.

There's a subtle concurrency issue here. If the registry stored the exact &EmailWorker{} pointer and reused it for every job, multiple goroutines could unmarshal payloads into the same Go value at the same time.

Swig avoids this with a factory approach internally. Registration captures the worker type, and each claimed job gets a fresh worker instance before JSON is unmarshaled. The API stays simple, but internally Swig creates a new EmailWorker for each job. This is a useful Go pattern: keep the public API simple while making the internal lifecycle safer.

How to Add a Job

Here's what adding a job looks like from the user side:

err := swigClient.AddJob(ctx, &EmailWorker{
    To:      "user@example.com",
    Subject: "Welcome!",
    Body:    "Thanks for signing up.",
})

Inside Swig, the process is roughly:

argsJSON, err := json.Marshal(workerWithArgs)
if err != nil {
    return err
}

_, err = db.ExecContext(ctx, `
    INSERT INTO swig_jobs (kind, queue, payload, priority, scheduled_for, status)
    VALUES (\(1, \)2, \(3, \)4, $5, 'pending')
`, jobName, queue, argsJSON, priority, runAt)

How to Enqueue Jobs Inside Transactions

One of the best reasons to use PostgreSQL for jobs is transactional enqueueing.

Imagine a user signs up. You want to insert the user and queue a welcome email. If those happen separately, you can get inconsistent states. With a transaction, both succeed or both fail:

tx, err := pool.Begin(ctx)
if err != nil {
    return err
}
defer tx.Rollback(ctx)

_, err = tx.Exec(ctx, `INSERT INTO users (email) VALUES ($1)`, email)
if err != nil {
    return err
}

err = swigClient.AddJobWithTx(ctx, tx, &EmailWorker{
    To:      email,
    Subject: "Welcome!",
    Body:    "Thanks for joining.",
})
if err != nil {
    return err
}

return tx.Commit(ctx)

If the transaction rolls back, the user isn't created and the job isn't queued. This is much harder to guarantee when your database and queue are separate systems.

How to Handle Multiple Workers Safely

A queue gets interesting when many workers run at the same time. Imagine three workers all asking PostgreSQL for the next pending job. You don't want all three to process the same job.

A naïve approach has a race condition. Two workers can select the same job before either one updates it.

PostgreSQL FOR UPDATE SKIP LOCKED

PostgreSQL can lock rows selected inside a transaction. FOR UPDATE means "lock this row because I plan to update it." SKIP LOCKED means "if another worker already locked a row, skip it and find another one."

This is perfect for a queue:

• Worker A locks job 1

• Worker B skips job 1 and locks job 2

• Worker C skips jobs 1 and 2 and locks job 3

No central coordinator is needed. Swig uses an atomic update pattern:

UPDATE swig_jobs
SET status = 'processing',
    instance_id = $1,
    worker_id = $2,
    locked_at = NOW(),
    attempts = attempts + 1
WHERE id = (
  SELECT id
  FROM swig_jobs
  WHERE status = 'pending'
    AND scheduled_for <= NOW()
  ORDER BY priority DESC, created_at
  FOR UPDATE SKIP LOCKED
  LIMIT 1
)
RETURNING id, kind, payload;

This query finds a pending job, skips already-locked jobs, marks it as processing, records which worker claimed it, and returns the job data. All of this happens atomically. Workers never do a separate SELECT and hope the later UPDATE is still safe.

How to Use Goroutines for Concurrent Workers

Swig starts worker loops as goroutines:

for i := 0; i < maxWorkers; i++ {
    go s.startWorker(ctx, queueType)
}

Each worker runs independently. PostgreSQL coordinates which job each worker gets. Go handles concurrency with goroutines, while PostgreSQL handles safe job claiming with locks.

How to Handle Graceful Shutdown

When a service shuts down, it should wait for workers to finish cleanly. Go's sync.WaitGroup helps:

var wg sync.WaitGroup

wg.Add(1)
go func() {
    defer wg.Done()
    processJobs()
}()

wg.Wait()

Swig also uses sync.Once to make shutdown idempotent. Calling Stop more than once shouldn't panic because of a double channel close. Shutdown paths are often where production systems behave differently from happy-path demos.

How to Wake Workers with LISTEN/NOTIFY

If workers constantly poll the database for jobs, they waste resources when the queue is empty. PostgreSQL has LISTEN/NOTIFY to solve this.

A connection can listen on a channel:

LISTEN swig_jobs;

Another session can send a notification:

NOTIFY swig_jobs, '{"id":"job-id"}';

Swig creates a trigger so PostgreSQL sends a notification after a job is inserted. Workers sleep when there's no work and wake when a new job arrives.

There's an important PostgreSQL detail here: LISTEN is session-scoped. A worker must wait for notifications on the same database session that executed LISTEN. Swig handles this by creating a dedicated listener for each worker that owns one database session throughout its lifecycle.

This is a common backend engineering lesson: abstractions like connection pools are useful, but some database features depend on the lifecycle of a specific connection.

How to Elect a Leader with Advisory Locks

Some queue maintenance tasks should only run on one instance at a time, including retrying failed jobs, recovering stale jobs, and cleaning old history.

Swig uses PostgreSQL advisory locks for this:

SELECT pg_try_advisory_lock($1);

If the result is true, that Swig instance becomes the leader. Advisory locks are also session-scoped, so Swig uses a dedicated advisory-lock connection for leadership. If that session ends, PostgreSQL releases the lock and another instance can take over. Simple failover without ZooKeeper or etcd.

How to Handle Failed Jobs

When a worker returns an error, Swig records the error and either retries the job or marks it as failed:

UPDATE swig_jobs
SET status = CASE
    WHEN attempts >= max_attempts THEN 'failed'
    ELSE 'pending'
  END,
  last_error = $2,
  last_error_at = NOW()
WHERE id = $1;

A Note on Delivery Semantics

It's tempting to say a job queue processes jobs exactly once. In distributed systems, that's a dangerous claim.

Consider this scenario:

1. A worker sends an email

2. The worker crashes before marking the job completed

3. The job is retried

4. The email might be sent again

The accurate description is that Swig provides atomic claiming and at-least-once processing. Because jobs can be retried, workers should be idempotent. Running the same operation more than once should produce the same result as running it once.

How to Abstract the Database Driver

Swig supports both pgx and database/sql through a driver interface:

type Driver interface {
    Exec(ctx context.Context, sql string, args ...interface{}) error
    Query(ctx context.Context, sql string, args ...interface{}) (Rows, error)
    QueryRow(ctx context.Context, sql string, args ...interface{}) Row
    WithTx(ctx context.Context, fn func(tx Transaction) error) error
    NewListener(ctx context.Context, channel string) (Listener, error)
    TryAdvisoryLock(ctx context.Context, lockID int64) (AdvisoryLock, bool, error)
}

The core queue code only depends on behavior, not a specific library. This is a common Go design: define the behavior your core package needs, write small adapters for concrete dependencies, and keep the core logic independent.

Conclusion

A PostgreSQL-backed queue isn't the right answer for every system. If you need massive event streaming, Kafka may be a better fit. If you need complex routing, RabbitMQ may be better.

But for many Go applications, PostgreSQL is already there. Swig shows how far you can get with a small Go API and a few PostgreSQL features:

• Store jobs in a table

• Claim jobs atomically with FOR UPDATE SKIP LOCKED

• Wake workers with dedicated LISTEN/NOTIFY sessions

• Coordinate leadership with advisory locks

• Keep app data and jobs consistent with transactions

• Manage worker lifecycles with goroutines and contexts

That combination makes a solid foundation for background processing and a great project for learning how Go and PostgreSQL work together in production systems. You can explore the full source code at github.com/glamboyosa/swig.