RoutingCat User Guide

A page that sells is a stack of decisions. Open Spellhome’s product page on a phone and count them: which photo comes first, whether one candle is selected or two, that a candle costs $51 and not $57, that the old price is struck through, that shipping is $9 on one candle and free on two, that the cart suggests nothing more.

Each was a reasonable call, and none was checked. A pricing page has the same stack: the plan shown first, monthly or yearly by default, the headline, the proof under it. Checking one of these properly ties up the page for weeks, so most sites check a few a year and guess the rest.

The arithmetic is short: visits, times what a visit is worth. Spellhome’s page takes 100,000 visits a month. Three visitors in a hundred buy, and an order leaves $56 after the candles and the shipping, so a visit is worth $1.68.

At that traffic, one more cent per visit is $1,000 a month, and all of it is kept, because the ad bill does not move when the page gets better. If the right offer is worth 20 cents a visit more than the one on the page, the guess costs $20,000 a month, and no dashboard says so.

RoutingCat replaces the guess with a system. It has four words, and you will meet them in every chapter:

• A page is a page of your site that RoutingCat routes: the product page, the pricing page, the home page.
• A slot is a place on that page that can change: the headline, the first photo, the price list, the order of the sections, or the whole page.
• A variant is one alternative for a slot. Anything your code can render can be one.
• The default is the variant you have today. Every slot keeps one, and it is what the page falls back to.

You declare slots and variants in your own code, with your coding agent, and they go live with your normal deploy.

From then on, RoutingCat picks each visitor’s variants before the page shows:

• Every variant stays live. There is no test to start, stop or schedule.
• Each visitor gets the version most likely to earn the most. A model estimates what each variant is worth from the conversions so far, and each variant gets visits in proportion to its chance of being the best. A weak variant loses its visitors on its own. An uncertain one keeps being tried.
• A visitor keeps what they saw: the same variants for their whole visit, seven days by default.
• One visitor in ten keeps today’s page. This control is chosen at random, and always sees the defaults.

Because the control is random, the difference between it and everyone else is a measurement, not an estimate. RoutingCat calls it the measured gain. It is the number you can repeat to a partner or a board.

The machine learning stays in the background. You never choose a sample size, a stopping rule or a significance level. Your part is the part that needs judgment:

1. Say what a conversion is, and what it is worth to you: an order’s profit, a plan’s lifetime value. You do it once (chapter 4).
2. Decide what to try. Your agent builds it.
3. Read what came back, with how sure it is.
4. Retire what lost, keep what works, and try the next idea.

Any page where visitors decide: a product page, a pricing page, the landing page your ads point to, a sign-up page, a home page. RoutingCat needs a conversion it can count, such as a purchase, a sign-up or a booked demo, and enough of them to learn from. Chapter 6 says how many.

This site’s own home page runs it: its main button, its install box, the layout of its pricing and the order of its sections are all slots.

Read more: How RoutingCat works · Pages, variants and versions

If you have run A/B tests, RoutingCat can sound like a better testing tool. It is a different way to work, and the difference shows at every step of an idea’s life.

A test is a small project. Someone builds the alternative in a visual editor, or waits for a developer. Someone works out how many visitors it needs, launches it, watches it, and decides when to stop. If it wins, someone rebuilds it properly in the site’s code. That cost is why most teams run a handful of tests a year, and why they keep them safe.

With RoutingCat, a variant is a few lines in your repository, written by your coding agent. It goes live with your next deploy and joins the variants already there. Nothing has to be watched, because a variant that does worse loses its visitors on its own. Nothing has to be called, because there is no end date.

This matters more than any statistic. Most ideas do not win, whoever has them. What separates a page that keeps improving from one that does not is how many ideas reach visitors, and how bold they are. When trying one costs a sentence and a mistake corrects itself, you try many more.

A visual editor changes what it can reach on the finished page: a headline, a colour, a button. Past that you need a developer, and the test waits.

A RoutingCat variant is code in your own site, so it can be anything your site can do: another price list, another checkout step, a reordered page, a whole new page. Your agent works out how to build it on your stack, and you review it like any other change. On Vercel and Cloudflare it is rendered by your own server, so the page arrives already in its variant, with no flicker. Chapter 5 shows the shapes a variant takes.

A test splits visitors evenly and holds that split until it ends. By design, the worst variant keeps its full share the whole time. Routing starts the same way, then moves visitors toward what is working.

