How relai works

This page explains what relai is doing under the surface: what a pin actually is, what gets captured and why each piece matters, how your team is organised, how a pin reaches an AI coding agent, and — in detail — what relai never records. No prior technical knowledge is assumed. Where a technical word is unavoidable, it is explained the first time it appears.

If you just want to get set up, read Getting started with relai instead.

The problem relai solves

Feedback about a website usually arrives as a sentence: “the checkout button is broken”. By the time it reaches the person who can fix it, almost everything useful has been lost — which button, on which page, in which browser, what the person had done just before, and whether the site quietly reported an error at that moment.

So the developer spends their first hour reconstructing the report rather than fixing anything, and often cannot reproduce it at all.

relai’s answer is to capture all of that at the moment you notice the problem, automatically, without asking you to do anything beyond pointing at it. That bundle is called a pin.

What a pin is

A pin is one piece of feedback, attached to one specific thing on one specific page — together with a snapshot of the circumstances it was reported in.

Every pin carries:

• What the person wrote, and the type and priority they gave it.
• A picture of what they were looking at.
• An exact record of which element on the page they pointed at.
• The technical circumstances at that moment — browser, page, errors, and more.
• Its own discussion thread, status, assignee and labels.

A pin stays attached to the element it was dropped on. Go back to that page later and the marker is still sitting there, so a pin is a durable, findable place to hold a conversation about one specific thing — not a message that scrolls away.

What a pin captures, and why each piece matters

This is the heart of relai. Each piece below answers a different question that a person fixing the bug would otherwise have to ask.

The screenshot

relai takes a picture of the element that was pinned, plus a margin of the page around it for context. Depending on the capture mode you chose, it can instead be a region you drew, or the whole page.

Why it matters: it answers “what did they actually see?” — the question that otherwise costs a round of back-and-forth. It also carries all the things nobody thinks to describe: the half-cut-off text, the wrong shade of grey, the notification overlapping the button.

If a site blocks the screenshot step, the pin still saves with everything else intact. A missing screenshot is a degraded pin, never a failed one.

The exact element

This is what separates a pin from a screenshot with an arrow on it. relai records which thing on the page was pointed at, in a way a person or a machine can find again later.

A web page is built from thousands of nested pieces called elements — a button is an element, so is a heading, an image, a row in a table. To describe one unambiguously you need a locator: a short piece of text that means “this exact one”.

relai gathers four kinds of evidence, in order of how well each survives the site changing:

1. Named handles. Some elements carry a deliberate, invisible name in the site’s code — most commonly one called data-testid. These are the gold standard: they are stable, they survive redesigns, and they say what the thing is.
2. Human-readable meaning. The visible text, the accessibility label, the placeholder text, what kind of element it is. Good for understanding, but it breaks the moment somebody rewords the button.
3. Structural position. Where the element sits relative to the nearest named thing above it — deliberately not relative to the whole page, which would break every time anything anywhere moved.
4. Visual position. Where it sat on screen, as a percentage of the window rather than in pixels, so it still means something on a different screen size. A last resort.

relai then picks the best single locator available and scores it 0–100 for confidence — how reliably it expects to find that element again. A named handle scores 98. A stable identifier scores 85. An accessibility label scores 62. Visible text scores around 55. Nothing but position scores in the single digits.

Why it matters: a high-confidence locator means the marker stays on the right thing months later, and it means an AI agent can find that element in the code immediately rather than guessing. If your pins score badly on a site, that is fixable in about a minute per element — see Make relai pin the same spot every time.

Alongside the locator, relai records the element’s live layout settings and those of the things containing it, and — on sites built with React, a common way of building web apps — the names of the components it sits inside. Layout bugs are very often caused by a container two levels up rather than by the element you can see, so this frequently points straight at the real culprit.

Console errors

Every browser keeps a hidden diagnostic log called the console. When something in a site’s code goes wrong, it usually complains there. Nobody except a developer ever opens it, which is why these messages are almost always lost.

relai keeps a rolling record of errors and warnings from the page and attaches those from around the moment of the pin. Anything logged within about five seconds of the click is flagged as likely connected to what the person just did, as opposed to background noise the page produces anyway.

