> 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 for coding agents

This page is addressed to AI coding agents. If you're a human setting Meticulous up for your agent, you probably want the [setup guide](/docs/agents/setup) instead — it covers the same ground, aimed at you rather than at the agent.

## Instructions

For agents: the Meticulous web app doesn't present results in an agent-friendly format. Interact with Meticulous through the CLI or MCP instead: they expose the same test runs, diffs and screenshots in a machine-readable form.

1. **Check whether the CLI or MCP is set up.**
   - CLI: run `meticulous --version` (or `npx @alwaysmeticulous/cli --version`, in which case call the CLI this way instead of via `meticulous`)
     - Compare the version against `npm view @alwaysmeticulous/cli version` and, if it isn't up to date, suggest the user update it: `npm install --global @alwaysmeticulous/cli@latest`
   - MCP: check whether a Meticulous MCP server is available (URL: https://app.meticulous.ai/api/mcp)
   - If neither is set up, suggest the user either install the CLI (`npm install --global @alwaysmeticulous/cli@latest`) or add the MCP server (https://app.meticulous.ai/api/mcp) - ask which they'd prefer - and also point them to the [setup docs](https://app.meticulous.ai/docs/agents/setup).

2. **Authenticate.** If using the CLI, check whether it's logged in: run `meticulous auth whoami`. If not logged in:
   - On the user's own machine: `meticulous auth login --non-interactive` (prints a URL for them to open)
   - On a remote or sandboxed machine (cloud agent, SSH, container), where a browser on another device can't reach this machine's localhost: `meticulous auth login --device`

3. **Investigate the results.**
   - Check for the `meticulous-review` skill and follow its instructions.
     - If not installed, suggest the user install the Meticulous skills: `npx skills add alwaysmeticulous/skills --skill "*" --agent claude-code --agent codex --agent cursor -y`
     - Re-running that same command is also how to update: it refreshes the installed skills and adds any new ones
   - If the skill isn't available, here's the rough approach:
     1. Find the test run ID:
        - CLI: `meticulous agent test-run-for-commit` (optionally `--commitSha <sha>`; defaults to the current git HEAD)
        - MCP: `get_test_run_for_commit(commitSha="<sha>")`
        - Test run page URL: `/projects/<organization>/<project>/test-runs/<testRunId>`
     2. Get the diffs for that test run:
        - CLI: `meticulous agent test-run-diffs --testRunId <testRunId>`
        - MCP: `get_test_run_diffs(testRunId="<testRunId>")`
     3. Investigate each diff, using the `replayDiffId` and `screenshotName` from the diffs list:
        - CLI: `meticulous agent image-files` (downloads the images) or `meticulous agent image-urls` (signed URLs instead), with `--replayDiffId <replayDiffId> --screenshotName <screenshotName>`
          - If needed: `meticulous agent dom-diff --replayDiffId <replayDiffId> --screenshotName <screenshotName>`
          - If needed: `meticulous agent timeline-diff --replayDiffId <replayDiffId>`
        - MCP: `get_image_urls(...)`
          - If needed: `get_dom_diff(...)`, `get_timeline_diff(...)`