At Spellhome, routing had three visitors in four on the best of three offers by week four, and had earned about three times what the even split had. To be fair to the test: stopped at the right moment, with the best offer then shown to everyone, it nearly catches up by week eight. But someone had to pick that moment, and routing was earning from the second week.

A test needs the page to itself, so questions wait in line. Seven questions at four weeks each is more than half a year. Slots do not wait: every slot of a page learns from the same visits, at the same time.

Chapter 6 covers how many slots a page can carry.

A test ends with one answer for everyone. But visitors differ, and a variant that is average overall can be the best by far for some of them. At Spellhome, an offer built around the full set of four candles was unremarkable across all visitors, +12% [−5, +30], and the strongest offer the store had for homeowners, a quarter of its traffic. A test on everyone would have dropped it.

Routing can learn a leader for each kind of visitor, so its ceiling is higher by construction: the best version for each audience is worth at least as much as the best single version. Chapters 8 and 9 show how.

A fixed split gives the plainest comparison between two versions, and each visitor keeps the same one on every visit. RoutingCat has it built in: give a slot a fixed share of 100% and it is a classic A/B test. Use it for a single question where you want the cleanest read, or where a visitor must keep what they were shown for weeks. Chapter 7 says when that matters for a price.

• Routing does not create evidence. A small difference still takes many conversions to see. What changes is that you do not have to wait for certainty before you benefit.
• The gain is still measured the classic way. One visitor in ten stays on your defaults, at random. That comparison is a randomized experiment, and it never stops running.

Read more: How routing learns · Routing settings

RoutingCat is a developer package. You could write every line of it by hand, and the docs say how. Most people never do: they install it, and from then on their coding agent does the RoutingCat part.

A handful of small edits, all visible in git diff:

• The proxy is where each visitor’s variants are picked: on your own server, before the page renders.
• The config names your site, and soon what counts as a conversion (chapter 4).
• The skill is what makes your agent an expert. It teaches it how to declare a variant on your stack, how to read every number, and what to retire or try next. It works with Claude Code, Codex, Cursor, Gemini CLI and GitHub Copilot.

People work with coding agents in different ways, and each of them works here.

Some say exactly what they want.

Some talk it through first. They describe a problem, such as “six orders in ten are a single candle, and that is our thinnest order”, and ask what could change it. The agent reads the page and the prices, proposes a few ideas with its reasons, says which ones need a decision from you, such as a price, and builds the ones you choose.

Some hand over the routine. Once a week they ask for a review, or schedule one where their agent can run on a schedule: what changed, what to retire, what to try next. The agent reads the results, acts within what it is allowed to do, and reports what it did and why.

Whichever way you work, the result is the same few lines in your repository, declaring a slot and its variants. That is why each chapter keeps the code at hand, folded under “In your code”, with one example of how you might ask for it. Your own words will do as well: the skill gives your agent RoutingCat’s vocabulary, so you do not need it.

• A new variant goes live only through your own deploy, so it gets the same review as any other change. Before it, npx routingcat plan lists exactly what the deploy will put in front of visitors.
• You can look first. In development, adding ?rc=lead:pair to the page’s address shows that variant.
• A preview deploy changes nothing live.
• Stopping is faster than shipping. Pausing or retiring a variant takes effect within about two minutes, with no deploy (chapter 11).

Your repository’s agent instructions (AGENTS.md, or CLAUDE.md) say what your agent may do without asking. The line most teams draw: it reads results freely, and you approve anything that changes what visitors see.

Your agent is not limited to RoutingCat’s numbers. Put last month’s ad sets, exported from Ads Manager, in the repository, and it will read them. If it can already query your orders in Stripe or your events in PostHog, it will use those too. None of them has to be connected to RoutingCat.

Read more: Set up RoutingCat · Work with your coding agent

Routing learns to get more of something. Setup is where you say what: first which event is the conversion, then what one is worth.

The objective is the conversion routing optimizes: a purchase, a sign-up, a booked demo, a trial started. A conversion counts when it happens within a window after the visitor first saw the page, 24 hours by default.

Outcomes are the other events you want to see beside it, such as a click on “Talk to us” or a newsletter sign-up. They are counted and reported for every variant, and never steer routing. The site has one objective, and a page can have its own.

Left alone, every conversion counts the same. On a page whose variants can change what is bought, that is the wrong target. An order for four candles is worth twice an order for one. An annual plan is worth more than a monthly one. An order won with free shipping is worth less than the same order without it.

