Skip to main content
skill CX Codex

posthog-cost-tuning — Claude Code skill: what it does, how to install

posthog-cost-tuning is a Claude Code skill for PostHog cost analysis: it measures which products drive the bill and trims capture noise without losing events needed for decisions.

MIT 1 installs ★ 2,935 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add jeremylongshore/tons-of-skills-marketplace --skill posthog-cost-tuning -a claude-code
Open on GitHub

What posthog-cost-tuning does

The skill walks the enabled PostHog products, pulls billable volume through HogQL queries against the project query endpoint, and matches a jump in traffic to the instrumentation release behind it. Only what the product owner has already labelled noise or safe to sample gets cut.

Inside you get ordered steps: a 30-day event audit, an autocapture config with DOM-event, element and CSS-selector allowlists, and a before_send hook that keeps purchase and signup events, samples pageviews and drops bot user agents. Session replay gets a 5000 ms minimum and stays off for free accounts, then a monthly projection raises an alert at 0.8 of the approved limit. Tool access is limited to Read, Grep and curl.

You need a PostHog Cloud account with billing access and an app already wired to posthog-js. Private query and billing calls take a least-privilege personal API key or OAuth token kept in a secret manager; without one the HogQL step stops. The browser side uses the public project token only, and the host follows the project, US or EU. Hardcoding prices is a dead end: unit prices and free allowances come from the live dashboard and calculator on every run.

What it helps with

  • find the events eating your monthly quota
  • restrict $autocapture to clicks and form submits
  • filter bot traffic before events leave the browser
  • project end-of-month spend from current usage
  • alert when usage approaches the approved limit

Example prompts for the agent

  • Audit PostHog billable volume for project $POSTHOG_PROJECT_ID and rank the top events from the last 30 days.
  • Tune posthog.init so autocapture tracks clicks and submits only, skipping /admin and /_next.
  • Project this month's event count and warn me at 0.8 of the limit.

How to install posthog-cost-tuning

1Skills CLI (Vercel)

npx skills add jeremylongshore/tons-of-skills-marketplace --skill posthog-cost-tuning -a claude-code

2Manually: put the files in place

~/.claude/skills/posthog-cost-tuning/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/posthog-cost-tuning/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about posthog-cost-tuning

How do I install posthog-cost-tuning in Claude Code?

Run npx skills add jeremylongshore/tons-of-skills-marketplace --skill posthog-cost-tuning -a claude-code. The skill then sits at ~/.claude/skills/posthog-cost-tuning/SKILL.md.

What does posthog-cost-tuning do?

It measures billable volume per PostHog product, ties traffic growth to an instrumentation release, and narrows capture where the data counts as noise or can be sampled safely.

Which credentials does it need?

A PostHog Cloud account with billing access, plus a least-privilege personal API key or OAuth token read from a secret manager. Only the public project token goes to the browser.

Source text

SKILL.md · MIT
---
name: posthog-cost-tuning
description: |
  Reduce PostHog usage cost without silently losing decision-critical data by measuring billable volume, applying product limits, and filtering noise. Use when forecasting spend or responding to a usage spike. Trigger with "PostHog cost", "PostHog billing", or "reduce PostHog usage".
argument-hint: "[project-path] [product-or-budget]"
allowed-tools: Read, Grep, Bash(curl:*)
version: 1.14.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- posthog
- api
- monitoring
- cost-optimization
compatibility: Designed for Claude Code
---
# PostHog Cost Tuning

## Overview

Measure the live billable volume for each enabled PostHog product, trace changes to instrumentation releases, and reduce only traffic that the product owner has classified as noise or safely sampleable. Pricing, free allowances, and product entitlements are live facts; read them from the billing dashboard, pricing calculator, and approved product limits at execution time.

## Prerequisites

- PostHog Cloud account with billing access
- Application instrumented with posthog-js
- Understanding of which events drive your analytics

## Authentication

- Usage inspection through private query and billing APIs requires a least-privilege personal API key or OAuth token on a trusted machine.
- Event capture and browser-side filtering use only the public project token; never ship a personal or secure key to the browser.
- Read private credentials from a secret manager, redact command output before sharing it, and select the private US or EU API host that matches the project.

## Live Pricing Boundary

