Skip to content
twelvebitStart free

Agent setup

Paste one prompt into your coding agent. It does the setup.

Claude Code, Codex or Cursor installs the tracker, writes your tracking plan, connects payments and checks that the first events arrive. You review the changes before you merge them.

Start free

A setup run, replayed

Prompt: Set up twelvebit analytics in this project for queststack.io. [Pasted text +8 lines]

Read (package.json, app/layout.tsx)

Next.js 16, App Router, Stripe Checkout

Update (app/layout.tsx)

+4 lines · tracking script in <head>

Write (analytics.yaml)

+28 lines · 4 events, 1 funnel

Write (lib/track.ts)

+22 lines · typed helpers

Update (app/api/checkout/route.ts)

+3 lines · visitor ID in checkout metadata

Bash (curl -X PUT …/api/v1/tracking-plan)

200 · plan saved, 4 events added

Bash (claude mcp add --transport http twelvebit …/api/mcp)

MCP server connected

Bash (curl …/api/v1/install-check)

4 events received in the last minute

Done. I added 4 events (signup, submit_tool, bump, checkout) and passed the visitor ID to Stripe Checkout, so payments are attributed. Review the diff before you merge.

Live check5 of 5
  • Site addedqueststack.io
  • First page view14:02:07
  • Tracking plan4 events
  • First goal: signup14:02:31
  • Revenue: first payment$29 · test mode
Event streamqueststack.io
payment$29.00 · Stripe test mode
checkoutplan=featured value=29
signuprole=maker source=submit
pageview/signup · Lisbon
pageview/leaderboard · Lisbon
pageview/ · Lisbon
What you need
  • A twelvebit account and a site (free during the beta)
  • A coding agent with access to your repo and a terminal
  • About five minutes to read the diff
No agent? Use the CLIsame setup from your terminal
npx -y https://twelvebit.app/cli/twelvebit-cli.tgz init

Step by step

What the agent does, in order.

Each step comes straight from the setup prompt. Nothing happens that you cannot see in the diff or in the terminal.

  1. Reads your project

    The agent finds the framework, the root layout, the sign-up flow and the checkout code. It reuses an analytics.yaml that is already there.

    package.jsonapp/layout.tsx

  2. Adds the tracking script

    One deferred script tag in the <head>, added the way your framework adds head scripts. For Next.js that is next/script in the root layout.

    app/layout.tsx

  3. Tracks the actions that matter

    It picks the 3 to 8 actions that matter most for your product, such as signup, start_trial or purchase, and tracks each one where it happens. Plain links and buttons can use a data-tb-goal attribute instead.

    window.twelvebit?.("signup", { plan: "pro" })

  4. Writes the tracking plan

    analytics.yaml lists every event with a description and its props. A small typed helper wraps the tracker, so event names and props match the plan.

    analytics.yamllib/track.ts

  5. Connects payments

    On the server, the agent reads the _tb_vid and _tb_sid cookies and adds them to the checkout metadata. Each payment then joins the visit that started it. This works with Stripe, Polar, Lemon Squeezy, Paddle and Dodo Payments.

    twelvebit_visitor_idtwelvebit_session_id

  6. Pushes the plan and connects MCP

    The agent sends analytics.yaml to twelvebit, so the dashboard knows your events. Then it adds the twelvebit MCP server, so it can read the numbers later.

    PUT /api/v1/tracking-plan/api/mcp

  7. Verifies the first events

    It runs the app, asks the install check for the last events, and lists what it added and where. The dashboard shows the same events live while you watch.

    GET /api/v1/install-check

The prompt

Read the whole prompt before you paste it.

This is the prompt for the demo site, queststack.io. In your dashboard the prompt has your own site ID, and the key stays in an environment variable.

Setup prompt9 lines · sample values
Set up twelvebit analytics in this project for queststack.io.

1. In the project root, run: npx -y https://twelvebit.app/cli/twelvebit-cli.tgz init queststack.io
   It opens the browser so that I can approve the sign-in. Wait until it finishes. It saves the site key in .env by itself: do not print the key or put it in chat. It also writes analytics.yaml and a twelvebit section in AGENTS.md.