So you give the objective a value: your own definition of what a conversion leaves you. Routing then optimizes value per visit, written VPV: how many visitors convert, times what a conversion is worth.

A value can be whatever your business counts in:

• A store’s profit. What the customer paid, less what the goods and the shipping cost you. With real margins per product if you have them, an average margin if you do not.
• Revenue, where margins are even: the amount of the order.
• A plan’s lifetime value. A $19 monthly plan at an 80% gross margin, whose customers leave at 5% a month, is worth about $19 × 0.8 ÷ 0.05 = $304. If 40% of its trials pay, a trial is worth about $122.
• What a lead is worth. A fixed number for a booked demo, or a figure your own code computes for each one.

• Your own server, with routingcat.track, as above. Each event carries an id, so one counted twice by a payment provider counts once.
• A payment connection. npx routingcat connect stripe credits Stripe’s payments to the visits that led to them, with no webhook code. Whop connects the same way.
• Any other backend, over HTTP.
• Across devices. routingcat.identify(user.id), called where an account is created and at each sign-in, links a person’s devices, so a purchase on a laptop still counts for the visit that started on a phone.

Results read in your own unit, and every difference splits in two:

That last line says where a difference comes from: more buyers, or bigger baskets. Here it is mostly bigger baskets.

• Give a value where variants can change what is bought: products, prices, plans, offers. Where they can only change how many visitors convert, as most headlines do, a plain objective learns faster.
• It is yours. RoutingCat takes the number you define, and never needs your cost sheet.
• An amount counts only from your server or a payment connection. A browser can report that a sale happened, never what it was worth.
• Leave out the ad spend. That money is gone before the page acts, whichever variant shows.
• Set a cap. No single visit counts for more than $300 at Spellhome, so one wholesale order cannot steer the page.
• Give it early. The measured gain in your unit starts from the deploy that declares the value. Changing the values later keeps what routing learned. Changing the events or the window starts the page’s learning again.

Read more: Optimize for what a visit is worth · Track conversions · Stripe · PostHog

A slot is a place on a page that can change, and a variant is one alternative for it. Because variants are written in your own code, there is no list of what they can be. If your site can render it, it can be a variant.

A few of these, as they look on a real page:

This site’s own home page tries the order of its sections, and its pricing in two layouts, each a component. Spellhome tries its long story page against a short one that opens on the dinner scene: one slot, whose two variants are whole pages.

How you change a variant decides what it is compared with:

• A fix or a polish keeps its key. The edit makes a new version, @v2, which builds on what the variant already showed. It is compared with the version it replaced.
• A new idea takes a new key. It goes live beside the others and is compared with the slot’s default, at the same time and on the same traffic. That is the fair comparison.
• A refinement can run beside its original, under a new key that names its parent. It starts from part of what its parent showed.

Every version of every variant is kept, with its results and the commit that made it. Your agent starts each session knowing what was tried and what it did.

• In development, add ?rc=photo:lifestyle to the page’s address to see that variant. ?rc=off returns to the defaults.
• In production, npx routingcat preview pdp/photo:lifestyle prints a signed link, valid for one hour, that shows the variant without counting in your results.

• A new variant starts on a small share. It begins from what the slot’s other variants taught routing, never from a guess that it is better, and earns more visits with evidence of its own.
• Keep what you try inside the variant. A change to a shared stylesheet, or to content fetched when the page renders, makes no version, so nothing is compared.
• Variants are public copy on a live business. Facts, numbers, prices and guarantees must be true and yours. Your agent reuses what your site already says, and asks you for anything new.
• Deleting a variant from your code retires it at the next deploy, and keeps its history.

Read more: Build a page · Ship changes · Pages, variants and versions

A test runs alone. Slots do not have to. A page can carry several, each with its own variants, and every visit teaches all of them at once. Nothing is split between them: a visitor gets one variant in each slot, and the model works out what each contributed.

• Asking several questions in the same month. The first photo, the price list, how the saving is shown, what the cart suggests: Spellhome ran six slots on one page.
• Finding out what matters. You rarely know in advance which part of a page moves the result. Nobody at Spellhome had ranked the photo first, and it made the largest single difference: the candle lit in a living room, in place of the jar on white, +28% [+18, +37].
• Keeping ideas moving. A new slot does not wait for another to finish, and adding a variant to one slot does not restart the others.