Do not copy prices or free allowances into implementation code. Record the billing-dashboard timestamp, current product limit, projected usage, unit price from the live calculator, and the owner who approved any data-loss tradeoff. Recheck those values before applying a change.

## Instructions

### Tool discipline

Use `Read` to inspect the relevant configuration and implementation before proposing changes. Use `Grep` to locate initialization, capture, flag, and credential boundaries.

### Step 1: Audit Current Event Volume

```bash
set -euo pipefail
# See which events consume the most quota (last 30 days)
curl "https://us.posthog.com/api/projects/$POSTHOG_PROJECT_ID/query/" \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "kind": "HogQLQuery",
      "query": "SELECT event, count() AS total FROM events WHERE timestamp > now() - interval 30 day GROUP BY event ORDER BY total DESC LIMIT 20"
    }
  }' | jq '.results[] | {event: .[0], count: .[1]}'
```

### Step 2: Tune Autocapture

`$autocapture` is often the largest event volume. Restrict it to only useful interactions.

```typescript
import posthog from 'posthog-js';

posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
  api_host: 'https://us.i.posthog.com',
  autocapture: {
    // Only capture click and submit events (skip change, scroll, etc.)
    dom_event_allowlist: ['click', 'submit'],
    // Only capture meaningful elements
    element_allowlist: ['a', 'button', 'form', 'input[type=submit]'],
    // Only capture elements with this CSS class
    css_selector_allowlist: ['.track-click', '[data-track]'],
    // Skip internal/admin pages entirely
    url_ignorelist: ['/admin', '/health', '/api/internal', '/_next'],
  },
});
```

### Step 3: Event Sampling with before_send

```typescript
posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
  api_host: 'https://us.i.posthog.com',
  before_send: (event) => {
    // 1. Always send business-critical events (no sampling)
    const critical = ['purchase', 'signup', 'subscription_started', 'subscription_canceled', 'error'];
    if (critical.includes(event.event)) return event;

    // 2. Drop bot traffic entirely
    const ua = navigator?.userAgent?.toLowerCase() || '';
    if (/bot|crawler|spider|scrapy|headless|phantom|puppeteer/i.test(ua)) {
      return null;
    }

    // 3. Apply only the sample rate approved for this event class.
    if (event.event === '$pageview') {
      const highTraffic = ['/', '/pricing', '/blog'];
      const url = event.properties?.$current_url || '';
      if (highTraffic.some(p => url.endsWith(p))) {
        return Math.random() < approvedPageviewSampleRate ? event : null;
      }
      return event;
    }

    // 4. Use a separately approved rate for autocapture.
    if (event.event === '$autocapture') {
      return Math.random() < approvedAutocaptureSampleRate ? event : null;
    }

    return event; // Keep all other events
  },
});
```

### Step 4: Optimize Session Recording Costs

```typescript
posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
  api_host: 'https://us.i.posthog.com',
  session_recording: {
    // Load the reviewed rate from configuration; document analysis impact.
    sampleRate: approvedSessionRecordingSampleRate,
    // Don't record sessions shorter than 5 seconds (bounces)
    minimumDurationMilliseconds: 5000,
    // Record 100% of sessions with errors (most valuable for debugging)
    // This is configured in PostHog dashboard under Session Replay settings
  },
});

// Alternatively: disable recording for non-paying users
posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
  api_host: 'https://us.i.posthog.com',
  disable_session_recording: true, // Start disabled
});

// Enable only for paying users
if (user.plan !== 'free') {
  posthog.startSessionRecording();
}
```

### Step 5: Monitor Usage and Set Alerts

```bash
set -euo pipefail
# Check current month's event usage
curl "https://us.posthog.com/api/projects/$POSTHOG_PROJECT_ID/query/" \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "kind": "HogQLQuery",
      "query": "SELECT count() AS total_events, uniq(distinct_id) AS unique_users, count() / dateDiff('"'"'day'"'"', toStartOfMonth(now()), now()) AS events_per_day FROM events WHERE timestamp > toStartOfMonth(now())"
    }
  }' | jq '.results[0] | {
    total_events: .[0],
    unique_users: .[1],
    avg_events_per_day: .[2],
    projected_monthly: (.[2] * 30)
  }'
```

