Skip to content

saromedia/king-cro

BranchesTags

Repository files navigation

Shopify CRO Agent

A weekly Shopify conversion rate optimisation agent powered by Claude. Runs automatically every Monday via GitHub Actions. Pulls live store data, analyses your theme code, scores findings by ICE, synthesises a report, and sends a Slack/email digest.

First time here? Follow SETUP.md — a step-by-step walkthrough designed for an AI agent (or you) to work through from zero to first report. Once running, see VERSIONING.md for how to pin to a release tag and pull upstream improvements safely.

Disclaimer

This project is an agentic AI tool — it makes real API calls, reads live store data, writes files, and can instruct a dev agent to open pull requests against your codebase.

By using this software you accept that:

  • All AI-generated analysis, recommendations, and code is provided for informational purposes only. You are responsible for reviewing all outputs before acting on them.
  • The authors accept no liability for decisions made based on agent output, including but not limited to: changes to your Shopify store, revenue impact, data exposure, or any other consequence of using this software.
  • This software accesses your Shopify store data via API credentials you provide. You are responsible for securing those credentials and understanding what scopes you grant.
  • No code generated by the dev agent should be merged or deployed without human review.
  • This software is provided "as is" under the MIT License. See LICENSE.

This is experimental software. Use it with the same caution you would apply to any automated system that touches a production environment.

Guardrails

The agents in this system are read-only by design. See GUARDRAILS.md for the full breakdown. Short version:

  • The CRO agent reads your store data and writes report files. It cannot push code or modify your theme.
  • The dev agent writes Liquid files but has no git access. Branch creation, commits, and PRs are explicit workflow steps — not agent actions.
  • PRs require human review before merge. Merging does not deploy to your live store.
  • Enabling an experiment requires a second manual step: toggling a setting in the Shopify theme editor.

How it works

  1. GitHub Actions triggers every Monday at 8 AM AEST
  2. Agent reads knowledge/ — your hypotheses, playbook, and history of past findings
  3. Pulls live Liquid theme files from Shopify via CLI (shopify theme pull)
  4. Fetches orders, abandoned checkouts, and product data from Shopify Admin API
  5. Fetches sessions and conversion rate from Shopify GraphQL Analytics API
  6. Scores all findings using ICE framework
  7. Calls Claude API to synthesise a structured report
  8. Commits the report to reports/DD-MM-YYYY.md and updates knowledge/history.md
  9. Sends Slack message and/or email digest

Setup

1. Clone and install

git clone https://github.com/YOUR_USERNAME/shopify-cro-agent.git
cd shopify-cro-agent

Install uv if you don't have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then install dependencies:

uv sync

2. Configure environment

cp .env.example .env

Open .env and fill in:

Key Where to find it
SHOPIFY_SHOP_URL Your .myshopify.com domain
SHOPIFY_ACCESS_TOKEN Shopify Admin → Apps → Develop apps → Create app → Admin API
THEME_DIR Local path to your downloaded theme (via shopify theme pull)
ANTHROPIC_API_KEY console.anthropic.com
SLACK_WEBHOOK_URL Slack → Apps → Incoming Webhooks
SMTP keys Your email provider's SMTP settings

Shopify API scopes required (set when creating your custom app):

Scope Why the agent needs it
read_orders AOV, revenue, refund rate, repeat customer rate, discount usage
read_checkouts Abandoned checkout count for cart abandonment rate
read_products Flag thin descriptions, few images, out-of-stock variants
read_customers Identify repeat customers for retention metrics
read_analytics Sessions + CVR via GraphQL — powers the core conversion metrics
read_themes Only needed for GitHub Actions to auto-pull theme files via Shopify CLI

Only grant READ scopes. The agent is strictly read-only. Do not enable any write_* scope — it creates unnecessary risk for zero benefit. See .env.example for the full setup walkthrough.

Finding your theme ID: Shopify Admin → Online Store → Themes → ⋯ (Actions) → Edit code. The number in the URL is your theme ID.

3. Test locally

Dry run (no API calls, no notifications):

uv run python scripts/run_agent.py --weekly --dry-run

Full local run:

uv run python scripts/run_agent.py --weekly

GitHub Actions setup

Add secrets

Go to your repo → Settings → Secrets and variables → Actions → New repository secret

Add one secret for each key in .env.example:

  • SHOPIFY_SHOP_URL
  • SHOPIFY_ACCESS_TOKEN
  • SHOPIFY_API_VERSION
  • SHOPIFY_THEME_ID
  • SHOPIFY_THEME_REPO — e.g. your-org/shopify-theme
  • THEME_REPO_PAT — GitHub PAT with repo scope on your theme repo (for dev agent PRs)
  • ANTHROPIC_API_KEY
  • SLACK_WEBHOOK_URL
  • SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, NOTIFY_EMAIL

Note: THEME_REPO_PAT is only needed if you use the dev agent (implement-experiment workflow). The weekly CRO scan does not require it.

Enable Actions write permissions

Go to Settings → Actions → General → Workflow permissions Select Read and write permissions so the agent can commit reports back to the repo.

Trigger manually

Go to Actions → Weekly CRO Scan → Run workflow to test before the first Monday.

Using this with Claude Code

Open this repo in Claude Code for ad-hoc analysis:

cd shopify-cro-agent
claude

Claude Code will automatically read CLAUDE.md. Then prompt naturally:

Focus on cart drop-off. Read the knowledge base and dig into the API data
and theme files for anything relevant to checkout friction.