Routing judges each slot’s variants on their own effect. It does not learn that one headline only works beside one photo. Two things follow:

• Every combination must make sense, because a visitor can get any of them: any photo with any price list.
• Pieces that must match go in one slot, as parts of one variant: a headline and its subhead, a price and the line that explains it.

Evidence comes from conversions, not from visits. At a 3% conversion rate:

So try ideas, not wordings. A different photo, a different bundle, a different promise. Not two ways to say “free shipping”. As a guide, tens of conversions a week support one or two bold alternatives in a single slot. Hundreds a week support three to five per slot, in several slots.

When several variants are still inside each other’s ranges after months, that is an answer too: the choice does not matter much. At Spellhome, three ways of showing the saving never separated. Keep one, and spend the slot on a bolder idea.

• A losing variant costs little while it is live. Routing has usually cut it to a few percent of visits before you look. Retiring it is housekeeping: it frees room for a new idea.
• A static page is built once per combination. Three slots of four variants make 64 pages. RoutingCat warns past 100 combinations and refuses past 1,000. A page rendered on the server has no such limit.
• The plan sets how many variants can be live: 10 across your sites on Hobby, the defaults not counted, and 100 a page on Pro.

Read more: Pages, variants and versions · Limits

The offer is where a page that sells makes or loses the most money, and where operators guess the most: what it costs, what is bundled, which option is already selected, how the saving is shown, what comes free. Each of these can be a slot.

A few of the questions an offer raises, each one a slot with two to four variants:

• Which offer leads. One item selected when the page loads, or the bundle. The plan highlighted on a pricing page. Monthly or yearly shown first.
• The price list itself. A dearer single item that makes the bundle look better, shipping folded into the price, “buy 2, get 1 free”.
• How the saving is shown. In dollars, in percent, as a price per item, or not at all.
• What comes with it. A free gift, a guarantee, a shipping threshold, a trial length.
• What the cart suggests. An upgrade to the larger bundle, or an add-on.

Opening the page on the pair instead of one candle was worth +16% [+5, +28] at Spellhome, with no change to any price. The set, opened the same way, sold about a quarter fewer orders and came out behind.

A generous offer nearly always wins more orders. The question is whether it earns more. That is why offers are judged on value per visit, which chapter 4 sets up: how many visitors buy, times what an order leaves you.

A tool that counts orders would have kept one of those two. “Buy 2, get 1 free” went on to lose clearly, −12% [−23, −2], and was retired. The dearer single candle ended at +7% [+1, +14]: some buyers who would have taken one candle took the pair, and it cost no orders that anyone could see. The single candle’s job, it turned out, was to sell the pair.

A price is a trade-off in its plainest form: a higher one sells fewer and earns more on each. Value per visit weighs both sides in one figure, so once a page has a value, a price is a variant like any other. The prices you want to try go live together, visitors move toward the one that earns the most, and a price that loses money loses its visitors without anyone watching it.

That matters more for prices than for anything else on a page, because there are so many candidates: the price point, the bundle, what one item costs beside the bundle, shipping in or out, the threshold for a gift. Tested one pair at a time, each losing price holds half your visitors until someone calls the test, and the list takes a year. Routed, you put in the candidates you believe in and read the page once a week. Spellhome’s four price lists above ran exactly that way.

The same works on a pricing page:

Three things make a routed price sound:

• A value that counts what the price changes. For a store, profit, so that a discount or free shipping shows as what it costs. For a subscription, each price at its own lifetime value, worked out as in chapter 4: $304 for the $19 plan, $384 at $24 and $464 at $29, if customers stay as long at each price. If the dearer plan loses them sooner, its figure should say so.
• Personalization off, so that the slot finds one price for all visitors. The next section says why.
• A checkout that charges what the page showed. Carry the price in the variant, as the Stripe price id above, and let the checkout read it from there.

Never route a price on a page that only counts conversions. The cheapest price converts best, so routing would drift to it. Give the page a value first.

Left on, a slot learns for whom from the visit itself: the device, the hour, a first or a repeat visit. On a price, that is the wrong thing to learn. A price that follows a visitor’s phone or the time of day is one you could not explain to a customer, and in some places it carries legal weight. RoutingCat recommends against it. So a price slot runs with personalization off: routing still finds the price that earns the most, and it is the same for everyone.

