You built a landing page. Traffic is coming in. But your conversion rate is stuck at 1.3% and you have no idea why.

CROtomate fixes that. You run one command. It reads your source code, generates a hypothesis (e.g., "change the CTA from Get Started to Start Free Trial"), rewrites the code, pushes to GitHub, waits for real visitors, measures the impact, and keeps the change if it worked, or reverts it if it didn't. Then it does it again. And again. Forever.

No A/B testing tools. No manual experimentation. No dashboard staring. Just a CLI that turns your site into a self-improving conversion machine.

npm install -g crotomate
crotomate init
crotomate run

That's it. Go to bed.

Table of contents

• How it works
• Quickstart
• What it actually changes
• SCOPE.md
• Supported LLM providers
• Deployment setup
• Analytics setup
• Commands
• Configuration reference
• How experiments are tracked
• FAQ
• Self-hosting on a VPS
• Contributing

How it works

    ┌──────────────────────────────────────────────────┐
    │                                                  │
    │   1. measure conversion rate (PostHog/Plausible) │
    │                   │                              │
    │                   v                              │
    │   2. LLM proposes ONE hypothesis                 │
    │                   │                              │
    │                   v                              │
    │   3. LLM implements the code change              │
    │                   │                              │
    │                   v                              │
    │   4. git commit + push (triggers auto-deploy)    │
    │                   │                              │
    │                   v                              │
    │   5. wait for N visitors + minimum hours         │
    │                   │                              │
    │                   v                              │
    │   6. CR improved? ── yes ──> KEEP                │
    │          │                                       │
    │          no                                      │
    │          │                                       │
    │          v                                       │
    │       git revert + push                          │
    │                   │                              │
    │                   v                              │
    │               loop back to 1                     │
    │                                                  │
    └──────────────────────────────────────────────────┘

Note: CROtomate runs experiments sequentially (before/after), not as simultaneous A/B splits. It measures the baseline conversion rate, deploys one change, measures again, and decides whether to keep or revert.

The key insight: Any site that auto-deploys when you push to a git branch works — Vercel, Netlify, GitHub Pages, or any CI/CD pipeline. CROtomate just uses git as the deployment bridge and its own memory (every experiment is a commit).

Quickstart

Prerequisites

• Node.js 18+
• A website that auto-deploys when you push to a git branch (Vercel, Netlify, GitHub Pages, any CI/CD)
• Analytics on your site (PostHog or Plausible)
• An API key from any supported LLM provider

Install and run

# Install globally
npm install -g crotomate

# Set your LLM API key
export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY, GOOGLE_API_KEY, etc.
# Or add it to a .env file in your project root

# Interactive setup: picks your analytics, LLM, and thresholds
crotomate init

# Start the loop
crotomate run

The init wizard creates a crotomate.config.json and a SCOPE.md in your project root. The run command starts the autonomous loop. Press Ctrl+C to stop gracefully after the current experiment finishes.

To update to the latest version:

npm update -g crotomate

What it actually changes

CROtomate changes whatever you tell it to in SCOPE.md. Out of the box, the default SCOPE.md permits:

• Headline and subheadline copy
• CTA button text, color, and size
• Social proof placement and wording
• Hero section layout
• Form field reduction
• Above-the-fold content ordering
• Trust signals and urgency/scarcity elements

But this list is yours to edit. Want the agent to also experiment with background images or page copy below the fold? Add it to SCOPE.md. Want it to leave your testimonials alone? Add that to the Forbidden Changes section.

The only rules you cannot override are the hardcoded safety floor — the agent will never touch routing, authentication, payment flows, backend logic, database schemas, environment variables, or build configuration, no matter what SCOPE.md says.

You have two layers of control:

• SCOPE.md — tell the agent what to focus on, what to avoid, and how your brand sounds
• editableGlobs / lockedGlobs in your config — control which files it can touch at the filesystem level

SCOPE.md

SCOPE.md is the system prompt for the CRO agent. It lives in your project root (next to crotomate.config.json) and tells the AI exactly what it's allowed to change and what's off limits.

The default SCOPE.md is intentionally restrictive — the agent can change copy, tweak button styles, and reorder above-the-fold elements, but cannot touch navigation, pricing, auth flows, state management, API calls, or anything structural. You can loosen or tighten these rules to match your comfort level.

What's inside

| Section | Purpose | | --- | --- | | Optimization Focus | What the agent may experiment with (copy, CTA styling, element placement, forms, social proof, urgency) | | Forbidden Changes | What the agent must never touch, even if it thinks it would help (structure, business logic, integrations, code architecture, assets) | | Brand Guidelines | Your voice, tone, color rules, and style constraints | | Additional Instructions | Target audience, product context, known issues, current promotions |

How it works

• crotomate init creates a default SCOPE.md if one doesn't exist
• The agent reads SCOPE.md before every experiment and injects its rules into the LLM prompt
• Built-in safety rules (no auth, no routing, no payments, no backend, no env vars, no build config) always apply on top and cannot be overridden — even if you remove them from SCOPE.md
• If you delete SCOPE.md, the agent falls back to the same defaults

