# BetterMeter

> BetterMeter is a privacy-first analytics platform for the AI era. It tracks websites, CLI tools, MCP servers, and APIs through a unified, cookie-free pipeline. BetterMeter is an alternative to Google Analytics built for developers who ship AI-powered products.

## What is BetterMeter?

BetterMeter is a web and developer tool analytics platform designed for the AI-first internet. Unlike traditional analytics (Google Analytics, Plausible, Fathom), BetterMeter tracks not just website visitors but also CLI tool usage, MCP server tool invocations, and API endpoint traffic — all in one dashboard.

BetterMeter answers questions that traditional analytics cannot:
- How much traffic comes from ChatGPT, Claude, Perplexity, and other AI platforms?
- Which AI crawlers (GPTBot, ClaudeBot, etc.) are indexing your site, and how often?
- Which CLI commands do developers use most? What is the error rate?
- Which AI clients (Claude Code, Cursor, Windsurf) invoke your MCP server tools?
- Which API endpoints are slowest? What is the error rate by endpoint?
- How do LLMs describe your brand in AI search results?

## Key Differentiators

- **AI Traffic Attribution**: Identifies visitors referred by ChatGPT, Claude, Perplexity, Gemini, and Copilot. No other analytics platform does this.
- **Four Source Types**: Tracks websites, CLI tools, MCP servers, and APIs through the same pipeline.
- **Privacy by Default**: No cookies, no fingerprinting, no PII storage. GDPR compliant without consent banners.
- **MCP Server Native**: BetterMeter itself runs as an MCP server, so AI assistants can query your analytics directly.
- **Brand Monitoring**: Tracks how LLMs describe your brand across AI search queries with visibility scoring.

## Features