What you can do is decide. A price meant for the visitors of one campaign or one source is ordinary commerce: an introductory price for the people a launch campaign brings, a lower first order for the visitors a partner sends, a price list for one country. That is a rule, only on the price (chapter 9), and rules hold with personalization off:

Visitors from those ad sets are then routed between that price and the others, on profit, and nobody else ever sees it. Its results read “for this audience”: whether first-dog owners are worth more to Spellhome at $84 or at $94.

One limit: a price that an ad has promised is not a variant. Every visitor from that ad must get it, and routing would send some of them to the other prices, and one in ten to the control. Honor a promised price in the site itself, with a coupon or a page of its own. Route a price while it is still a question.

A slot can also take a fixed share. At 100% it is a classic A/B test: its visitors are split evenly, each keeps the same price on every visit, and the slot gets a measured comparison of its own.

It is one setting: fixedShare: 1 in code, or npx routingcat set pricing/pro fixed_share=100% on a live slot, without a deploy.

Choose it when:

• A visitor must keep their price for weeks. Under routing, a visitor keeps the same price for the whole visit, seven days by default, and a later visit can show another. Where people come back many times before they buy, as a team does on a pricing page, a fixed split holds each of them to one price for as long as it runs.
• You want the plainest read on two prices, for a decision you will make once and announce. An even split gives both the same number of visitors. Routing leaves the trailing price with few, so its own figure stays less precise.
• The page has no value. With an even split, you can weigh orders against revenue yourself.

It costs what every test costs: the weaker price keeps half your visitors until you end it.

Removing the anchor was the worst idea Spellhome tried: −25% [−39, −12], retired after four weeks. The three other ways of showing the saving never separated.

A free wick trimmer with two candles or more did not pay for itself either. Each order with it was worth less, which was certain, since the gift cost $3. Nothing showed it winning more orders: −5% [−12, +2]. Offered in the cart for $12 instead, the same trimmer made each order worth about 4% more.

• Show a price on one page. Pages are routed independently, so the same price shown on two pages could differ between them.
• Count what an offer costs you. A gift, free shipping or a discount belongs in the value of the order, or it will look better than it is.
• Where the browser picks the variant, as with the script integration, a determined visitor could pick the lower price, while most browse normally. Your agent says so before it builds one.

Read more: Optimize for what a visit is worth · Routing settings

One best version for everyone is the first thing routing finds. It is rarely the whole answer, because visitors are not alike. Someone on a phone, back for the third time, is not someone on a laptop who just clicked an ad. Personalization is routing learning the difference, slot by slot.

RoutingCat describes each visit along a few dimensions, each with a short list of levels:

It personalizes on the context of a visit, never on who the visitor is.

A slot learns for whom by default, over the first five of those dimensions, with nothing to set up. Routing personalizes only where the evidence earns it, so most of the time you will simply find that:

• A shorter first screen leads on phones, while the long one keeps desktop.
• A first visit and a repeat visit want different things: proof and reviews for one, the fastest way to reorder for the other.
• Search visitors arrive with a question, social visitors were interrupted. The same headline rarely serves both.
• Evenings and weekends browse, weekday lunches buy. An offer with a deadline can lead at one time and trail at another.

None of these is a setting. They are what a slot finds on its own, and what the results show you by dimension.

The dimensions that matter most are usually yours. You already sort visitors when you buy traffic: by campaign, by ad set, by the page an ad points to. A dimension of your own turns that into a few levels a slot can learn from. It reads one field of the visit’s arrival:

• A campaign tag. Ad sets named by who they reach, a spring sale against a brand campaign, a creative against another.
• The landing path. Visitors who arrived on /gifts against those who arrived on a product.
• The referrer. A partner’s site, a newsletter, a review that sent you traffic.
• The country.

Spellhome names its ad sets by who they reach, dog_…, home_…, gift_…, and puts that name on every ad’s link. Meta fills it in with utm_content={{adset.name}}, and the same tag goes on Google’s ad groups, so both networks fold into the same three audiences.

dimensions turns raw ad set names into a handful of audiences: ad sets come and go, the audiences stay. personalizeBy adds a dimension of yours, or the ad network, to what a slot learns from.

Results break down by any dimension. Spellhome’s offers, by audience:

Each audience has its own leader. First-dog owners are shown the starter offer two times in three, where it is predicted at +29%. Homeowners get the full collection half the time, at +46%. Gift buyers get the gift offer nearly three times in four, at +67%.

