Work with your coding agent

Your coding agent is how you use RoutingCat. You say what you want, in your own words, and it writes the variants, wires the tracking, reads the results and acts, as it does with the rest of your code. This guide covers how to work with it, the skill that makes it an expert, the note that points it there, and what an agent in a sandbox needs.

Work at the level you like

As with any code, you choose how much to direct and how much to hand over:

You say	Your agent
“Try ‘Edit photos in one click’ as the home page’s headline.”	declares that variant beside the current headline, checks that it renders, runs `plan` and tells you what will go live
“Try three headlines on the home page.”	writes three distinct ideas from what your site already says, and ships them the same way
“Get more sign-ups from the pricing page.”	reads where visitors come from and how the page does, proposes what to try, and builds it
“How is it going?”	runs `status`, and says each number with how sure it is
“Run the home page’s experiments, and check in every week.”	reads the evidence each week, retires what does worse, keeps what works, adds new ideas, ships them as your repository allows, and tells you what it did and why
“Is RoutingCat working?”	runs `doctor`, and explains any check that fails

Read and explain results says how each figure is worded, and Change what’s live what each act does.

What your agent checks with you

Your agent works the way you do, and brings you what is yours to decide:

At setup, your main conversion. It defines what routing learns to get more of, so your agent proposes one, with its reasons, and asks you. It also asks whether to add the note to AGENTS.md, unless you answered at a terminal.
What will reach your visitors. Before a deploy, plan shows what will go live, and before an act, --dry-run shows what it will change. Your agent shows you these as you like to work: before each change, or in its report when you have handed it the work.
Claims. Variants are public copy, so facts, numbers, testimonials, prices and legal text come from your site or from you.
The evidence, with how sure it is, and what it would keep, retire or try next.

Say what your agent may do

The skill tells your agent to follow your repository’s own agent instructions, such as AGENTS.md or CLAUDE.md. Say there whether your agent may commit, push to your repository or deploy, and what it may change.

New variants reach visitors only through a deploy and the production push that registers it. Acts, such as a pause or a promote, change what is live within about 2 minutes without either.

Let your agent read freely, and approve what changes your site. Most of what your agent runs only reads, and is safe to allow in its own settings: status, show, sources, download, plan, doctor, docs and preview, and push with --check, --dry-run or --head-only. The rest is worth approving call by call:

the acts, promote, pause, resume, retire, revert, set and gap, which change what visitors see;
keys, link, connect, domains and members, which change who and what reaches your site;
a plain push, which registers production with --env production once you confirm its plan.

With Claude Code, the rules go in .claude/settings.json, committed to your repository so your team shares them, one rule per command:

{
  "permissions": {
    "allow": [
      "Bash(npx routingcat status *)",
      "Bash(npx routingcat plan *)",
      "Bash(npx routingcat doctor *)",
      "Bash(npx routingcat docs *)",
      "Bash(npx routingcat push --check *)"
    ]
  }
}

A rule matches the command as your agent writes it, so add one for each command you allow, and leave push out of any ask or deny rule: such a rule wins over an allow, and would stop push --check too.

Give your agent the skill

npx routingcat init installs RoutingCat’s skill at your repository’s root, in the Agent Skills format: in .agents/skills/routingcat/, with a copy in .claude/skills/routingcat/, so that each agent finds it where it looks.

Agent	Reads skills from
Claude Code	`.claude/skills/`
Codex, Gemini CLI	`.agents/skills/`
Cursor, GitHub Copilot	`.agents/skills/` or `.claude/skills/`: `init` writes both, so either finds it

What it teaches:

File	When the agent reads it	What it covers
`SKILL.md`	Whenever it works on RoutingCat	How RoutingCat works, including how routing learns and how each number is made; trying ideas; the acts; reading results; the commands
The file for your site’s stack, such as `nextjs.md`, and for its host, such as `vercel.md`	Before any change to your site’s code	How to declare, render, check and ship variants on your stack, how to track conversions there, and what fails there
`setup.md`	Once	Finishing setup
`experiments.md`	When it designs what to try, judges results, or runs experiments for you	Designing ideas, sizing them to your traffic, judging the evidence, and running experiments over time
`troubleshooting.md`	When something fails	Each symptom and its fix

For exact references, it reads these pages, in the copy for your kind of site that the command carries: npx routingcat docs <page> prints one, and <page>#<anchor> one section, from the version your routingcat.config.json pins, so that the pages match your site.

How it stays current: init brings it level with its own version, the one your config pins, unless you edited it. doctor says when the skill is older than that version, or edited.

A skill installed during a conversation may load only in the next one. Run by an agent, init ends by telling it to read the skill’s setup.md directly, so setup goes on in the same conversation.

Add the note to `AGENTS.md`

Agents open a skill when a request matches its description, and often skip it otherwise. They read your repository’s AGENTS.md in every session, so init offers a two-line note there, recommended, that sends them to the skill:

<!-- routingcat -->
This site uses RoutingCat to try page variants, route visitors between them and measure conversions.
Before working on the site's conversion, its experiments or results, `routingcat/`, `routingcat.config`, its slot markup, or any `track` or `identify` call, read `.agents/skills/routingcat/SKILL.md` and the file it names for the site's stack; `npx routingcat docs <page>` prints the docs for the site's version, also in `node_modules/routingcat/docs/` where the package is installed.

Your site runs the command through npx, with no node_modules, so your agent reads those docs with npx routingcat docs <page>, as the skill tells it.

You choose. At a terminal, init asks, yes by default. Run by your agent, it leaves the choice to you: your agent asks, then runs npx routingcat init --agents-md if you agree.
Where it goes: AGENTS.md at your repository’s root, created if missing, and CLAUDE.md if you have one, which Claude Code reads instead. A CLAUDE.md that imports AGENTS.md with @AGENTS.md already gets the note through the import, so init leaves it as it is.
It stays current. Run again, init keeps the note up to date, writing only between its two markers. doctor reports whether the note is there, as information.
To take it out, delete the lines from  to  in each file that has them. Run again, init then asks once more, or your agent asks you; --no-agents-md skips the question.

Run it in a sandbox

Network. The commands reach RoutingCat’s API. In a sandbox without network access, as Codex’s is by default, a command exits with code 4: allow network access for it, or run it yourself.
Sign-in. You sign in once per machine; the command keeps the sign-in in the machine’s keychain, else in a file only you can read, and every new conversation uses it. A read-only sandbox can’t keep it, and the command exits with code 3: run npx routingcat login in your own terminal, then the same command again. See Access and keys.
Waiting. Exit code 3 means a command is waiting, on a person, such as a sign-in to approve, or on time, such as doctor’s checks right after a deploy. Your agent tells you what to do, or waits a little, then runs the same command again.
Long commands. doctor --wait names a page of your site for you to open in your browser, since your pages decide only there, then waits up to 5 minutes for your visit. The skill gives it a 6-minute timeout under Claude Code; Codex and Cursor move long commands to the background.

Read the JSON

Every command takes --json and returns one object with every field; the text is a view of it. A failure carries its exit code and its message, with the message’s id. See JSON output and The routingcat command.