### AI Traffic Attribution
See exactly how many visitors come from ChatGPT, Claude, Perplexity, Gemini, and Copilot. Understand which AI platforms drive real engagement to your site. BetterMeter detects AI referrals by parsing referrer headers and user agent strings for known AI platform patterns.
- [Learn more](https://bettermeter.com/features/ai-traffic-attribution)

### Bot & Crawler Analytics
Track GPTBot, ClaudeBot, Googlebot, and 30+ crawlers. Know which bots hit your site, how often, and which pages they index. Filter by category: AI crawlers, search engines, monitoring bots, and scrapers.
- [Learn more](https://bettermeter.com/features/bot-crawler-analytics)

### CLI Analytics
Track how developers use your CLI tool. See top commands, error rates, execution duration, CI vs local usage, and usage trends over time. Integrates with Commander.js via auto-wrapping or manual tracking.
- [Learn more](https://bettermeter.com/features/cli-analytics)

### MCP Server Analytics
Track which tools AI clients invoke on your MCP server. See Claude vs Cursor vs Windsurf breakdown, success rates, latency, and token usage. Auto-wraps MCP server tool handlers with zero code changes.
- [Learn more](https://bettermeter.com/features/mcp-analytics)

### API Analytics
Monitor API endpoints with Express middleware or manual tracking. See top endpoints, error rates, latency, and caller patterns. One line to add to an Express app.
- [Learn more](https://bettermeter.com/features/api-analytics)

### Privacy-First Analytics
No cookies, no fingerprinting, no local storage, no PII. IP addresses are SHA-256 hashed with daily salt rotation — raw IPs are never stored. GDPR, CCPA, and PECR compliant by default. No consent banner required.
- [Learn more](https://bettermeter.com/features/privacy-first-analytics)

### Live Visitors
Real-time live visitor count powered by activity-gated heartbeats. The browser tracker sends a heartbeat every 30 seconds while the tab is visible and the user is active. Live counts are stored in Redis sorted sets and expire after 60 seconds of inactivity. Opt out with the `data-no-heartbeat` attribute on the script tag.
- Dashboard: green pulsing dot with live count, refreshes every 10 seconds
- CLI: `bettermeter live -s <siteId> [--json]`
- MCP: `bettermeter_live_visitors` tool
- API: `GET /api/analytics/live?siteId=...` returns `{ live: number }`

### Brand Monitoring
See how ChatGPT, Claude, and Gemini describe your brand. Track AI visibility score (0-100), sentiment, accuracy, and competitor rankings across LLM search results. Get alerts when your position changes.
- [Learn more](https://bettermeter.com/features/brand-monitoring)

## Integrations

BetterMeter tracks four event sources through a single pipeline:

| Source | Integration | Event |
|--------|------------|-------|
| Website | `<script>` tag (~1KB, no cookies) | pageview, custom events |
| CLI tool | `@bettermeter/node` SDK | cli.command |
| MCP server | `@bettermeter/node` SDK | mcp.tool |
| API | `@bettermeter/node` SDK | api.request |

BetterMeter connects to 50+ tools across your stack:

- **AI Tools & IDEs**: [Claude Code](https://bettermeter.com/integrations/claude-code), [Claude Desktop](https://bettermeter.com/integrations/claude-desktop), [Cursor](https://bettermeter.com/integrations/cursor), [Windsurf](https://bettermeter.com/integrations/windsurf), [GitHub Copilot](https://bettermeter.com/integrations/github-copilot), [VS Code](https://bettermeter.com/integrations/vs-code), [Raycast](https://bettermeter.com/integrations/raycast), [v0](https://bettermeter.com/integrations/v0)
- **Frameworks**: [Next.js](https://bettermeter.com/integrations/nextjs), [Nuxt](https://bettermeter.com/integrations/nuxt), [Astro](https://bettermeter.com/integrations/astro), [Remix](https://bettermeter.com/integrations/remix), [SvelteKit](https://bettermeter.com/integrations/sveltekit), [React](https://bettermeter.com/integrations/react), [Vue](https://bettermeter.com/integrations/vue), [Angular](https://bettermeter.com/integrations/angular), [Gatsby](https://bettermeter.com/integrations/gatsby), [WordPress](https://bettermeter.com/integrations/wordpress)
- **Infrastructure & CI/CD**: [Vercel](https://bettermeter.com/integrations/vercel), [Netlify](https://bettermeter.com/integrations/netlify), [GitHub Actions](https://bettermeter.com/integrations/github-actions), [Cloudflare](https://bettermeter.com/integrations/cloudflare), [AWS](https://bettermeter.com/integrations/aws)
- **Monitoring**: [Sentry](https://bettermeter.com/integrations/sentry)
- **Communication**: [Slack](https://bettermeter.com/integrations/slack), [Microsoft Teams](https://bettermeter.com/integrations/microsoft-teams), [Discord](https://bettermeter.com/integrations/discord), [Email](https://bettermeter.com/integrations/email)
- **Project Management**: [Linear](https://bettermeter.com/integrations/linear), [Jira](https://bettermeter.com/integrations/jira), [GitHub Issues](https://bettermeter.com/integrations/github-issues)
- **Data & Automation**: [Zapier](https://bettermeter.com/integrations/zapier), [Make](https://bettermeter.com/integrations/make), [n8n](https://bettermeter.com/integrations/n8n), [BigQuery](https://bettermeter.com/integrations/bigquery), [Google Sheets](https://bettermeter.com/integrations/google-sheets)
- **Backend & E-commerce**: [Express](https://bettermeter.com/integrations/express), [Hono](https://bettermeter.com/integrations/hono), [Shopify](https://bettermeter.com/integrations/shopify), [Webflow](https://bettermeter.com/integrations/webflow)
- [All integrations](https://bettermeter.com/integrations)

## Quick Start

### Track a Website

```html
<script defer data-site="example.com" src="https://bettermeter.com/api/script"></script>
<noscript><img src="https://bettermeter.com/api/pixel?s=example.com" alt="" /></noscript>
```

### Track Custom Events (Web)

```javascript
window.bettermeter.track("signup", { plan: "pro" });
window.bettermeter.identify("user_123");
```

### Track a CLI Tool

```typescript
import { BetterMeter } from "@bettermeter/node";
const bm = new BetterMeter({ siteId: "my-cli", apiKey: "bm_..." });

// Auto-track all Commander.js commands
bm.wrapCommander(program, { version: "1.0.0" });

// Or track manually
bm.trackCommand({
  command: "deploy",
  flags: ["--prod"],
  durationMs: 3400,
  exitCode: 0,
});
```

### Track an MCP Server

```typescript
import { BetterMeter } from "@bettermeter/node";
const bm = new BetterMeter({ siteId: "my-mcp", apiKey: "bm_..." });

// Auto-track all tool invocations (zero code changes to existing tools)
bm.wrapMcpServer(server);

// Or track manually
bm.trackTool({
  tool: "search_docs",
  client: "claude-code",
  durationMs: 250,
  success: true,
});
```

### Track an API

```typescript
import { BetterMeter } from "@bettermeter/node";
const bm = new BetterMeter({ siteId: "my-api", apiKey: "bm_..." });

// Express middleware (one line)
app.use(bm.expressMiddleware());

// Or track manually
bm.trackApi({
  method: "GET",
  endpoint: "/api/users",
  statusCode: 200,
  durationMs: 45,
});
```

## Node SDK — @bettermeter/node

Install: `npm install @bettermeter/node`

Zero dependencies. Requires Node.js 18+.

### Constructor

`new BetterMeter(config)`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| siteId | string | Yes | Domain or identifier registered in BetterMeter |
| apiKey | string | Yes | API key from dashboard (starts with bm_) |
| apiUrl | string | No | API URL. Default: https://bettermeter.com |
| disabled | boolean | No | Disable tracking. Default: false |
| batch | boolean | No | Queue events and flush on interval. Default: false |
| batchInterval | number | No | Flush interval in ms. Default: 5000 |

### Methods

- `trackCommand(opts)` — Track a CLI command invocation
- `trackTool(opts)` — Track an MCP tool invocation
- `trackApi(opts)` — Track an API request
- `wrapCommander(program, opts?)` — Auto-track all Commander.js commands
- `wrapMcpServer(server)` — Auto-track all MCP tool calls on an McpServer instance
- `expressMiddleware()` — Returns Express/Connect middleware for API tracking
- `flush()` — Send all queued events immediately
- `shutdown()` — Stop batch timer and flush. Call before process exit.

### Environment Variables

- `BETTERMETER_DISABLED=1` — Disable tracking globally (useful for tests)

## CLI

Install: `npm install -g bettermeter`

The CLI renders rich visual output by default — ASCII line charts for timeseries, horizontal bar charts for ranked data, sparklines in overview stat cards, and styled tables with box-drawing borders. Colors auto-detect terminal capabilities and respect `NO_COLOR`. Use `--json` for raw JSON output (ideal for scripting or piping to `jq`).

All analytics commands accept: `-s/--site <id>`, `-r/--range <today|7d|30d|90d|12m>`, `-l/--limit <n>`, `--json`.

### Real-Time
- `bettermeter live -s <siteId> [--json]` — Live visitor count

### Authentication
- `bettermeter login -t <apiKey> -u <url>` — Authenticate with API key
- `bettermeter logout` — Remove stored credentials
- `bettermeter whoami` — Show current authenticated user

### Web Analytics
- `bettermeter stats` — Overview: visitors, pageviews, sessions + period-over-period change
- `bettermeter pages` — Top pages by visitor count
- `bettermeter sources` — Traffic sources (--filter all|ai|traditional)
- `bettermeter ai-traffic` — AI referral breakdown by platform
- `bettermeter bots` — Bot/crawler traffic (--category all|ai-crawler|search|monitoring|scraper)
- `bettermeter timeseries` — Daily visitor and pageview trend
- `bettermeter countries` — Visitors by country
- `bettermeter devices` — Device type breakdown
- `bettermeter browsers` — Browser breakdown
- `bettermeter export` — Full analytics report (--format json|csv|md)

### CLI Analytics
- `bettermeter cli-overview` — CLI usage summary: invocations, callers, success rate, avg duration
- `bettermeter cli-commands` — Top CLI commands by invocation count
- `bettermeter cli-timeseries` — CLI daily activity trend

### MCP Analytics
- `bettermeter mcp-overview` — MCP usage summary: invocations, callers, success rate, avg duration
- `bettermeter mcp-tools` — Top MCP tools by invocation count
- `bettermeter mcp-clients` — MCP client breakdown (Claude, Cursor, Windsurf, etc.)
- `bettermeter mcp-timeseries` — MCP daily activity trend

### API Analytics
- `bettermeter api-overview` — API usage summary: invocations, callers, error rate, avg duration
- `bettermeter api-endpoints` — Top API endpoints by invocation count
- `bettermeter api-timeseries` — API daily activity trend

### Brand Monitoring
- `bettermeter brand-report <domain> -q <queries>` — Generate brand visibility report
- `bettermeter brand-config <domain>` — View or update brand monitoring configuration
- `bettermeter brand-compare <domain> -q <queries>` — Compare rankings vs competitors
- `bettermeter brand-alerts <domain>` — Manage brand alert rules (list, create, delete)

### Site Management
- `bettermeter sites list` — List all sites
- `bettermeter sites add <domain>` — Add a new site
- `bettermeter sites remove <siteId>` — Remove a site
- `bettermeter sites info <siteId>` — Show site details and tracking snippet
- `bettermeter install <siteId>` — Get the tracker snippet for a site

### Team Management
- `bettermeter members list -s <siteId>` — List site members
- `bettermeter members add <email> -s <siteId> -r <role>` — Add a member (viewer|editor|admin)
- `bettermeter members remove <memberId> -s <siteId>` — Remove a member
- `bettermeter members update-role <memberId> -s <siteId> -r <role>` — Update member role

## MCP Server

BetterMeter runs as a Model Context Protocol (MCP) server, allowing AI assistants (Claude, Cursor, Windsurf, etc.) to query analytics data directly.

### Setup

Add to your `.mcp.json` or MCP client configuration:

```json
{
  "mcpServers": {
    "bettermeter": {
      "command": "npx",
      "args": ["bettermeter"]
    }
  }
}
```

### Available MCP Tools

#### Real-Time
- `bettermeter_live_visitors` — Get current live visitor count for a site

#### Web Analytics
- `bettermeter_stats` — Overview stats: visitors, pageviews, sessions with period-over-period change
- `bettermeter_pages` — Top pages by visitor count
- `bettermeter_sources` — Traffic sources with AI referral detection
- `bettermeter_ai_traffic` — AI traffic breakdown by platform (ChatGPT, Claude, Perplexity, etc.)
- `bettermeter_bots` — Bot and crawler traffic with category filtering
- `bettermeter_timeseries` — Daily visitor and pageview counts over time
- `bettermeter_countries` — Visitors by country
- `bettermeter_devices` — Device type breakdown (mobile, tablet, desktop)
- `bettermeter_browsers` — Browser breakdown
- `bettermeter_visitors` — List recent visitors with activity summary
- `bettermeter_visitor` — Detailed visitor profile with event timeline
- `bettermeter_events` — Custom events with counts
- `bettermeter_export` — Export full analytics report (JSON or Markdown)

#### CLI Analytics
- `bettermeter_cli_overview` — CLI usage: invocations, callers, success rate, avg duration
- `bettermeter_cli_commands` — Top CLI commands by invocation count
- `bettermeter_cli_timeseries` — CLI daily invocation and caller counts

#### MCP Analytics
- `bettermeter_mcp_overview` — MCP usage: invocations, callers, success rate, avg duration
- `bettermeter_mcp_tools` — Top MCP tools by invocation count
- `bettermeter_mcp_clients` — MCP client breakdown (Claude, Cursor, etc.)
- `bettermeter_mcp_timeseries` — MCP daily invocation and caller counts

#### API Analytics
- `bettermeter_api_overview` — API usage: invocations, callers, error rate, avg duration
- `bettermeter_api_endpoints` — Top API endpoints by invocation count
- `bettermeter_api_timeseries` — API daily invocation and caller counts

#### Site Management
- `bettermeter_sites_list` — List all configured sites
- `bettermeter_sites_add` — Add a new site to track
- `bettermeter_sites_remove` — Remove a site
- `bettermeter_sites_info` — Get site details and tracking snippet
- `bettermeter_install` — Get the tracking snippet to install on a website

#### Team Management
- `bettermeter_members_list` — List all members for a site
- `bettermeter_members_add` — Add a member or send invitation
- `bettermeter_members_remove` — Remove a member
- `bettermeter_members_update_role` — Update a member's role

#### Brand Monitoring
- `bettermeter_brand_report` — Generate brand visibility report across search queries
- `bettermeter_brand_config` — View or update brand monitoring configuration
- `bettermeter_brand_compare` — Compare brand rankings against competitors
- `bettermeter_brand_alerts` — Manage brand alert rules

All analytics tools accept: `site_id` (string), `range` (today|7d|30d|90d|12m), `limit` (1-100).

## API Endpoints

Authenticate with `Authorization: Bearer <api_key>`. All query endpoints accept `?siteId=...&from=YYYY-MM-DD&to=YYYY-MM-DD`.

### Real-Time & Heartbeat
- `GET /api/analytics/live` — Live visitor count. Returns `{ live: number }`. Accepts `?siteId=...`
- `POST /api/heartbeat` — Receive browser heartbeats for live visitor tracking
- `POST /api/h` — Stealth alias for /api/heartbeat (ad-blocker resistant)

### Event Ingestion
- `POST /api/event` — Ingest an event (web, CLI, MCP, or API). Returns 202.

### Web Analytics
- `GET /api/analytics/overview` — Visitors, pageviews, sessions + % change
- `GET /api/analytics/pages` — Top pages by visitor count
- `GET /api/analytics/sources` — Traffic sources with AI detection
- `GET /api/analytics/ai-traffic` — AI referral breakdown by platform
- `GET /api/analytics/bots` — Bot/crawler traffic
- `GET /api/analytics/timeseries` — Daily visitor/pageview trend
- `GET /api/analytics/countries` — Visitors by country
- `GET /api/analytics/devices` — Device type breakdown
- `GET /api/analytics/browsers` — Browser breakdown
- `GET /api/analytics/visitors` — Visitor list with activity
- `GET /api/analytics/visitors/[visitorId]` — Visitor profile
- `GET /api/analytics/events` — Custom events

### CLI Analytics
- `GET /api/analytics/cli-overview` — Invocations, callers, success rate
- `GET /api/analytics/cli-commands` — Top commands
- `GET /api/analytics/cli-timeseries` — Daily CLI activity

### MCP Analytics
- `GET /api/analytics/mcp-overview` — Invocations, callers, success rate
- `GET /api/analytics/mcp-tools` — Top tools
- `GET /api/analytics/mcp-clients` — Client breakdown
- `GET /api/analytics/mcp-timeseries` — Daily MCP activity

### API Analytics
- `GET /api/analytics/api-overview` — Invocations, callers, error rate
- `GET /api/analytics/api-endpoints` — Top endpoints
- `GET /api/analytics/api-timeseries` — Daily API activity

### Brand Monitoring
- `GET /api/analytics/brand` — Brand visibility report
- `GET /api/analytics/brand/history` — Historical brand data
- `GET /api/analytics/brand/compare` — Competitor comparison
- `GET /api/analytics/brand/alerts` — Alert rules
- `GET /api/analytics/brand/export` — Export brand data

### Tracker Script
- `GET /api/script` — Serves the browser tracking script (~1KB IIFE). Includes heartbeat support for live visitor tracking.
- `GET /api/pixel` — Noscript tracking pixel

## Privacy Model

BetterMeter is designed to be privacy-compliant by default:

- **No cookies** — No cookies, local storage, or session storage are used
- **No fingerprinting** — No canvas, WebGL, or font fingerprinting
- **No PII storage** — IP addresses are SHA-256 hashed with a daily-rotating salt. Raw IPs are never stored.
- **Stable visitor IDs** — A separate hash (without date) enables per-site visitor profiles that cannot be reversed
- **CLI/MCP privacy** — Only command/tool names and flag names are tracked. Flag values, arguments, and file paths are never sent.
- **Fire-and-forget** — Analytics SDK failures never break the host application
- **Opt-out** — Set `disabled: true` in SDK config or `BETTERMETER_DISABLED=1` environment variable
- **GDPR compliant** — No consent banner needed. No personal data is collected or stored.

## Proxy Setup (Bypass Ad Blockers)

BetterMeter supports first-party proxying. Configure URL rewrites on your domain:
- `/bm/s` → `https://bettermeter.com/api/s` (tracker script)
- `/bm/e` → `https://bettermeter.com/api/e` (event endpoint)
- `/bm/p` → `https://bettermeter.com/api/p` (noscript pixel)

Platform-specific guides available for Next.js, Nuxt, SvelteKit, Astro, Remix, Nginx, Caddy, Apache, and Rails.

## Docs & Links

- [Documentation](https://bettermeter.com/docs)
- [Getting Started](https://bettermeter.com/docs#getting-started)
- [Web Tracking Guide](https://bettermeter.com/docs#web-tracking)
- [CLI Tracking Guide](https://bettermeter.com/docs#cli-tracking)
- [MCP Server Tracking Guide](https://bettermeter.com/docs#mcp-tracking)
- [API Tracking Guide](https://bettermeter.com/docs#api-tracking)
- [SDK Reference](https://bettermeter.com/docs#sdk-reference)
- [CLI Reference](https://bettermeter.com/docs#cli-reference)
- [MCP Tools Reference](https://bettermeter.com/docs#mcp-tools-reference)
- [API Reference](https://bettermeter.com/docs#api-reference)
- [Proxy Setup](https://bettermeter.com/docs#proxy-setup)
- [Data Model](https://bettermeter.com/docs#data-model)
- [Privacy](https://bettermeter.com/docs#privacy)
- [Features Overview](https://bettermeter.com/features)
- [AI Traffic Attribution](https://bettermeter.com/features/ai-traffic-attribution)
- [Bot & Crawler Analytics](https://bettermeter.com/features/bot-crawler-analytics)
- [CLI Analytics](https://bettermeter.com/features/cli-analytics)
- [MCP Server Analytics](https://bettermeter.com/features/mcp-analytics)
- [API Analytics](https://bettermeter.com/features/api-analytics)
- [Privacy-First Analytics](https://bettermeter.com/features/privacy-first-analytics)
- [Brand Monitoring](https://bettermeter.com/features/brand-monitoring)
- [Extended Documentation for AI](https://bettermeter.com/llms-full.txt)

## Legal

- [Privacy Policy](https://bettermeter.com/privacy)
- [Terms of Service](https://bettermeter.com/terms)
- [Data Processing Agreement](https://bettermeter.com/dpa)

## Comparisons

### BetterMeter vs Google Analytics
Google Analytics uses cookies, requires consent banners, and cannot track CLI tools, MCP servers, or APIs. BetterMeter is cookie-free, GDPR-compliant by default, and tracks all four source types. BetterMeter also detects AI traffic attribution, which Google Analytics does not support.

### BetterMeter vs Plausible / Fathom / Simple Analytics
These tools are privacy-first like BetterMeter, but they only track websites. BetterMeter extends privacy-first analytics to CLI tools, MCP servers, and APIs. BetterMeter also provides AI traffic attribution, bot/crawler analytics, and brand monitoring features that these alternatives lack.

### BetterMeter vs PostHog / Mixpanel
PostHog and Mixpanel are product analytics tools focused on user behavior and funnels. BetterMeter is focused on traffic analytics across four source types (web, CLI, MCP, API) with AI-era features like AI traffic attribution, bot analytics, and brand monitoring. BetterMeter is also simpler and more privacy-focused.

## FAQ

**What is BetterMeter?**
BetterMeter is a privacy-first analytics platform that tracks websites, CLI tools, MCP servers, and APIs. It is designed for the AI-first internet and provides features like AI traffic attribution and bot crawler analytics that traditional analytics tools do not offer.

**How does BetterMeter track AI traffic?**
BetterMeter identifies visitors referred by AI platforms (ChatGPT, Claude, Perplexity, Gemini, Copilot) by parsing referrer headers and user agent strings for known AI platform patterns. This happens automatically for all tracked websites.

**Does BetterMeter use cookies?**
No. BetterMeter uses no cookies, no local storage, and no fingerprinting. It is GDPR compliant by default and requires no consent banner.

**How do I track my MCP server with BetterMeter?**
Install the `@bettermeter/node` SDK, create a BetterMeter instance with your site ID and API key, and call `bm.wrapMcpServer(server)` on your McpServer instance. All tool invocations are automatically tracked with timing and error data.

**Can AI assistants query my BetterMeter analytics?**
Yes. BetterMeter runs as an MCP server. Add it to your AI assistant's MCP configuration and the assistant can query all your analytics data using natural language.

**What data does BetterMeter collect from CLI tools?**
Command names, flag names (not values), version, duration, exit code, OS, and architecture. File paths, arguments, and flag values are never collected.

**Is BetterMeter open source?**
The tracking script and Node SDK are open source. The dashboard and analytics backend are proprietary.