RoutingCat

RoutingCat shows each visitor of your site one variant of each place you choose to vary. It learns which variants convert, and for whom, and it measures what routing adds against a control: 10% of visitors who always see your current pages. These docs are for a site whose templates Vercel or Cloudflare serves, a static site or one your own server renders; on any other host, your site takes the docs for any other website, where RoutingCat decides in the page. RoutingCat is made for founders who work with a coding agent: you say what you want, with as much or as little direction as you like, and your agent does the work.

The loop

Declare. You or your agent write each slot in your templates, its variants side by side: what your page shows today stays as the slot’s default, and the others are hidden. routingcat.config.json names the pages, and npx routingcat push stamps each variant’s version into the markup.
Deploy. Your usual deploy, on Vercel or Cloudflare. Your build runs npx routingcat build, which registers what changed: a production deploy makes it live within about 2 minutes, and new variants reach visitors no other way.
Read. npx routingcat status says what is happening: what was counted, what the model predicts with its range, and the measured gain against the control.
Act. Keep a variant, pause or retire one, or try the next idea. An act is live within about 2 minutes, without a deploy.

Routing is always on: each change is compared from the moment it goes live, and what to keep is a judgment on the evidence, yours or your agent’s. How RoutingCat works explains what happens behind each step.

What your site needs

Templates in HTML syntax. Hugo, Jekyll, Eleventy, or plain HTML pages in public/, as public/index.html beside where you run setup; a Nuxt 2 app built static with nuxt generate; or Laravel, Rails, Django, a WordPress theme or PHP, whose own server renders the pages. Every variant of a slot is written in the page, and RoutingCat shows the one each visitor gets.
A host that runs RoutingCat before your pages, so that each visitor’s variants are picked before the page is served:
- on Vercel, a root middleware.ts, for any of these stacks;
- on Cloudflare Workers or Pages, a Worker or Pages middleware in front of a static site’s files;
- on Cloudflare in front of your own server, a Worker on your domain’s route, for a site your server renders.
On Cloudflare, your account needs Workers Paid. RoutingCat sets up a Nuxt 2 app on Vercel, and any other site on the host its folder names, or the one you give setup. Run again with another host, setup moves such a site between Vercel, Cloudflare and any other host, its pages, variants and results kept.
Your host’s command line, signed in where you run setup. On Vercel, the folder is linked to a Vercel project and the Vercel CLI is signed in; each build proves itself with Vercel’s own token, so there is no secret to set. On Cloudflare, Wrangler is signed in, and Cloudflare’s builds carry a deploy key that npx routingcat keys deploy mints; a production build on your machine registers under your sign-in instead, once you confirm what goes live.
A build that runs npx routingcat build after your site’s own, as hugo --gc --minify && npx routingcat build. Setup adds the routingcat package to your package.json.
A coding agent that reads skills. Setup installs RoutingCat’s skill where Claude Code, Codex, Cursor, Gemini CLI and GitHub Copilot look for one. You can also run every command yourself.
A RoutingCat account, created at sign-in during setup. You start on Hobby, at no cost: up to 3 sites, sharing 10,000 visitors a month on routed pages and 10 live variants, with routing starting once a card is on file, nothing charged. See Plans, billing and emails.

The docs

Start here

How RoutingCat works: What happens when someone visits a routed page, how routing learns, what the measured gain is, and how sure each number is.

Get started

Set up RoutingCat: Install RoutingCat on a site whose templates Vercel or Cloudflare serves, set your build to register each deploy, choose what it counts as a conversion, deploy, and check that it works.
Try your first idea: Try new headlines on your home page, from the slot in your template to the first days of results.

Concepts

Pages, variants and versions: How to shape what can change on a page, how pages, slots, variants and versions are named, and what makes a new version.
Conversions and visits: What counts as a conversion, how RoutingCat counts in visits and windows, how a conversion finds its visit, and how far to trust each source of events.
How routing learns: How routing learns, enough to predict it: a contextual bandit with Thompson sampling, what it learns from, how it explores, how it learns for whom, and what edits and settings change.
What the numbers mean: The three kinds of number RoutingCat reports, what the measured gain is, how to read ranges, signal, labels and scorecards, when each figure updates, and what a missing value means.

