> Meticulous records real user sessions from a web app and replays them against each commit to catch visual regressions.
>
> Full AI-readable docs index (complete project setup journey + every page as markdown): https://app.meticulous.ai/llms.txt

# Recorder Developer Tools

The recorder ships with an in-browser developer overlay that you can opt into on
any non-production environment. It gives you two things directly inside the page
the recorder is running on:

1. **Manual session selection** — mark the session you are currently recording as
   always-run in CI, without leaving your app.
2. **Local mocks** — switch between mock network scenarios served by a local
   [Meticulous Local Mocks](#local-mocks) MCP server while you iterate
   on UI.

It appears as a small dark logo in a corner of the page that you can drag and
click to expand. The overlay never loads in production environments and the
recorder snippet has to be installed for it to show up — see
[Install the Recorder](/docs/recorder-installation) if you don't have it set up yet.

## Enabling the developer tools

Open the browser DevTools console on any page where the recorder is running and
run:

```javascript
window.Meticulous.enableDeveloperTools();
```

This sets a local flag and reloads the page. From then on, every time the
recorder loads on any non-production origin in this browser, the developer
overlay is loaded too.

The overlay does **not** load if the recorder script reports the page as a
production environment (`data-is-production-environment="true"` on the
recorder snippet tag). This is intentional — the manual selection and local
mocks features are development tooling, not user-facing features.

## Manually selecting a session

Meticulous's [automatic session selection](/docs/how-to/testing-pool) is the
recommended default for almost everyone: it continuously adapts the suite of
sessions executed in CI to maximize coverage of your application as it changes.

There are still cases where you want to nail a specific user flow to the
suite — for example, a regression you just hand-recorded, or a flow that
exercises an edge case the auto-selector keeps missing. The "Manually select
session" button in the overlay does exactly that, without you having to leave
the page or open the Meticulous app.

### How it works

1. Perform the user flow you want to capture.
2. Click the Meticulous logo in the corner to open the overlay.
3. Click **Manually select session**. Optionally give the session a memorable
   name (e.g. "Checkout — happy path") and confirm.
4. A popup will open prompting you to approve the request in the Meticulous
   app — see [Approval flow](#approval) below.
5. Once approved, the button switches to **Manually selected**. Click it again
   to remove the session from the manually-selected set.

A small "Manage manually selected sessions" link in the overlay deep-links you
to the project's full manual-selection list in the Meticulous app at any time.

### Limits

Each project has a hard cap on the number of manually-selected sessions
(currently **50**) to keep CI focused. The overlay will warn you about this
before you confirm. Manual selection is intended for the handful of flows you
explicitly want to pin — use auto-selection for everything else.

## The approval flow

Because the recorder runs on your own origin (e.g. your local dev URL), rather than meticulous.ai,
it cannot directly speak to the Meticulous app with your session cookies. So
the first time you ask the overlay to mark or unmark a session, it opens a
small approval popup that:

- Asks you to sign into the Meticulous app (if you aren't already).
- Asks you to explicitly approve giving this browser permission to
  mark/unmark sessions for the project.

After you approve once, the overlay caches a short-lived bearer token in your
browser. Subsequent mark/unmark actions complete instantly without re-prompting,
until the token expires (~8 hours) or you sign out.

The approval popup is opened synchronously inside the click handler so that
browser popup blockers honor it. If your browser still blocks it, allow popups
for the page and try again.

## Local mocks

The "Local Mocks" panel in the overlay is a switcher for mock network scenarios
served by the **Meticulous Local Mocks MCP server**, an opt-in tool that
records the network traffic of your local browsing and lets your coding agent
generate scenarios from it.

When the MCP server is running and paired with the overlay, you can pick a
scenario from the dropdown to have the overlay intercept and replay its
recorded responses for the rest of the page session — useful for flicking
between edge cases (e.g. empty state, error state, paginated state) while you
iterate on the UI, without having to set up a backend to reproduce them.

If you don't have the MCP server running, the panel shows an "Enable
Auto-Mocks (alpha)" button that walks you through the one-time pairing step.

## Repositioning the overlay

Drag the logo to any corner of the page. The overlay remembers which corner it
was last in (per browser tab) and snaps to it on the next page load. Because it
anchors to the nearest viewport corner with CSS, it stays in view even when you
resize the window.

## Disabling the developer tools

Run the following in the browser DevTools console:

```javascript
localStorage.removeItem("meticulous.developer-tools");
location.reload();
```

The overlay will stop loading on subsequent page loads. Your manual-selection
approval token and any locally-marked sessions remain on the server; the
overlay just won't surface them on this device.