Now look at the collection across all visitors: +12% [−5, +30], behind three other offers. Judged on everyone, it would have been dropped. It is the best offer Spellhome has for a quarter of its traffic.

• Each level needs its own evidence. Every level splits the conversions. Three or four audiences on 100,000 visits a month learn in weeks. Forty ad sets as forty audiences would learn nothing. A slot takes at most four dimensions in personalizeBy.
• Comparisons stay fair without you. Ad sets convert at very different rates. A variant that goes live during a strong campaign’s burst is compared among comparable visits, and is not credited with that campaign’s buyers.
• You can turn it off. With personalization off, a slot finds one answer for everyone. It is the right setting for a price (chapter 7).
• Tag your Meta ads as paid. Meta marks unpaid clicks too, so a visit counts as meta only from a link with a source and a paid medium, as utm_source=facebook&utm_medium=paid_social.
• Learning is not deciding. When you already know who a variant is for, or must guarantee it, the next chapter has the tools.

Read more: Show a variant only to some visitors · Routing settings

The last chapter let routing find out who prefers what. Sometimes you already know, or you have to decide. A version made for one audience should not show to another. A promise made in one ad should not greet visitors who never saw it. RoutingCat has two tools for this, and they are easy to confuse.

A condition says where a variant may show. only names the visitors it is for. never names the visitors it must not reach. A visitor it excludes is routed among the slot’s other variants, as if this one did not exist.

What it is for:

• A version made for one audience. Spellhome’s candles are sold to dog owners, and some of its ad sets reach cat owners. For them, a first photo with a cat in it, shown only to visitors from those ad sets.
• A promise an ad made. The hero that says “50% off”, only for the campaign whose ad promised it.
• Something that breaks somewhere. The sticky “Add to cart” bar, never on desktop.
• An offer that is not for everyone. The first-order discount, never on a repeat visit.
• A claim with a boundary. A delivery promise, only for visitors from the countries it covers. A compliance badge, only for the campaign aimed at larger companies.

Here avatar is the dimension of chapter 8, with one more level for the cat ad sets: cat: 'cat_*'.

never is written the same way, as never: { visit: 'repeat' } or never: { device: 'desktop' }. A condition can name several levels, combine dimensions, and be named once as an audience to reuse wherever a condition goes:

On a variant that is already live, a condition can be set without a deploy, within about two minutes: npx routingcat set pdp/photo:cat --only avatar=cat.

An expectation is where you believe a variant does better. From its first visitors, routing shows it more there and less elsewhere. Then the evidence corrects the belief, whichever way it goes.

Spellhome wrote three offers, each for one of its audiences, and said so:

All three beliefs held: each offer leads with the audience it was written for. Had one been wrong, routing would have found out. A right expectation saves some early exploring, and a wrong one is overturned as conversions come in.

Ask one question: must it hold, or do I believe it?

Use a rule only for what must hold. A rule is never tested: an offer shown only to gift buyers will never show whether homeowners wanted it too.

status prints each variant’s conditions under its line. A variant with a condition is judged on the visits it may show to, against the default on those same visits, so its figures mean “for this audience”. The measured gain includes your rules, since the control still sees the defaults.

• The default takes no condition. It shows wherever no other variant may, and to the control.
• A visitor keeps what they saw. A condition is checked when a visit starts, so a new one reaches the visits that begin after it. To stop a variant at once, pause it (chapter 11).
• Read the levels exactly. A tablet is other. So only: { device: 'mobile' } leaves tablets out, and never: { device: 'desktop' } keeps them.
• A rule can exclude everyone: a typo in a tag, a campaign that ended. plan refuses a condition no visitor could match, and status warns when no visit of the last 28 days did. A variant made for a campaign outlives it: retire it when the campaign ends.
• On a price, a rule is a decision. A price shown only to one campaign’s visitors is ordinary commerce. A price by device or by hour is one you could not explain to a customer. Chapter 7 says where the line is.
• Every deployment of your site must run RoutingCat 1.1. Until they all do, a variant with a condition is held back and shown to no one, so a rule never shows outside its condition.

Read more: Show a variant only to some visitors · Config and declarations

Every number RoutingCat shows says what kind it is. Once you know the three kinds, every screen reads the same way, in the terminal and in the dashboard.