Why it matters: this is often the single most valuable line in the whole pin. It frequently names the exact file and line that failed, turning “it doesn’t work” into a specific, located defect before anyone has tried to reproduce anything.

The failing network request

Web pages constantly talk to servers in the background — fetching your basket, saving a form, checking a price. Each of those exchanges is a network request. When one fails, the page often shows nothing useful: a blank area, a spinner that never stops, or a generic “something went wrong”.

When a workspace opts in, relai keeps a short rolling record of these exchanges — roughly the last twenty seconds, up to fifty of them — and attaches it to the pin, with the failing one identified as the likely culprit.

Why it matters: a screenshot of a blank screen is nearly useless. The same pin with a failed request and the server’s error message attached is a fixable bug. This is what turns relai from a tool for reporting visual problems into one that can also report things that are actually broken.

This is off unless a workspace owner or admin switches it on, and everything in it is stripped of sensitive values before it is stored. Details in What relai never captures.

The steps that led up to it

The oldest question in bug reporting is “what were you doing?” — and the honest answer is usually that the person cannot remember.

With the same opt-in as network capture, relai records the last handful of meaningful actions before the pin — roughly fifteen seconds, up to thirty actions. Things clicked, pages moved between, forms submitted, and which fields were typed in. It reads like clicked Apply → went to /checkout → edited Coupon → [pin].

Why it matters: it converts a bug that only one person can trigger into one anybody can follow. It also often reveals that the problem started two steps before the screen the person was complaining about.

What was typed is never recorded. relai stores which field was edited, never its contents. This is a hard line in the product, not a setting.

The technical circumstances

Always captured: browser and version, operating system, screen and window size, language, the page address, its title, and the exact time. Where a site publishes its own build version, relai records that too, so a developer can tell which release of the site the person was actually looking at.

Why it matters: a large share of bugs are conditional — only in Safari, only on a narrow window, only on the version deployed last Tuesday. Without this, that is discovered after an hour of failing to reproduce the problem. With it, it is the first thing anyone notices.

Workspaces and sites

A workspace is your team. It holds your people, your sites, and all your pins. Everyone you invite joins the same workspace and sees the same pins. Most companies need exactly one; you can belong to several — an agency working for several clients, say — and switch between them from the top of the left sidebar. Pins never cross between workspaces.

A site is one web address you have registered. Registering it tells relai that this address belongs to your workspace, so pins dropped there are filed under it. A workspace can hold as many as you like — your live site, your staging site, a version running on a developer’s own machine.

Two consequences worth knowing, because they explain most confusion during setup:

• The address must match. relai treats acme.com and www.acme.com as different places. Register the one people actually use.
• Registering is per workspace; permission is per browser. A site is registered once for everybody, but each teammate must separately allow the relai extension to run on it in their own browser. That is a rule browsers enforce, not a relai choice — which is why relai’s status messages about a site being “disabled” always mean disabled here, in this browser.

How the AI coding agent handoff works

An AI coding agent is an assistant that works inside a developer’s code and can make changes to it — Claude Code, Cursor, Codex and similar tools. Developers increasingly hand work to these rather than doing every edit by hand.

The bottleneck is context. An agent asked to “fix the checkout button” has no idea which button, on which page, or what went wrong. Someone has to assemble that first — which is exactly the work relai has already done.

So relai lets an agent read pins directly. A developer connects their agent once, from Connect your agent in the sidebar: they generate a personal access token and copy a short configuration snippet for whichever tool they use. The agent then talks to relai over a standard called MCP — a common language for connecting AI assistants to outside tools. Nothing is installed or run locally.

Once connected, the agent can do five things:

• List pins — browse the workspace’s open pins, filtered by status, site, assignee or priority.
• Read one pin in full — everything above, including the screenshot as an actual image the agent can look at, the locator, the console errors, the failing request, the steps to reproduce, the element’s layout state and component names, and the comment thread.
• Change a pin’s status — to open, in progress, or resolved, optionally attaching a note and a link.
• Resolve a pin — marking it done and attaching the link to the change that fixed it.
• Comment on a pin — writing back into the pin’s own thread, where whoever reported it will see it.

What this means in practice. A developer can say “take a look at pin 4”, and the agent pulls the screenshot, the element, the errors and the reproduction steps itself, then works from those. The report a non-technical colleague wrote by pointing at a button becomes a specification an agent can act on, with no translation step in between — and when the work is done, the agent writes the outcome back into the same pin, so the person who reported it sees it close.

