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 instead — it covers the same ground, aimed at you rather than at the agent.

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.

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(...)