```typescript
// Automated cost monitoring
async function checkPostHogBudget() {
  const result = await queryPostHog(`
    SELECT count() AS events_this_month
    FROM events
    WHERE timestamp > toStartOfMonth(now())
  `);

  const eventsThisMonth = result.results[0][0];
  const approvedMonthlyLimit = Number(process.env.POSTHOG_MONTHLY_EVENT_LIMIT);
  if (!Number.isFinite(approvedMonthlyLimit)) {
    throw new Error('Set POSTHOG_MONTHLY_EVENT_LIMIT from the current billing configuration');
  }
  const projectedMonthly = eventsThisMonth / (new Date().getDate() / 30);

  if (projectedMonthly > approvedMonthlyLimit * 0.8) {
    await sendSlackAlert(`PostHog usage alert: ${Math.round(projectedMonthly)} events projected against reviewed limit ${approvedMonthlyLimit}`);
  }
}
```

## Decision Record

For each proposed filter or sample, record the baseline count, affected event or product, chosen rate, expected analytical limitation, rollback trigger, and measured result after one full review window. Never report generic savings estimates as if they were measured for the target project.

## Error Handling

| Issue | Cause | Solution |
|-------|-------|----------|
| Event volume spike | New feature without volume estimate | Forecast events before launch |
| Bill higher than expected | Bot traffic | Add bot filtering in `before_send` |
| Missing critical events | Sampling too aggressive | Exclude revenue events from sampling |
| Approved product limit reached mid-month | Volume exceeds the reviewed budget | Apply the least destructive approved control and preserve conversion events |

## Output

- Autocapture restricted to meaningful interactions
- Reviewed event-sampling policy with its analytical limitations recorded
- Bot traffic filtered
- Session-recording control derived from the live billing configuration
- Budget monitoring against the approved product limit

## Examples

For an autocapture spike, compare billing-dashboard volume with the release timeline, preserve named conversion events, narrow noisy autocapture, and set a reviewed product limit. Report expected data loss explicitly; do not invent savings percentages.

## Resources

See [official PostHog references](references/official-docs.md) for current authority and verification boundaries.

- [PostHog Pricing](https://posthog.com/pricing)
- [PostHog Autocapture Config](https://posthog.com/docs/product-analytics/autocapture)
- [PostHog before_send](https://posthog.com/docs/libraries/js/config)
- [Session Recording Control](https://posthog.com/docs/session-replay/how-to-control-which-sessions-you-record)

© Jeremy Longshore · MIT · jeremylongshore/tons-of-skills-marketplace

Similar skills

All skills for DevOps and infrastructure →

From the same set139

The whole set →
deepgram-cost-tuning The deepgram-cost-tuning skill outlines ways to track Deepgram spend, set budget checks for transcription, and reduce billable audio time through preprocessing. CX Codex +1 1installs clerk-cost-tuning clerk-cost-tuning — a skill that makes Clerk's MRU pricing concrete and trims the bill: auth only where it is needed, caching around the Backend API, a script for idle accounts. CX Codex +1 1installs lindy-cost-tuning lindy-cost-tuning audits Lindy AI credit usage, downsizes models, and consolidates agent workflows to cut monthly spending. CX Codex +1 1installs evernote-cost-tuning The evernote-cost-tuning skill helps track Evernote upload quotas, estimate note sizes, and spot storage-heavy notes. Use it when an integration needs quota checks before uploading attachments. CX Codex +1 1installs ideogram-cost-tuning ideogram-cost-tuning controls prepaid Ideogram API consumption with admission ceilings, retry limits, and output tracking. Helps teams eliminate wasted spend on failed or duplicate runs. CX Codex +1 1installs coderabbit-cost-tuning The coderabbit-cost-tuning skill reviews CodeRabbit plans, seats, limits, and usage against current billing evidence. Use it to prepare cost scenarios before anyone approves a change. CX Codex +1 1installs firecrawl-cost-tuning firecrawl-cost-tuning traces where Firecrawl credits go and trims the bill through endpoint choice, format discipline, cache policy and spend limits, checked against quality. CX Codex +1 1installs retellai-cost-tuning retellai-cost-tuning optimizes voice agent and telephony expenses on Retell AI. Helps trim phone call budgets while preserving essential human-handoff triggers. CX Codex +1 1installs

Project sponsors

Companies that keep this analytics open