2. Follow AGENTS.md: add the script tag that init printed, track the 3 to 8 actions that matter, and describe them in analytics.yaml.
3. Run npx -y https://twelvebit.app/cli/twelvebit-cli.tgz codegen, then npx -y https://twelvebit.app/cli/twelvebit-cli.tgz check --strict, then trigger one event and run npx -y https://twelvebit.app/cli/twelvebit-cli.tgz status until it arrives.
4. Connect the MCP server so you can read the data later (it signs in through the browser): claude mcp add --transport http twelvebit https://twelvebit.app/api/mcp

Full guide: https://twelvebit.app/setup.md. At the end, list the events you added and where.

Tracking plan

The plan is a file in your repo.

analytics.yaml is the source of truth for your events. It goes through code review, and the agent pushes it to twelvebit so the dashboard can show the health of each event.

analytics.yamltracking plan
# analytics.yaml · written by your agent, reviewed by you
version: 1
project: queststack.io
integrations: [stripe]
events:
  signup:
    description: A visitor creates an account
    props:
      role: { type: string, enum: [maker, buyer] }
  submit_tool:
    description: A maker submits a tool to the directory
  checkout:
    description: A maker opens the checkout for a paid plan
    props:
      plan: { type: string }
      value: { type: number }
  bump:
    description: A signed-in user bumps a listing
    props:
      tool: { type: string }
dashboards:
  funnels:
    - name: Visit to paid listing
      steps: ["page:/pricing", signup, checkout, payment]
lib/track.tstyped helpers
// lib/track.ts · typed helpers from analytics.yaml
type Plan = "boost" | "featured" | "lifetime";

export const track = {
  submitTool: (p: { category: string }) =>
    window.twelvebit?.("submit_tool", p),
  checkout: (p: { plan: Plan; value: number }) =>
    window.twelvebit?.("checkout", p),
};

track.submitTool({ category: "ai-coding" });
track.checkout({ plan: "featured", value: 29 });

MCP server

Your agent can read the numbers too.

The twelvebit MCP server gives your agent read access to your analytics. Ask which page brought the most customers, then ask it to improve that page.

Connect itone command
Claude Code
claude mcp add --transport http twelvebit \
  https://twelvebit.app/api/mcp \
  --header "Authorization: Bearer $TWELVEBIT_API_KEY"
Codex
codex mcp add twelvebit \
  --url https://twelvebit.app/api/mcp \
  --bearer-token-env-var TWELVEBIT_API_KEY
Cursor · .cursor/mcp.json
{
  "mcpServers": {
    "twelvebit": {
      "url": "https://twelvebit.app/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:TWELVEBIT_API_KEY}"
      }
    }
  }
}
Toolsread only
  • get_overviewVisitors, revenue, customers and conversion, with the previous period
  • get_revenueRevenue by channel and plan, and recent payments with their credited channel
  • get_breakdownTop channels, pages, countries or devices, with attributed revenue
  • get_funnelCounts per step, conversion by channel and days to convert
  • get_journeyOne person's visits, events and payments
  • get_realtimeVisitors online now and visitors per minute
  • get_install_statusWhich planned events have arrived
  • update_tracking_planValidate and save a new analytics.yaml

Guardrails

Rules the agent follows.

  • Keys stay out of chat and git

    The agent writes the API key to .env only when .env is in .gitignore. The tracker in the browser needs no secret.

  • No personal data in events

    Event props are flat strings, numbers or booleans. The prompt tells the agent not to put names or emails in them.

  • You review every change

    The agent keeps changes small and follows your code style. You read the diff and merge it like any other pull request.

  • Safe to run again

    Run the prompt again after a refactor. The agent reuses the plan that is already in your repo and fills in what is missing.

Paste one prompt. Watch the first events arrive.

Start free. Your agent does the setup, and you see revenue next to the traffic that brought it.

Start free

Free during public beta · no card needed