# 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:

```bash
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:

```bash
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](/docs/agent-skills) and the [MCP server](/docs/mcp) 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

```tsx
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](/docs/react), [Next.js](/docs/nextjs) and [Redirect experiments](/docs/redirect-experiments).

## Read the verdict

```bash
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](/docs/statistics) explains each.

## Finish

```bash
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](/docs/concepts) explains assignment, exposures and goals.
- [splithub.config.ts](/docs/config) lists every option.
- [Self-hosted](/docs/self-hosted) if the events must stay in your database.
- [SplitHub Cloud](/docs/cloud) for the dashboard, live overrides, alerts and AI reviews.