Two things to be clear about. The agent’s access is bounded by the token of the person who created it: it sees their workspace and obeys their role, so an agent connected by a comment-only user can comment but cannot change anything. And relai does not itself write code or open pull requests — it supplies context to the tool that does, and records what came back.

Pins are also readable by hand. Every pin’s detail page shows the same material a human can read — under Locator details, Environment, Steps to reproduce, Network, Element state, Component and Console. Where AI Assist was used when the pin was written, an Agent brief section holds the structured version: the intent, the acceptance criteria, and any constraints.

What relai captures, and what it never captures

relai is pointed at your own websites by your own colleagues, and it is deliberately conservative about what it retains. Here is the whole picture.

Always captured

• The page address, page title, and the time.
• A screenshot of the pinned element, region, or page.
• The element’s identifying attributes, visible label, and position.
• Browser, operating system, screen and window size, language.
• Console errors and warnings from around the moment of the pin.
• Your name and email, and what you wrote.

Captured only if your workspace opts in

• The recent network requests around the pin.
• The recent actions leading up to the pin.

Both are controlled by one switch — Capture network activity on pins, under Settings → Workspace → Network capture, which only owners and admins can change. It is off by default. And even with it on, you see a preview of exactly what would be attached and can untick it before saving.

Never captured

These are enforced in the capture code itself, not left to configuration:

• Anything typed into a form. Where relai records that a field was edited, it stores the field’s identity only. Its contents are never read.
• Login credentials and session identifiers. Authorisation headers and cookies are never captured at all.
• The text content of the page structure. relai stores a skeleton of the pinned element’s structure to help diagnose layout problems — the tags, the arrangement, the named handles. Every piece of text inside it is replaced with a placeholder before it is stored, and anything holding a value is removed entirely.
• Application internals. Where relai identifies the components an element sits inside, it takes their names only — never the data flowing through them.
• Uploaded files. File contents are skipped rather than recorded.

How sensitive data is stripped from what is kept

Network capture is the one place where relai handles data a site is genuinely exchanging, so it runs through a filter before anything is stored — not on the way out, and not on display. Nothing unredacted is ever retained.

• Web addresses are trimmed. Everything after the question mark — where tokens and search terms usually hide — is discarded outright. What remains is scanned again and anything token-shaped is masked.
• Only readable content is kept, and only a little. Requests and responses are captured only when they are text or structured data, and only the first couple of kilobytes of each. Anything else is skipped.
• Secrets are masked by shape and by name. Anything looking like a security token — long strings of hex or encoded characters, or the three-part tokens used for sessions — is replaced. So is any value labelled with a sensitive name: password, secret, token, api key, authorisation, session, private key and their common variants.

A masked value is replaced with a visible marker, so a developer reading the pin can see that something was there and that relai removed it.

One honest caveat about screenshots

A screenshot is a picture of what was on screen. If you pin something on a page that is showing real customer data, that data is in the picture. relai cannot detect this for you.

It is the one part of a pin where what gets captured is entirely your choice. If you work with sensitive records, use test data where you can, and prefer Element capture over Full page — it photographs the thing you pointed at plus a small margin, rather than everything on screen.

Roles: who can do what

Every person in a workspace has one of four roles. Owners and admins set them from the Users page. These are enforced by relai’s servers, not merely hidden in the interface — and they apply equally to a connected AI agent, which inherits the role of whoever connected it.

• Owner — full control. Everything an admin can do, plus granting the owner role itself. Only an owner can make another owner.
• Admin — everything a member can do, plus managing the workspace: its settings, its sites, its integrations, and inviting or changing the role of anyone who is not an owner.
• Member — the normal working role. Capture pins, and triage them: change status, priority, assignee and labels, comment, and use the AI enhancement tools. No access to workspace settings or to managing people.
• Comment only — read pins and take part in discussions. Cannot change a pin’s status or any of its fields. Suitable for a client, a stakeholder, or anyone you want reading and commenting without reorganising the board.

Capturing pins is not a privileged action: anyone in the workspace, including comment-only users, can drop one. What roles govern is what happens to a pin afterwards.