• Counted is what happened: visits, conversions, revenue, the share of visits each variant was served. It is exact. It is not a fair comparison between variants, because routing showed each one to different visitors at different times.
• Predicted is the model’s belief about each variant, with a range: +17% [+2, +31]. It moves as conversions arrive, and early extremes shrink.
• Measured comes from the random control, without the model. It is the only number that counts as a gain.

That is Spellhome’s first slot, two weeks after it went live. Line by line:

• gain is the measured gain: routed visits against the control, in your own unit, with its range.
• Each variant has a label, what a visit that sees it is predicted to be worth, its difference from the default with a range, and the share of visits it is served.
• favored means routing shows it most. learning means routing has evidence of its own for it, and prior that it does not yet. None of them is a verdict.
• The last line under a variant splits its difference in two: how many visitors convert, and what a conversion is worth (chapter 4).

The full output also gives each variant a signal from 0 to 100, which says how much evidence is behind its prediction. It is not a chance of being the best.

Every prediction and every gain comes with a 95% range: where the evidence puts the true figure. Three habits follow:

• A range that spans zero means the direction is not known yet. −6% [−21, +10] is not “6% worse”. It is “too early to call”.
• Compare variants by their predicted difference from the default, never by their counted rates.
• Decide from the predictions, which settle sooner, and report the measured gain, which settles last.

Routing does not wait for any of this. At Spellhome the pair already had more than half the visits at two weeks, because it was already the likeliest to be the best.

One visitor in ten never leaves your defaults. The measured gain is the difference between everyone else and them.

Read it from the top:

• gain is what routing added over showing everyone the defaults: $126,162, and the evidence puts it between $94,503 and $157,821.
• Most of it is order value. Routed visitors buy a little more often, 3.3% against 3.1%. What changed is what they buy: $67 an order against $56.
• It is measured, not modeled. Those 27,853 control visits are the reason you can repeat the number to a partner or a board.

• The gain is recomputed every day, and it is not a finish line. Acting on its first good day overstates it. Read it weekly.
• It settles slowly. Its precision depends on the size of the control. At a 3% conversion rate, confirming a 20% gain takes about 150,000 visits to the page. On a small site it can read “too early to tell” for months, while the predictions already guide your decisions.
• It includes the cost of trying things. Weak variants and cautious new ones pull it down, so it is what you actually kept.
• Pages' gains do not add up, since one visitor sees several pages.
• The dashboard shows the same figures as the command, and states no verdict either.

Read more: What the numbers mean · Read and explain results · The dashboard

A new variant reaches visitors through a deploy. What you do to it afterwards does not need one. An act changes what visitors see within about two minutes.

• Pause, when something is wrong with a variant and not with its idea: a broken image, a typo in a price, a claim to check. It is off in two minutes, and resume brings it back. A pause holds through every deploy.
• Retire, when a variant has clearly lost. Spellhome retired the version of its offer with no saving shown, at −25% [−39, −12]. It stops for good, keeps its history, and frees room for a new idea.
• Promote, when a variant clearly leads for everyone. It becomes its slot’s default: the control sees it from then on, and new ideas are compared with it. The gain measured so far is kept, and measurement goes on against the new defaults.
• Revert, when a change made the page worse and you want it as it was. The page returns to what it served before its last change.

Two more, for the whole site or for one audience: set routing=off makes every page serve its defaults to everyone, and loses nothing routing learned. set with --only or --never puts a condition on a live variant (chapter 9).

Every act can be rehearsed. With --dry-run it writes nothing and prints what it would change. With --expect, it refuses to run if anything changed on the site since you looked.

An act holds until a deploy changes the same thing in your code. So after an act, the page’s file follows:

Where what is live and your code differ, status says so on a line of its own, under drift.

Routing already does most of the work: once it knows a variant is worse, the variant gets few visits. What is left to you:

• Retire a variant that is clearly worse, and not better for any kind of visitor.
• Pause or retire at once a variant that is wrong: off-brand, mistaken, broken. That needs no evidence.
• Promote a clear leader, so the control stops paying for the old default.
• Replace what you retire. What the leaders have in common is the next idea.

• A default cannot be paused or retired. Promote another variant first.
• A variant with a rule or a belief cannot be promoted, since the default shows to everyone. Remove them first, if you want it everywhere.
• A visitor who was shown a paused variant gets the default for the rest of their visit.
• An act skips code review. Say in your agent instructions who may run one, and when.

Read more: Change what’s live · Routing settings

A routed page is never finished. Offers age, ads change, a competitor moves. What keeps a page improving is a routine, and it is a short one.