Guides

Build a page: Declare a page in routingcat.config.json, write its slots in your templates’ markup, stamp them with push, and follow the rules that keep hidden variants harmless and what visitors see measurable.
Change, preview and deploy: Add, refine, remove or bring back variants in your templates, stamp them, look at one on your machine or in production, and know what each deploy makes live.
Track conversions: Report sign-ups, purchases and other conversions from your server through the HTTP events API or from a page through the browser entry, check that each reaches its visit, and record a tracking gap when tracking breaks.
Whop: Credit Whop payments and memberships to the visits that led to them by connecting your Whop company, then passing the visitor id in the checkout your server creates.
Clerk and other auth providers: Record each sign-up once, and link visitors to their accounts at every sign-in, whether your server creates the accounts or Clerk or another provider does.
PostHog: Put the visitor id and the variants on your PostHog events, take conversions your site already captures in PostHog through a destination, and know who can read the key it holds.
Read and explain results: Read status, show, sources and download, and explain each figure to a person plainly, with how sure it is and without claiming more than the evidence supports.
Change what’s live: Pause, resume, promote, retire or revert from the command, safely, and keep your code in agreement with what’s live.
Routing settings: Change how a slot or the whole site is routed, with each setting’s range and default, in code or with set.
Work with your coding agent: How you use RoutingCat through your coding agent, from one precise change to experiments it runs for you, the skill that makes it an expert, the note in AGENTS.md that points it there, and how to run it in a sandbox.
Read the dashboard: Read your site’s figures, what routing gains on each page and how each variant does on the dashboard, over 7, 28 or 90 days, all time or the days you pick, turn what you see into a request for your coding agent, and find your Settings, your plan across your sites and each site’s settings.
Plans, billing and emails: What Hobby and Pro include and cost for every site you own, the card that starts routing on Hobby, Hobby’s 3 sites and the variants it holds past its 10, what happens past Hobby’s visitors or at Pro’s cap, how you upgrade, manage and cancel in Settings, and which emails RoutingCat sends.

Reference

Config and declarations: Every option of your site’s config and of its page, slot and variant declarations, with its type, default and rules.
JavaScript API: Every function, component and script your site’s code uses from RoutingCat, with its signature and options.
The routingcat command: Every command of npx routingcat, with its arguments, options and output, and the conventions they share: JSON, writes, exit codes, addresses and values.
JSON output: What every command prints with –json: the envelope, failures, messages and warnings, the fields of each figure, cursors and the contract’s version.
HTTP events API: Send conversions and identity links from any backend: the key, the body, the limits, the answers and when to retry.
Messages: Every warning and error RoutingCat shows, by its id: how serious it is, where it shows, what it means and how to fix it.
Limits and defaults: Every limit RoutingCat holds a page, a declaration or a setting to, and every default you start with, with its unit.
Glossary: Every term the RoutingCat documentation, the command and the dashboard use, in plain words.

Privacy and security

What RoutingCat collects: What RoutingCat records about your visitors, by category, and what it never stores: its cookies and browser storage, the requests your site makes, retention, deletion and how the data is used.
Access and keys: Who can act on your site, what each key allows, where it lives and how to replace it, what a leaked key would allow, which domains may send browser events, and how the command signs in.

Operate

Run it in production: What RoutingCat adds to each page on Vercel or Cloudflare, what happens when it can’t be reached, how routed pages work with caches, and how to upgrade, pause or remove it.
Cloudflare: The Cloudflare settings that matter for a site RoutingCat runs on there, Workers Paid and what it costs, Workers Cache, Rocket Loader, Zaraz, cache rules, HTTPS and location, the deploy key Cloudflare’s builds carry, and production deployed from your machine.
Troubleshooting: Find a symptom, its cause and its fix, from a stopped init or refused markup to pages that show their defaults and conversions that don’t join, then read doctor’s checks one by one.