Getting started

SplitHub is A/B testing for web apps where the code is written with a coding agent. Experiments are declared in splithub.config.ts, variants are rendered with React or Next.js (or decided by a drop-in script), and the verdict is read from the CLI, the MCP server, the dashboard or an email. Events go to your own database or to SplitHub Cloud.

One command#

In the folder of your app:

npx splithub

The interactive menu offers: sign in through a link (no key to paste), create or pick a cloud project, write splithub.config.ts and the framework files, print the provider integration snippet, install the agent skills and the MCP server entry, create the first experiment, push it. Every step is also a subcommand with flags and --json, which is what an agent uses:

npx splithub init --mode cloud --yes      # or --mode self for your own database
npx splithub create --kind value --id hero-title --variants control,bold \
  --value "control=Old headline" --value "bold=New headline" --goal signup --yes
npx splithub push
npx splithub start hero-title
npx splithub results hero-title

Prefer to let the agent do it? Open the project in Claude Code, Cursor or Codex and say: "Set up SplitHub and A/B test the headline on the home page." After init the agent has the skills and the MCP server it needs.

What init writes#

File	Purpose
splithub.config.ts	Experiments and goals. The source of truth.
Provider snippet in the command output	Add it to app/layout.tsx or main.tsx to wrap the app in the provider.
middleware.ts (Next.js)	Visitor cookie, redirect experiments, header for Server Components.
app/api/splithub/[[...path]]/route.ts (self mode)	Ingest and results handler with a store.
splithub/store.ts (self mode, --db postgres or mysql)	A working store for your database.
.claude/skills/*, .cursor/rules/splithub.mdc, AGENTS.md or CLAUDE.md section	Agent skills.
.mcp.json, .cursor/mcp.json	MCP server registration.

Render a variant#

import { useValue, useTrack } from '@splithub/react';

export function Hero() {
  const title = useValue<string>('hero-title');
  const track = useTrack();
  return <h1 onClick={() => track('signup')}>{title}</h1>;
}

create writes the experiment as running: it goes live for every visitor when you deploy the code that renders it. Check it locally first with ?sh_force=<id>:<variant>; development never sends events to the cloud. To hold a test, create it with --status draft and start it later with npx splithub start <id>, or pause it in the dashboard.

A value experiment changes data (text, a URL, a number, JSON) without new components. A component experiment renders different JSX per variant with <Experiment id="…"><Variant name="control">…</Variant></Experiment>. A redirect experiment sends each variant to its own page. See React, Next.js and Redirect experiments.

Read the verdict#

npx splithub status            # every experiment: status, visitors, days, verdict headline
npx splithub results hero-title

The verdict is one of no_data, insufficient_sample, srm_detected, winner_found, no_significant_difference, with a message and the numbers behind it: visitors and conversions per variant, relative lift, p-value, 95% confidence interval, probability to beat. The statistics page explains each.

Finish#

npx splithub finish hero-title

Replace the useValue call (or the <Experiment>) with the winning content, delete the losing code, keep the config entry for history or remove it. In cloud mode a finished experiment stops accepting events at the edge; nothing more is stored or billed.

Next#

• How it works explains assignment, exposures and goals.
• splithub.config.ts lists every option.
• Self-hosted if the events must stay in your database.
• SplitHub Cloud for the dashboard, live overrides, alerts and AI reviews.