# agentlytics

> Cookieless website analytics that coding agents can read and act on, by measuremy.site. One script tag records pageviews, referrers, UTM tags and custom events. An MCP server gives the agent traffic, spike explanations, growth actions and tracked campaign links. Free for 5,000 pageviews a month, 1 site.

## Add agentlytics to this project

You are a coding agent and the user asked you to add agentlytics. Do these steps in order. Use curl (or any HTTP client) for the API calls. All endpoints take and return JSON.

### 1. Ask the user two things

- Their email address. It creates or signs in to their agentlytics account. Signing up means they accept the terms (https://measuremy.site/terms) and privacy policy (https://measuremy.site/privacy); mention this.
- The site's production domain, like `example.com`. Look for it first (deploy config, `CNAME`, `vercel.json`, `netlify.toml`, `astro.config.*` `site`, `package.json` `homepage`, env files, README) and ask the user to confirm it. Subdomains are covered: `example.com` also counts `www.example.com` and `app.example.com`.

### 2. Send the sign-in code

```sh
curl -s -X POST https://measuremy.site/api/agent/start -H 'content-type: application/json' -d '{"email":"USER_EMAIL"}'
```

The user gets an email with a 6-digit code. Ask them to tell you the code. Codes expire after 10 minutes.

### 3. Exchange the code for the site's keys

```sh
curl -s -X POST https://measuremy.site/api/agent/verify -H 'content-type: application/json' \
  -d '{"email":"USER_EMAIL","code":"123456","domain":"example.com"}'
```

The response contains:
- `snippet`: the script tag to install. Its `data-key` (`pk_...`) is public and safe to commit.
- `read_key` (`rk_...`): **secret**. It lets an agent read this site's analytics. Never write it into a committed file.
- `mcp`: ready-made commands and config for Claude Code, Cursor and Codex.
- `verification`: how domain ownership is confirmed.
- `commands`: slash-command files for /make-public and /make-private (step 7).
- `dashboard`: the user's dashboard link.

If the domain is already in the user's account, the call issues a new read key and the old key stops working. Errors come back as `{"error": "...", "message": "..."}`; tell the user the message. `wrong_code` means ask again; `plan_limit` means the free plan's one site is taken.

### 4. Install the snippet

Put `snippet` in the `<head>` of every page, once, in the project's shared layout:

- **Next.js App Router:** `app/layout.tsx` inside `<head>` (a plain `<script defer ...>` works), or `next/script` with `strategy="afterInteractive"` and `data-key`.
- **Next.js Pages Router:** `pages/_document.tsx` inside `<Head>`.
- **Vite, React, Vue, Svelte (SPA):** `index.html` `<head>`. Client-side navigation is tracked automatically.
- **SvelteKit:** `src/app.html`. **Nuxt:** `app.head.script` in `nuxt.config`. **Remix / React Router:** `root.tsx`.
- **Astro:** the base layout's `<head>`. **Hugo / Jekyll / Eleventy:** the base template's `<head>`.
- **Rails / Django / Laravel / Express templates:** the main layout template.
- **Plain HTML:** every page's `<head>`.
- **WordPress, Webflow, Shopify, Framer, Squarespace, Wix, Ghost:** these are edited in the platform's admin, not in code. Give the user the snippet and point them to https://measuremy.site/docs/install.

If the site sets a Content-Security-Policy, add `https://a.measuremy.site` to `script-src` and `connect-src`.

### 5. Track the actions that matter

Find where signups, purchases, or other key actions succeed in the code. Add a call right after each success:

```js
window.agentlytics && agentlytics.track("signup", { plan: "free" })
```

Use short snake_case names (`signup`, `purchase`, `trial_started`). Props are optional and must not contain personal data.

### 6. Connect yourself over MCP

Use the matching entry from `mcp` in the response:

- **Claude Code:** run `mcp.claude_code`. It saves the server in local scope, which is private and never committed. The new tools load after the session restarts or after `/mcp` reconnects.
- **Cursor:** write `mcp.cursor.content` to `~/.cursor/mcp.json`, merging with any existing servers. If you use the project's `.cursor/mcp.json`, add that file to `.gitignore` first.
- **Codex:** add `mcp.codex.content` to `~/.codex/config.toml`, and tell the user to `export AGENTLYTICS_READ_KEY=<read_key>` in the shell that launches Codex.

### 7. Add the /make-public and /make-private commands

The response's `commands` field has small command files for each agent. Write the ones for the agent you are: Claude Code `.claude/commands/`, Cursor `.cursor/commands/` (both in the project; safe to commit), Codex `~/.codex/prompts/` (run as `/prompts:make-public`). Then the user can type `/make-public` to get a shareable public dashboard of traffic, spikes and their causes (growth actions stay private), and `/make-private` to turn it off. They need the MCP connection from step 6.

### 8. Deploy and confirm

Nothing is recorded until the domain is verified. Verification happens automatically on the first visit once the deployed homepage HTML contains the snippet. If the snippet is loaded through a tag manager, have the user add the DNS TXT record from `verification`.

After the user deploys, check:

```sh
curl -s https://measuremy.site/api/agent/site -H 'Authorization: Bearer READ_KEY'            # status
curl -s -X POST https://measuremy.site/api/agent/site -H 'Authorization: Bearer READ_KEY'    # re-run verification now
```

The response says `verified`, `events_last_24h` and a `next_step`.

### 9. Finish

- Tell the user what you changed, and give them the dashboard link.
- Offer to add a short note to the project's `CLAUDE.md` or `AGENTS.md`: "Analytics: agentlytics (MCP server `agentlytics`). Before marketing work, call get_growth_actions. Use create_tracked_link for every link you publish."
- Spike detection needs a few days of traffic before it has a baseline.

## Using the MCP tools

Endpoint: `https://a.measuremy.site/mcp` (streamable HTTP, `Authorization: Bearer <read_key>`).

- `get_overview`: visitors, pageviews, change vs the previous period. Start here.
- `find_traffic_spikes`, `explain_spike`: what caused each jump, ranked by source, page and event.
- `get_whats_working`: channels ranked by conversions and growth.
- `get_growth_actions`: a ranked action list built from the site's own numbers.
- `create_tracked_link`: a UTM link for anything you publish. Always use one.
- `get_campaign_results`: what each tracked campaign brought in.
- `add_annotation`: log launches, posts and deploys so spikes have context.
- `set_public_dashboard`: when the user asks to share their analytics, publish a public dashboard (or make it private again) and give them the link. It shows traffic, spikes and their causes; growth actions stay private. Claude Code also lists this as the `make-public` and `make-private` prompts.
- `query_visits`: answer questions about visits: count pageviews or events and visitors that match filters (country, browser, os, source, referrer, page, event), optionally grouped by one of them, by day or by hour. `recent_visits`: the latest individual visits with the same filters. No IP addresses or user agents are stored, so none can be returned.
- `top_countries`, `top_browsers`, `top_systems`: the same breakdowns as the dashboard.
- Also `get_timeseries`, `top_sources`, `top_pages`, `list_events`, and the `plan_marketing` prompt.

## Links

- [Install guide for every platform](https://measuremy.site/docs/install)
- [Agent setup](https://measuremy.site/docs/mcp)
- [How it works](https://measuremy.site/how-it-works)
- [Pricing](https://measuremy.site/pricing)