Setting up Meticulous for agents

The primary interface for agents we provide is the Meticulous CLI plus a range of pre-defined skills. These skills enable AI coding assistants (Claude Code, Codex, Cursor, etc.) to use Meticulous: review test runs, investigate replays, debug diffs, etc.

The Meticulous CLI is required to run simulations and test runs from the command line:

npm install --global @alwaysmeticulous/cli@latest

You can also install it locally per-project instead of globally.

The CLI is under active development with frequent changes and improvements — re-run the same command to update to the latest version. The skills also invoke the meticulous-cli-update skill at the start of every workflow to keep this in sync automatically.

Authenticate the CLI with your Meticulous account:

meticulous auth login

This will open a browser to sign in, and if you're a member of multiple projects, let you pick which one to use. You can switch projects later by running meticulous auth set-project. Non-interactive versions of both commands are also available, for use in CI or other non-TTY environments: meticulous auth login --non-interactive --project <organization/project> and meticulous auth set-project --project <organization/project>.

Install skills into your project using npx skills:

# Claude Code only: create .claude/ first if it doesn't already exist
mkdir -p .claude

# Install all skills for the specified agents
npx skills add alwaysmeticulous/skills --all --agents claude-code,codex,cursor

# Update already-installed skills to the latest version
npx skills update --project

See the Skills page for the full list of available skills and what each one does.

The Meticulous skills run a small set of CLI commands and read downloaded screenshots from ~/.meticulous/agent-images/. Pre-allowing these in your agent configuration avoids repeated permission prompts during a session.

Add the following to .claude/settings.json (project-level) or ~/.claude/settings.json (user-level). Replace /HOME/DIR with your home directory path (e.g. /Users/alice).

{
  "permissions": {
    "allow": [
      "Read(~/.meticulous/agent-images/**)",
      "Bash(meticulous *)",
      "Skill(meticulous-cli-update)",
      "Bash(npm view @alwaysmeticulous/cli version)",
      // If you want to auto-approve updating the CLI and skills, also add:
      "Bash(npm install --global @alwaysmeticulous/cli@latest)",
      "Bash(npx skills update --project)"
    ]
  }
}

Add the following to ~/.codex/rules/default.rules:

prefix_rule(pattern=["meticulous"], decision="allow")
prefix_rule(pattern=["npm", "view", "@alwaysmeticulous/cli", "version"], decision="allow")
# If you want to auto-approve updating the CLI and skills, also add:
prefix_rule(pattern=["npm", "install", "--global", "@alwaysmeticulous/cli@latest"], decision="allow")
prefix_rule(pattern=["npx", "skills", "update", "--project"], decision="allow")

Add the following entries to Cursor's Command Allowlist:

meticulous
npm view @alwaysmeticulous/cli version
# If you want to auto-approve updating the CLI and skills, also add:
npm install --global @alwaysmeticulous/cli@latest
npx skills update --project