agent-analytics

---
name: agent-analytics
description: "Simple website analytics your AI agent controls end-to-end. Track page views, events, funnels, retention, and A/B experiments across all your projects. Use when: adding website tracking, checking site traffic, setting up conversion funnels, running A/B experiments, or replacing Mixpanel / Plausible / PostHog with something lightweight and agent-operated. No dashboard needed."
version: 3.7.0
author: dannyshmueli
repository: https://github.com/Agent-Analytics/agent-analytics-cli
homepage: https://agentanalytics.sh
tags:
  - analytics
  - tracking
  - web
  - events
  - experiments
  - live
  - website-tracking
  - page-views
  - funnels
  - retention
  - ab-testing
  - simple-analytics
  - privacy
  - agent-first
  - plausible-alternative
  - mixpanel-alternative
  - growth
metadata: {"openclaw":{"requires":{"env":["AGENT_ANALYTICS_API_KEY"],"anyBins":["npx"]},"primaryEnv":"AGENT_ANALYTICS_API_KEY"}}
---

# Agent Analytics — Website analytics your AI agent fully operates

Simple, privacy-first website analytics and growth toolkit that your AI agent controls end-to-end. Track page views, custom events, conversion funnels, user retention, and A/B experiments across all your projects — then talk to your analytics in natural language. No dashboards. Your agent creates projects, adds tracking code, queries traffic data, builds funnels, runs experiments, and tells you what to optimize next. A lightweight Plausible/Mixpanel/PostHog alternative built for the AI agent era.

## Security & trust