Customizing it

Open SCOPE.md and edit it directly. The Brand Guidelines and Additional Instructions sections come with commented-out examples — uncomment the ones that apply to you and fill in your details. The more context you give the agent about your brand and audience, the better its hypotheses will be.

Supported LLM providers

| Provider | Config value | Env var | Default model | | --------- | ------------ | ------------------- | ---------------------- | | Anthropic | anthropic | ANTHROPIC_API_KEY | claude-opus-4-5 | | OpenAI | openai | OPENAI_API_KEY | gpt-4o | | Google | google | GOOGLE_API_KEY | gemini-2.0-flash | | Mistral | mistral | MISTRAL_API_KEY | mistral-large-latest | | xAI | xai | XAI_API_KEY | grok-3 |

Other models suggested by the init wizard: claude-sonnet-4-5, claude-haiku-4-5, gpt-4o-mini, o3-mini, gemini-2.5-pro, mistral-small-latest, grok-3-mini. You can use any model your provider supports by setting the model field in your config.

Use the most capable model you can afford. The LLM is doing three hard jobs: understanding your codebase, generating high-quality hypotheses, and writing production code that deploys without breaking anything. More capable models (Claude Opus, GPT-4o, Gemini 2.5 Pro) understand your code structure better, produce sharper hypotheses grounded in what actually matters for conversions, and write cleaner code that won't cause deployment failures. Smaller or cheaper models are more likely to misread your codebase, propose generic hypotheses, or generate code that fails to compile — wasting the entire experiment. Don't save $0.05 per experiment and risk broken deploys.

CROtomate makes ~2 LLM calls per experiment (one for the hypothesis, one for the code change). At GPT-4o pricing with one experiment per day, that's roughly $0.10-$0.50/day depending on your codebase size.

Set the env var or add it to a .env file in your project root. See the full LLM setup guide for model options and billing notes.

Deployment setup

CROtomate deploys by pushing to your configured git branch. Your hosting platform or CI/CD pipeline picks up the commit and rebuilds automatically. No platform-specific integration needed.

This works out of the box with any auto-deploying setup:

• Vercel — pushes to your production branch trigger a rebuild
• Netlify — same, auto-deploys on push
• GitHub Pages — with a GitHub Actions workflow
• Any CI/CD pipeline — as long as pushing to the branch triggers a deploy

Just make sure the repoBranch in your config matches the branch your hosting watches.

Analytics setup

CROtomate needs read access to your analytics to measure conversion rates before and after each experiment.

| Provider | What you need | Guide | | --------- | --------------------------------- | -------------------------------------- | | PostHog | Personal API key + Project ID | Setup guide | | Plausible | API key + site domain + Goal name | Setup guide |

You define what "conversion" means: a custom event like signup_completed, a goal like purchase, or a pageview goal like /thank-you.

Commands

| Command | What it does | | ------------------------------ | ---------------------------------------------------------- | | crotomate init | Interactive setup wizard. Creates crotomate.config.json and SCOPE.md. | | crotomate run | Start the optimization loop. Runs until stopped. | | crotomate run --once | Run a single experiment, then exit. | | crotomate run --iterations 5 | Run exactly 5 experiments, then exit. | | crotomate status | Show experiment history table and current CR. | | crotomate rollback | Revert the last kept experiment (with confirmation). |

Tip: Set DEBUG=1 to see full stack traces on errors (e.g., DEBUG=1 crotomate run).

Example status output

#   Date        Hypothesis                            Baseline  Variant  Delta    Result
--- ----------- ------------------------------------- --------- -------- -------- ------
1   2025-01-15  Change CTA to "Get Started Free"         3.10%    3.80%   +22.6%  kept
2   2025-01-17  Move social proof above the fold         3.80%    3.65%    -3.9%  reverted
3   2025-01-19  Add "No credit card required" badge      3.80%    4.15%    +9.2%  kept
4   2025-01-21  Make hero headline more specific         4.15%    4.10%    -1.2%  reverted

Total: 4 | Kept: 2 (50%) | Avg lift: +15.9% | Current CR: 4.15%

Configuration reference

crotomate.config.json is created by crotomate init. SCOPE.md controls the agent's behavior (what it focuses on, what it avoids, brand rules). All config fields:

{
  "projectName": "my-landing-page", // used in logs
  "repoPath": "/home/user/my-site", // absolute path to your local git clone
  "repoBranch": "main", // branch to push to (default: "main")

  "analytics": {
    "provider": "posthog", // "posthog" | "plausible"
    "apiKey": "phc_...", // your analytics read API key
    "projectId": "12345", // PostHog project ID or Plausible site domain
    "conversionEventName": "signup_completed", // the event that counts as a conversion
    "baseUrl": "https://us.posthog.com", // optional, for self-hosted PostHog or Plausible
  },

  "llm": {
    "provider": "anthropic", // "anthropic" | "openai" | "google" | "mistral" | "xai"
    "model": "claude-opus-4-5", // see provider table above
    // API key is NEVER stored here, always read from env var
  },

  "loop": {
    "minVisitorsPerTest": 200, // wait for at least this many visitors
    "minTestDurationHours": 24, // wait at least this many hours
    "maxIterations": null, // optional, stop after N experiments
    "pollIntervalMinutes": 30, // how often to check analytics
    "keepThresholdPercent": 2, // minimum % improvement to keep a change
  },

  "editableGlobs": ["src/**/*.tsx", "src/**/*.css"], // files the agent CAN edit
  "lockedGlobs": ["package.json", "tsconfig*.json"], // files the agent must NEVER touch
}

How experiments are tracked

Every experiment is saved as a JSON file in the experiments/ directory:

experiments/
  2025-01-15T10-30-00-000Z-change-cta-to-get-started-free.json
  2025-01-17T14-22-00-000Z-move-social-proof-above-fold.json

Each file records the hypothesis, files changed, baseline and variant conversion rates, the decision (kept/reverted), commit SHAs, duration, visitor count, and which LLM was used. The agent reads the last 20 experiments before generating each new hypothesis to avoid repeating past ideas.

Git is also memory. Every kept experiment is a commit, every reverted experiment leaves a revert commit. Run git log --oneline to see the full history.

FAQ

Use the most powerful model you can afford. The model needs to understand your codebase, write hypotheses that target real conversion levers, and produce code that deploys cleanly. More capable models do all three better. Claude Opus and GPT-4o are the recommended defaults. Gemini 2.5 Pro is a strong alternative. Avoid small/cheap models (Haiku, GPT-4o-mini, Flash) for production use — the cost savings are minimal ($0.01-$0.05 per experiment) and not worth the risk of shallow hypotheses, ignored SCOPE.md constraints, or broken deploys.

Lower minVisitorsPerTest in your config (e.g., to 50 or even 20). Smaller sample sizes make results less statistically reliable, but for early-stage sites any signal is better than guessing. You can also lower minTestDurationHours to speed up iterations.

Every change is a git commit. If something goes wrong, crotomate rollback reverts the last experiment in one command. The agent is constrained at three levels: hardcoded safety rules (never touches auth, routing, payments, backend), your SCOPE.md (defines exactly what it can and can't change), and lockedGlobs (files it physically cannot edit). Use a powerful LLM — smaller models are more likely to generate code that fails to compile, which means the deploy fails and the experiment is wasted.

Yes. Press Ctrl+C to stop the loop gracefully. It'll finish the current experiment phase and exit. Make your changes, push, then restart with crotomate run.

It depends on your traffic. With minVisitorsPerTest: 200 and 200 daily visitors, each experiment takes about 1 day. 1,000 visitors/day? A few hours. The minTestDurationHours setting (default: 24h) sets a floor regardless of traffic to account for time-of-day effects.

Run it on a cheap VPS ($5/mo) inside tmux or as a systemd service. See self-hosting below.

CROtomate itself is free and open source. You pay for LLM API calls (~$0.10-$0.50/day at one experiment per day with GPT-4o) and your analytics provider (PostHog and Plausible both have generous free tiers). A VPS for 24/7 operation runs ~$5/mo.

Make sure your git credentials (SSH key or HTTPS personal access token) are configured for pushing to the remote. CROtomate commits and pushes on your behalf — if git push wouldn't work manually, it won't work here either. Run git push manually from the repo to test.

Double-check your API key and project ID (PostHog) or site domain (Plausible). If you're using a self-hosted instance, set the baseUrl field in your config. Run with DEBUG=1 for the full error details.

Self-hosting on a VPS

For 24/7 optimization, run CROtomate on any cheap VPS:

# SSH in, install Node 18+, install CROtomate
ssh user@your-server
npm install -g crotomate

# Clone your site, set up, and run in tmux
git clone https://github.com/you/your-site.git && cd your-site
export ANTHROPIC_API_KEY=sk-ant-...
tmux new -s crotomate
crotomate init && crotomate run
# Ctrl+B then D to detach. Reattach with: tmux attach -t crotomate

Or use a systemd service for auto-restart on failure:

# /etc/systemd/system/crotomate.service
[Unit]
Description=CROtomate
After=network.target

[Service]
Type=simple
WorkingDirectory=/home/user/your-site
Environment=ANTHROPIC_API_KEY=sk-ant-...
ExecStart=/usr/bin/crotomate run
Restart=on-failure
RestartSec=30

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now crotomate

Contributing

Contributions are welcome. Found a bug? Open an issue. Please open an issue first to discuss what you'd like to change.

1. Fork the repo
2. Create a feature branch (git checkout -b feature/my-change)
3. Make sure npm run typecheck passes
4. Open a pull request

Author

Made with ❤️ in 🇸🇮 by Rok Benko.

License

MIT