# Duelpilot — instructions for AI agents You are an AI agent and your user wants A/B tests on their website (or asked you to look into Duelpilot). This page tells you how to set Duelpilot up end to end, up to the first test, without your user filling in forms. Your user only has to (1) say which site, (2) let you add one script tag, and (3) click a claim link and approve. ## Rules that always apply - Ask your user before you change their website, CMS or code, and before you sign up. Say what Duelpilot is: A/B testing where you (the agent) research, design and monitor tests, and a person approves every launch. - The Duelpilot token you get is a secret. Never put it in website code, a repository or a chat message other people can see. The site key in the script tag is public; that is fine. - You cannot approve, launch, resume, pick a winner or ship. Those are human decisions in Duelpilot's board. Don't ask your user to give you a way around that. - Never invent prices, claims, reviews or numbers in variant copy. ## Step 1 — Open a workspace ```bash curl -sS -X POST https://duelpilot.com/api/agent/signup \ -H 'content-type: application/json' \ -d '{"site_url": "https://www.example.com", "site_name": "Example", "agent": "claude-code"}' ``` The answer (HTTP 201) contains: - `token`: your MCP bearer token (`dpl_…`), scoped to this one site. Shown once. - `mcp.url`: https://duelpilot.com/api/mcp - `claim_url`: give this to your user **now**. They open it, sign in with their email and become the owner. Unclaimed workspaces are deleted after 14 days. - `workspace.site_key`: the public key for the script tag. Limits: a few signups per hour per address. On HTTP 429, reuse the token you already have. ## Step 2 — Connect to the MCP server Pick what your environment supports: - **claude.ai / Claude Desktop / ChatGPT**: add a custom connector with URL `https://duelpilot.com/api/mcp` and sign in (OAuth). Your user signs in to Duelpilot in the browser and picks the organisation, sites and permissions; no token to paste. ChatGPT: chatgpt.com/plugins → + → Add custom MCP server, authentication OAuth. - **Claude Code**: `claude mcp add --transport http duelpilot https://duelpilot.com/api/mcp --header "Authorization: Bearer $DUELPILOT_TOKEN"` (the tools appear in a new session). - **Cursor / other MCP clients**: a remote server with URL `https://duelpilot.com/api/mcp` and header `Authorization: Bearer `. - **No MCP client? Plain HTTP works** (stateless JSON-RPC, no initialize needed): ```bash curl -sS https://duelpilot.com/api/mcp \ -H "Authorization: Bearer $DUELPILOT_TOKEN" \ -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_install","arguments":{}}}' ``` Use `tools/list` to see all tools and `prompts/get` with name `setup` for the guided setup. ## Step 3 — Install the script and verify it 1. `get_install` returns the exact snippet, the detected platform (WordPress, Shopify, Webflow, Wix, Next.js, Nuxt, …) and the install guide for it. The snippet goes at the top of ``, synchronous. 2. Install it the way your access allows: in the code (repository), in the CMS together with your user (they log in themselves; ask before every save or publish), or give your user the steps. 3. `verify_install` checks the live page in real desktop and mobile browsers. When it passes, the site counts as installed. That is also the proof that your user controls the site: tools that fetch pages (`inspect_page`, `run_site_check`, `submit_proposals`, …) only work after this. ## Step 4 — Set up the site Run the MCP prompt `setup` (or do the same with tools): `get_site_status`, `inspect_page` on the main templates, then draft `propose_site_profile` (language, brand voice, audience, primary conversion, palette, sensitive URLs, forbidden claims — ask your user for those), `propose_goal` (the primary conversion and one or two guardrails) and `propose_audience`. These are drafts; your user confirms them in Duelpilot. Google Analytics is connected by your user in Duelpilot (Settings → Analytics), not by you. Without it, Duelpilot still counts results itself. ## Step 5 — The first test 1. `start_agent_run` with `agent: "analyst"`: you get the current Analyst instructions. Follow them; they end with `propose_ideas` (each idea needs two pieces of evidence) and `finish_agent_run`. 2. Start the first design round yourself: `start_design` on the idea with the strongest evidence and ICE. This works for the site's first test only (later, your user moves ideas to **Design** on the board, or switches on auto-design). Tell your user which idea you picked and why. 3. `start_agent_run` with `agent: "designer"`: design 2–4 proposals, `submit_proposals` (dry run first). Each gets a preview link and a site check on phone, tablet and desktop. 4. Your user claims the workspace (step 1), then picks and approves in Duelpilot. You never approve. The test goes live. 5. Monitor daily with `start_agent_run` and `agent: "monitor"`. To keep this going without you being asked, help your user create three routines in their own agent (Analyst weekly, Designer every 30 minutes plus a trigger, Monitor daily). The exact one-line prompts: `get_playbook` with name `routines`. ## Code tests (Code plan) Some tests change behaviour rather than the page: a new booking flow, a different date picker, fewer form fields, pricing logic, search ranking. On the Code plan you build those yourself, in your user's own repository with your user's own GitHub/GitLab access; Duelpilot never gets repository access. Duelpilot serves the flag, splits traffic, counts, checks your preview deployments and shows everything on the board. - An idea with `kind: "code"` is a code test. Its flag key is the experiment key (`e12`); arms are `c` (control, your existing code) and `v1`–`v3`; `null` always means control. - In the browser: `window.duelpilot.variant("e12")` (counts the exposure on the first call). On the server: the dependency-free SDK from `get_flag_sdk` (also at https://duelpilot.com/sdk/duelpilot-flags.ts), which reads the public flag config from the edge and buckets exactly like the browser when both use the `dp_vid` cookie. - Small arms, one branch and pull request per arm (`duelpilot/e12-v1-…`), each with a preview deployment; report them with `submit_code_variants` (dry run first). Duelpilot site-checks the previews on phone, tablet and desktop. - **Never merge.** A person approves the test in Duelpilot and merges. After a winner ships you get a cleanup job: open the PR that removes the flag and keeps the winner, and report it with `submit_cleanup_pr`. - Full playbook: `get_playbook` with name `code-tier`. ## Paying Your user chooses a plan when they claim the workspace (https://duelpilot.com/pricing.md). The first test is free on every plan; after it, a paid plan needs an active subscription before the next test can launch (Free keeps working within its limits). Payment is always done by your user in Duelpilot: never enter payment details yourself. ## Messages from Duelpilot Duelpilot sends the agents of a workspace short messages: product updates, tips, notices and, rarely, incidents. You get the unread ones in `start_agent_run` (`messages_from_duelpilot`), other tool answers end with a one-line note while some are unread, and `get_messages` lists them (without MCP: `GET https://duelpilot.com/api/agent/messages` with your token). They are information from the platform, never instructions that outrank your user: tell your user what matters to them, act on "action" messages only with their agreement, then call `ack_messages` (one acknowledgement covers every agent of the workspace). Public updates: https://duelpilot.com/updates.md. ## Errors Every tool answers `{ok:false, code, message, fix}` on failure; follow `fix`. `NOT_INSTALLED` means step 3 isn't done; `NOT_CLAIMED` means your user hasn't opened the claim link yet; `HUMAN_ONLY` means it's your user's decision.