1. Read. What changed since the last look, and whether anything is broken. A figure built on broken tracking means nothing, so warnings come first.
2. Decide. What to retire, what to promote, what to leave alone (chapter 11).
3. Build. The next ideas, from what the leading variants have in common, and from outside the page: how similar sites present the same thing, what your ads are promising, what customers write to you.
4. Ship. Read plan, then deploy.

Once a week is the right rhythm. Evidence builds over days and weeks, and looking more often mostly shows noise.

However you work with your agent, a review comes down to the same thing: one look a week, and a decision.

The same records say where conversions came from. npx routingcat sources counts them by channel, by source, by campaign and by landing page, and results break down by your own audiences. It is accounting: it says where conversions came from, not what caused them.

Spellhome’s last four weeks, by audience:

A gift visit is worth $3.39, about 40% more than a first-dog or a homeowner visit. If gift ad sets cost the same per click as the others, they are where the next ad dollar should go. The page now says which traffic is worth buying, in profit and not in clicks. Your ad accounts never had that number.

The loop can be your agent’s. When you hand it the routine, it keeps the rhythm, fixes or raises what is broken, judges each slot, acts within what you allowed, and reports each time: what it changed, why, with the evidence and its ranges, and what it expects to learn next. It stays inside what you reserved, such as your brand, your claims or your prices, and asks before a change would cross it.

1. Install it on the page that takes your paid traffic, and say what a conversion is worth to you.
2. Start with the offer. It is where the money is.
3. Try ideas, not wordings: two to four bold variants a slot, sized to your traffic.
4. Read ranges, not points, and the split between how many convert and what a conversion is worth.
5. Retire, promote, replace. Weekly.
6. Name your audiences once the page has a clear best version for everyone.

Read more: Read and explain results · Work with your coding agent

RoutingCat sits in front of the pages that earn your living. Three questions decide whether that is acceptable: what it costs in speed, what happens when it fails, and what it knows about your visitors.

On Next.js, Nuxt and Astro, each visitor’s variants are picked on your own server before the page renders, from routing data refreshed in the background. No call to RoutingCat waits on the page, and the page arrives already in its variant, with no flicker.

• RoutingCat’s own work takes about a millisecond per page. On Vercel it runs as Routing Middleware, which adds from nothing measurable to about 20 ms depending on the region. On Cloudflare it adds 2 to 5 ms of CPU.
• Static pages stay static. Each combination of a static page is built and cached, and the visitor is sent to theirs before the cache.
• The browser code is about 11 KB, gzipped, on a page’s first load. It reports what the visitor was actually shown.
• On any other host, a script picks the variants in the browser before the page paints. A visitor’s first view waits for routing data, one second at most by default, then shows the defaults.

Visitors always get a page.

• If RoutingCat cannot be reached, routing goes on with the routing data each server last had. A new server waits up to 300 ms, then starts from the copy built into your deploy.
• If a build cannot reach it, the build ships as usual and shows your defaults.
• The tracking calls never throw, and send after the response, so they never delay or break a checkout.
• Every slot keeps its default, which is your site as it was.
• You hold the switches. A pause stops one variant within about two minutes. set routing=off returns the whole site to its defaults, and keeps everything routing learned.

• A preview deploy changes nothing live. It registers the new versions, and its own visits stay out of your results.
• In development, RoutingCat serves the defaults and records nothing.
• A production deploy is the only way a new variant reaches visitors. The first RoutingCat line of its build log says what went live.

RoutingCat personalizes on the context of a visit, never on who the visitor is.

• A visitor is a random id in a first-party cookie, written by your own server. It is random for each site and shared with none, so there is no profile of a person across sites.
• What it never stores: a visitor’s full IP address, email addresses, the contents of forms, a fingerprint, a precise location.
• What it records: the time, an approximate location, the device and browser, where the visit came from, what was shown, and the events you send.
• Crawlers, link previews and monitoring are left out of learning and results.
• The cookie is set for every visitor, whatever consent your site collects. The docs list every cookie and how long it lasts.

Keep personal data out of the events you send: they are kept as you send them.

Hobby is free: up to 10,000 visitors a month on routed pages, and 10 live variants across your sites. Pro is $100 a month: 100,000 visitors included, 100 live variants a page, and learning up to every hour, where Hobby learns once a day.

Read more: Run it in production · What RoutingCat collects · How RoutingCat works