I've added three new hypotheses to hypotheses.md. Re-run analysis focused
on those areas. Update playbook.md if you find signals worth tracking permanently.

Read history.md. Which findings have appeared more than twice and are still
marked Ongoing? What's getting stuck?

Maintaining the knowledge base

File Who updates it When
knowledge/hypotheses.md You Whenever you have a new hunch
knowledge/playbook.md You or the agent When new signals worth tracking are discovered
knowledge/history.md Agent (auto) After every run — you add "Actioned" notes manually
reports/ Agent (auto) Each Monday

Strategy intelligence

The agent tracks win rates by experiment type and surfaces strategic observations in every report. After a few experiments complete, you'll see output like:

Strategy pulse: social_proof experiments have a 3/3 win rate (100%) but only 2 are currently active out of 11 suggested. This is your highest-ROI underutilised strategy. Meanwhile visual has 6 experiments suggested and 1/3 winners (33%) — consider pausing the backlog and running social_proof experiments first.

The agent is deliberately opinionated here. The data is in knowledge/insights.md.

Test isolation and multivariate guidance

Every experiment suggestion includes a zone (which part of the page it affects) and a test mode (solo / concurrent / sequential).

  • Solo: run this alone — it shares a zone with another active test
  • Concurrent: safe to run alongside other active experiments in different zones
  • Sequential: run only after a specific preceding experiment concludes

The agent also checks your current session volume and flags if a proposed multivariate test is underpowered. Full methodology is in knowledge/playbook.md.

Agentic experiment implementation

Once the CRO agent identifies an experiment worth implementing, you can spawn a dev agent to write the Liquid code and open a PR — without writing a line of code yourself.

Disclaimer

This project is an agentic AI tool — it makes real API calls, reads live store data, writes files, and can instruct a dev agent to open pull requests against your codebase.

By using this software you accept that:

  • All AI-generated analysis, recommendations, and code is provided for informational purposes only. You are responsible for reviewing all outputs before acting on them.
  • The authors accept no liability for decisions made based on agent output, including but not limited to: changes to your Shopify store, revenue impact, data exposure, or any other consequence of using this software.
  • This software accesses your Shopify store data via API credentials you provide. You are responsible for securing those credentials and understanding what scopes you grant.
  • No code generated by the dev agent should be merged or deployed without human review.
  • This software is provided "as is" under the MIT License. See LICENSE.

This is experimental software. Use it with the same caution you would apply to any automated system that touches a production environment.

Guardrails

The agents in this system are read-only by design. See GUARDRAILS.md for the full breakdown. Short version:

  • The CRO agent reads your store data and writes report files. It cannot push code or modify your theme.
  • The dev agent writes Liquid files but has no git access. Branch creation, commits, and PRs are explicit workflow steps — not agent actions.
  • PRs require human review before merge. Merging does not deploy to your live store.
  • Enabling an experiment requires a second manual step: toggling a setting in the Shopify theme editor.

How it works

  1. CRO agent (or you) writes a handoff spec to dev-agent/handoffs/DD-MM-YYYY-[id].md using the template in dev-agent/handoff-template.md
  2. Go to Actions → Implement Experiment (Dev Agent) → Run workflow
  3. Enter the handoff filename
  4. The dev agent pulls the live theme, reads the spec, writes the code change (gated behind a theme schema toggle), and opens a PR
  5. You review the PR — nothing is deployed until you merge

The human gate is the PR. The dev agent cannot merge, cannot deploy, cannot change live theme settings. It can only write code and open a pull request.

Running the dev agent locally

# Write your handoff spec first
cp dev-agent/handoff-template.md dev-agent/handoffs/16-04-2026-pdp-17.md
# Edit it with the experiment details

# Then run Claude Code scoped to the dev agent
cd shopify-cro-agent
claude --dangerously-skip-permissions \
  -p "Read dev-agent/CLAUDE.md for your instructions. Then read dev-agent/handoffs/16-04-2026-pdp-17.md and implement it."

File structure

shopify-cro-agent/
├── CLAUDE.md                    # Agent identity — read automatically by Claude Code
├── pyproject.toml               # Dependencies (uv)
├── .env.example                 # Environment variable template
├── .gitignore
├── knowledge/
│   ├── hypotheses.md            # Your CRO theories
│   ├── playbook.md              # Methodology and benchmarks
│   ├── history.md               # Auto-updated findings log
│   └── insights.md              # Strategy pattern analysis and win rates
├── reports/
│   └── DD-MM-YYYY.md            # Weekly reports (committed by agent)
├── scripts/
│   ├── run_agent.py             # Master orchestrator
│   ├── fetch_shopify.py         # Shopify Admin API fetcher
│   ├── analyse_theme.py         # Liquid theme CRO checker
│   ├── score.py                 # ICE scoring
│   └── notify.py                # Slack + email notifications
├── dev-agent/
│   ├── CLAUDE.md                    # Dev agent identity — read by Claude Code
│   ├── handoff-template.md          # Template for CRO→dev handoff specs
│   └── handoffs/                    # Specs written by CRO agent, read by dev agent
└── .github/
    └── workflows/
        ├── weekly-scan.yml      # GitHub Actions — weekly CRO scan
        └── implement-experiment.yml # GitHub Actions — dev agent PR workflow

About

Shopify Conversion Rate Optimisation (CRO) Agent

Topics

shopify conversion-rate-optimization conversion-rate agentic-ai conversion-optimization agentic-skills

Resources

Readme

License

MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v0.1.0 — initial tagged release Latest
May 13, 2026

Packages

 
 
 

Contributors

Languages