- **Open source**: Full source at [github.com/Agent-Analytics/agent-analytics-cli](https://github.com/Agent-Analytics/agent-analytics-cli) — inspect every command before running
- **Read-only by default**: The CLI only reads analytics data. Write operations (creating projects, experiments) require explicit user-provided API keys
- **No arbitrary code execution**: All CLI commands use structured flags (`--days`, `--property`, `--steps`). No eval, no shell interpolation, no dynamic code generation
- **Scoped permissions**: The API key controls access. The CLI never requests filesystem, network, or system-level permissions beyond HTTP calls to `api.agentanalytics.sh`
- **Published on npm**: [@agent-analytics/cli](https://www.npmjs.com/package/@agent-analytics/cli) — versioned, auditable, standard npm supply chain

## Philosophy

You are NOT Mixpanel. Don't track everything. Track only what answers: **"Is this project alive and growing?"**

For a typical site, that's 3-5 custom events max on top of automatic page views.

## First-time setup

**Get an API key:** Sign up at [agentanalytics.sh](https://agentanalytics.sh) and generate a key from the dashboard. Alternatively, self-host the open-source version from [GitHub](https://github.com/Agent-Analytics/agent-analytics).

If the project doesn't have tracking yet:

```bash
# 1. Login (one time — uses your API key)
npx @agent-analytics/cli login --token aak_YOUR_API_KEY

# 2. Create the project (returns a project write token)
npx @agent-analytics/cli create my-site --domain https://mysite.com

# 3. Add the snippet (Step 1 below) using the returned token
# 4. Deploy, click around, verify:
npx @agent-analytics/cli events my-site
```

The `create` command returns a **project write token** — use it as `data-token` in the snippet below. This is separate from your API key (which is for reading/querying).

## Step 1: Add the tracking snippet

The `create` command returns a tracking snippet with your project token — add it before `</body>`. It auto-tracks `page_view` events with path, referrer, browser, OS, device, screen size, and UTM params. You do NOT need to add custom page_view events.

## Step 1b: Discover existing events (existing projects)

If tracking is already set up, check what events and property keys are already in use so you match the naming:

```bash
npx @agent-analytics/cli properties-received PROJECT_NAME
```

This shows which property keys each event type uses (e.g. `cta_click → id`, `signup → method`). Match existing naming before adding new events.

## Step 2: Add custom events to important actions

Use `onclick` handlers on the elements that matter:

```html
<a href="..." onclick="window.aa?.track('EVENT_NAME', {id: 'ELEMENT_ID'})">
```

The `?.` operator ensures no error if the tracker hasn't loaded yet.

### Standard events for 80% of SaaS sites

Pick the ones that apply. Most sites need 2-4:

| Event | When to fire | Properties |
|-------|-------------|------------|
| `cta_click` | User clicks a call-to-action button | `id` (which button) |
| `signup` | User creates an account | `method` (github/google/email) |
| `login` | User returns and logs in | `method` |
| `feature_used` | User engages with a core feature | `feature` (which one) |
| `checkout` | User starts a payment flow | `plan` (free/pro/etc) |
| `error` | Something went wrong visibly | `message`, `page` |

### What to track as `cta_click`

Only buttons that indicate conversion intent:
- "Get Started" / "Sign Up" / "Try Free" buttons
- "Upgrade" / "Buy" / pricing CTAs
- Primary navigation to signup/dashboard
- "View on GitHub" / "Star" (for open source projects)

### What NOT to track
- Every link or button (too noisy)
- Scroll depth (not actionable)
- Form field interactions (too granular)
- Footer links (low signal)

### Property naming rules

- Use `snake_case`: `hero_get_started` not `heroGetStarted`
- The `id` property identifies WHICH element: short, descriptive
- Name IDs as `section_action`: `hero_signup`, `pricing_pro`, `nav_dashboard`
- Don't encode data the page_view already captures (path, referrer, browser)

## Step 2b: Run A/B experiments (Pro)

Experiments let you test which variant of a page element converts better. The full lifecycle is API-driven — no dashboard UI needed.

### Creating an experiment

```bash
npx @agent-analytics/cli experiments create my-site \
  --name signup_cta --variants control,new_cta --goal signup
```

### Implementing variants

**Declarative (recommended):** Use `data-aa-experiment` and `data-aa-variant-{key}` HTML attributes. Original content is the control. The tracker swaps text for assigned variants automatically.

```html
<h1 data-aa-experiment="signup_cta" data-aa-variant-new_cta="Start Free Trial">Sign Up</h1>
```

**Programmatic (complex cases):** Use `window.aa?.experiment(name, variants)` — deterministic, same user always gets same variant.

Exposure events (`$experiment_exposure`) are tracked automatically once per session. Track the goal event normally: `window.aa?.track('signup', {method: 'github'})`.

### Checking results

```bash
npx @agent-analytics/cli experiments get exp_abc123
```

Returns Bayesian `probability_best`, `lift`, and a `recommendation`. The system needs ~100 exposures per variant before results are significant.

### Managing experiments

```bash
# Pause (stops assigning new users)
npx @agent-analytics/cli experiments pause exp_abc123

# Resume
npx @agent-analytics/cli experiments resume exp_abc123

# Complete with a winner
npx @agent-analytics/cli experiments complete exp_abc123 --winner new_cta

# Delete
npx @agent-analytics/cli experiments delete exp_abc123
```

### Best practices
- Name experiments with snake_case: `signup_cta`, `pricing_layout`, `hero_copy`
- Use 2 variants (A/B) unless you have high traffic — more variants need more data
- Set a clear `goal_event` that maps to a business outcome (`signup`, `purchase`, not `page_view`)
- Let experiments run until `sufficient_data: true` before picking a winner
- Complete the experiment when done: `experiments complete <id> --winner new_cta`

## Step 3: Test immediately

After adding tracking, verify it works:

```bash
# Option A: Browser console on your site:
window.aa.track('test_event', {source: 'manual_test'})

# Option B: Click around, then check:
npx @agent-analytics/cli events PROJECT_NAME

# Events appear within seconds.
```

## Querying the data

All commands use `npx @agent-analytics/cli`. Your agent uses the CLI directly — no curl needed.

### CLI reference

```bash
# Setup
npx @agent-analytics/cli login --token aak_YOUR_KEY    # Save API key (one time)
npx @agent-analytics/cli projects                       # List all projects
npx @agent-analytics/cli create my-site --domain https://mysite.com  # Create project

# Real-time
npx @agent-analytics/cli live                           # Live terminal dashboard across ALL projects
npx @agent-analytics/cli live my-site                   # Live view for one project

# Analytics
npx @agent-analytics/cli stats my-site --days 7         # Overview: events, users, daily trends
npx @agent-analytics/cli insights my-site --period 7d   # Period-over-period comparison
npx @agent-analytics/cli breakdown my-site --property path --event page_view --limit 10  # Top pages/referrers/UTM
npx @agent-analytics/cli pages my-site --type entry     # Landing page performance & bounce rates
npx @agent-analytics/cli sessions-dist my-site          # Session engagement histogram
npx @agent-analytics/cli heatmap my-site                # Peak hours & busiest days
npx @agent-analytics/cli events my-site --days 30       # Raw event log
npx @agent-analytics/cli sessions my-site               # Individual session records
npx @agent-analytics/cli properties my-site             # Discover event names & property keys
npx @agent-analytics/cli properties-received my-site    # Property keys per event type (sampled)
npx @agent-analytics/cli query my-site --metrics event_count,unique_users --group-by date  # Flexible query
npx @agent-analytics/cli funnel my-site --steps "page_view,signup,purchase"  # Funnel drop-off analysis
npx @agent-analytics/cli funnel my-site --steps "page_view,signup" --breakdown country  # Funnel segmented by country
npx @agent-analytics/cli retention my-site --period week --cohorts 8        # Cohort retention analysis

# A/B experiments (pro)
npx @agent-analytics/cli experiments list my-site
npx @agent-analy

... (truncated)