> 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

# Meticulous Onboarding Guide

Set up Meticulous in this order:

1. Connect the repository to Meticulous.
2. Choose automated CLI onboarding or manual setup.
3. Record sessions and confirm Meticulous runs on pull requests.

Connecting the repository first lets Meticulous identify the base and head
versions of each pull request or merge request and publish its test result in
the right place.

---

## 1. Connect your repository

Create your Meticulous organization and project, then connect the Git provider
that hosts the repository. Do this before installing the recorder or configuring
CI.

### GitHub

1. Sign in to [Meticulous](https://app.meticulous.ai) and create or select your organization.
2. Choose **Connect to GitHub** when creating the project.
3. [Install the Meticulous GitHub App](https://github.com/apps/alwaysmeticulous/installations/new) for the organization and repositories you want Meticulous to test.
4. Return to Meticulous, select the repository, and create the linked project.
### GitLab

1. Create a **legacy** GitLab personal access token (not a fine-grained token):
    - Go to your avatar → **Edit profile** → **Personal access tokens**
    - Choose **Add legacy token** (or **Create legacy token**), not **Generate fine-grained token**
    - Under **Scopes**, enable **api** and **read_repository**
    ([guide](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token))
    - Your GitLab user must have **Maintainer** or **Owner** on the project
    - Alternatively, a **project access token** (Premium/Ultimate on GitLab.com) with the same scopes and **Maintainer** role works
    ([project token guide](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html#create-a-project-access-token))
2. In Meticulous, link the repository and paste the token:
    - When creating a GitLab project, or from **Project settings → CI settings → Linked repository**
    - Enter your GitLab **project ID** (from **Settings → General** in GitLab), paste the access token, and configure the webhook shown after linking
3. Add the Meticulous webhook in GitLab (**Settings → Webhooks**):
    - Use the **Webhook URL** and **Secret token** from Meticulous
    - Enable **Merge request events**
### Bitbucket

1. Create a **repository access token** in Bitbucket:
    - Open your repository in Bitbucket Cloud → **Repository settings** → **Access tokens** → **Create repository access token**
    ([guide](https://support.atlassian.com/bitbucket-cloud/docs/create-a-repository-access-token/))
    - Grant **Repositories: Read** and **Pull requests: Read**
2. In Meticulous, link the repository and paste the token:
    - When creating a Bitbucket project, or from **Project settings → CI settings → Linked repository**
    - Enter your Bitbucket **workspace**, **repository slug**, and paste the access token (it is stored securely and never shown again)
3. Add the Meticulous webhook in Bitbucket (**Repository settings → Webhooks → Add webhook**):
    - Use the **Webhook URL** and **Secret** shown by Meticulous after linking
    - Enable the pull request **Updated**, **Merged**, **Declined**, and **Superseded** triggers

Once the linked project exists, choose how you want to install Meticulous.

---

## 2. Choose your setup path

### Meticulous CLI (recommended)

## Automated setup with meticulous onboard

`meticulous onboard` uses Claude Code or Codex on your machine to inspect the
application and prepare a pull request containing the recorder and CI
configuration. Meticulous does not host the model inference; the command uses
your existing Claude Code or Codex account.

### Prerequisites

- Run the command from a clone of the connected Git repository.
- Install and authenticate [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex](https://developers.openai.com/codex/cli/).
- Use Node.js 20 or newer.

### Run onboarding

From the application repository. If you are not logged in, the command opens a
browser to sign in, then continues:

```bash
npx @alwaysmeticulous/cli onboard --project="<ORGANIZATION>/<PROJECT>"
```

On a remote machine where a browser cannot reach this terminal, sign in first
with device login, then re-run onboard:

```bash
npx @alwaysmeticulous/cli auth login --device
```

It asks you to choose the frontend application in a monorepo and the local
coding agent, reviews the repository, proposes a plan for approval, and then
opens a setup pull request.

After the pull request is ready:

1. Review and merge the recorder and CI changes.
2. Add any requested API token to your CI provider&apos;s secret store.
3. Record a representative session.
4. Open a pull request and confirm that Meticulous reports a result.
### Manual setup

## Manual recorder and CI setup

Use the guided setup in the Meticulous app or follow these docs:

1. [Install the recorder](/docs/recorder-installation) for localhost and your
   trusted internal or preview environments.
2. Exercise a representative user flow and confirm the session appears in the
   Meticulous project.
3. [Replay the session locally](/docs/how-to/detect-diffs-locally) before moving to
   CI. Debugging locally is faster than debugging a CI-only failure.
4. [Choose a CI approach](/docs/ci):
   [upload static assets or a container](/docs/github-actions-v2).

For authenticated applications, make sure the recorded flow can sign in and
replay reliably. See [Troubleshooting authentication](/docs/how-to/troubleshoot-auth)
and [recording and replaying across environments](/docs/how-to/record-and-replay-on-different-environments).

---

## 3. Verify the complete setup

Setup is complete when:

- The project is linked to the correct GitHub, GitLab, or Bitbucket repository.
- At least one representative session reaches Meticulous.
- A session replays successfully against your application.
- The default branch has a baseline test run.
- A pull request or merge request produces a Meticulous result.

If something fails, start with [recorder troubleshooting](/docs/how-to/troubleshoot-recorder)
or the [FAQ and troubleshooting guide](/docs/faq-and-troubleshooting).

After the first successful run, [make the Meticulous check blocking](/docs/make-check-blocking)
and [reduce false-positive diffs](/docs/how-to/fix-false-positive-diffs).