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.
Instrucciones de origen · Vista previa de solo lectura
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.
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.
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 — 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 and generate a key from the dashboard. Alternatively, self-host the open-source version from GitHub.
If the project doesn't have tracking yet:
# 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 — use it as in the snippet below. This is separate from your API key (which is for reading/querying).
project write token
data-token
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.
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.
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
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.
--window <N> — conversion window in hours (funnel, default: 168) or live time window in seconds (live, default: 60)
--count-by <field> — user_id or session_id (funnel only)
--breakdown <key> — segment funnel by a property (e.g. country, variant) — extracted from step 1 events (funnel only)
--breakdown-limit <N> — max breakdown groups, 1-50 (funnel, default: 10)
--interval <N> — live refresh in seconds (default: 5)
The live command
npx @agent-analytics/cli live opens a real-time TUI dashboard that refreshes every 5 seconds. It shows active visitors, sessions, and events/min across all your projects, plus top pages and recent events. Note: this is an interactive terminal UI — it clears the screen on each refresh, so it works best when run directly in a terminal rather than captured as output.
Which endpoint for which question
Match the user's question to the right call(s):
User asks
Call
Why
"How's my site doing?"
insights + breakdown + pages (parallel)
Full weekly picture in one turn
"Is anyone visiting right now?"
live
Real-time visitors, sessions, events across all projects
"Is anyone visiting?"
insights --period 7d
Quick alive-or-dead check
"What are my top pages?"
breakdown --property path --event page_view
Ranked page list with unique users
"Where's my traffic coming from?"
breakdown --property referrer --event page_view
Referrer sources
"Which landing page is best?"
pages --type entry
Bounce rate + session depth per page
"Are people actually engaging?"
sessions-dist
Bounce vs engaged split
"When should I deploy/post?"
heatmap
Find low-traffic windows or peak hours
"Give me a summary of all projects"
live or loop: projects then insights per project
Multi-project overview
"Which CTA converts better?"
experiments create + implement + experiments get <id>
Full A/B test lifecycle
"Where do users drop off?"
funnel --steps "page_view,signup,purchase"
Step-by-step conversion with drop-off rates
"Which variant converts better through the funnel?"
For any "how is X doing" question, always call insights first — it's the single most useful endpoint. For real-time "who's on the site right now", use live.
Analyze, don't just query
Don't return raw numbers. Interpret them. Here's how to turn each endpoint's response into something useful.
/insights → The headline
API returns metrics with current, previous, change, change_pct, and a trend field.
How to interpret:
change_pct > 10 → "Growing" — call it out positively
change_pct between -10 and 10 → "Stable" — mention it's steady
change_pct < -10 → "Declining" — flag it, suggest investigating
bounce_rate current vs previous → say "improved" (went down) or "worsened" (went up)
avg_duration → convert ms to seconds: Math.round(value / 1000)
Previous period is all zeros → say "new project, no prior data to compare"
Example output:
This week vs last: 173 events (+22%), 98 users (+18%).
Bounce rate: 87% (up from 82% — getting worse).
Average session: 24s. Trend: growing.
/breakdown → The ranking
API returns values: [{ value, count, unique_users }] sorted by count DESC.
How to interpret:
Top 3-5 values is enough — don't dump the full list
Show the unique_users too — 100 events from 2 users is very different from 100 events from 80 users
Use total_with_property / total_events to note coverage: "155 of 155 page views have a path"
For referrers: group "(direct)" / empty as direct traffic
Example output:
Top pages: / (98 views, 75 users), /pricing (33 views, 25 users), /docs (19 views, 4 users).
The /docs page has high repeat visits (19 views, 4 users) — power users.
bounce_rate > 0.7 → "high bounce, needs work above the fold"
bounce_rate < 0.3 → "strong landing page"
avg_duration → convert ms to seconds; < 10s is concerning, > 60s is great
avg_events → pages/session; 1.0 means everyone bounces, 3+ means good engagement
Compare pages: "Your /pricing page converts 3× better than your homepage"
Example output:
Best landing page: /pricing — 14% bounce, 62s avg session, 4.1 pages/visit.
Worst: /blog/launch — 52% bounce, 18s avg. Consider a stronger CTA above the fold.
/sessions/distribution → Engagement shape
API returns distribution: [{ bucket, sessions, pct }], engaged_pct, median_bucket.
How to interpret:
engaged_pct is the key number — sessions ≥30s as a percentage of total
engaged_pct < 10% → "Most visitors leave immediately — focus on first impressions"
engaged_pct 10-30% → "Moderate engagement, room to improve"
engaged_pct > 30% → "Good engagement"
If 80%+ is in the "0s" bucket, the site has a bounce problem
If there's a healthy spread across buckets, engagement is genuine
Example output:
88% of sessions bounce instantly (0s). Only 6% stay longer than 30s.
The few who do engage stay 3-10 minutes — the content works, but first impressions don't.
peak is the single busiest slot — mention day + hour + timezone caveat (times are UTC)
busiest_day → "Schedule blog posts/launches on this day"
busiest_hour → "This is when your audience is online"
Low-traffic windows → "Deploy during Sunday 3 AM UTC to minimize user impact"
Weekend vs weekday split → tells you if audience is B2B (weekdays) or B2C (weekends)
Example output:
Peak: Friday at 11 PM UTC (35 events, 33 users). Busiest day overall: Sunday.
Traffic is heaviest on weekends — your audience browses on personal time.
Deploy on weekday mornings for minimal disruption.
/funnel → Where users drop off
CLI: funnel my-site --steps "page_view,signup,purchase". API: POST /funnel with JSON body.
API returns steps: [{ step, event, users, conversion_rate, drop_off_rate, avg_time_to_next_ms }] and overall_conversion_rate.
How to interpret:
Each step shows how many users progressed from the previous step
conversion_rate is step-to-step (step 2 users / step 1 users)
drop_off_rate is 1 - conversion_rate at each step
The biggest drop_off_rate is the bottleneck — focus optimization there
avg_time_to_next_ms shows how long users take between steps (convert to hours/minutes)
overall_conversion_rate is end-to-end (last step users / first step users)
--window <hours> — max time from step 1 to last step (default: 168 = 7 days)
--since <days> — lookback period, e.g. 30d (default: 30d)
--count-by <field> — user_id (default) or session_id
--breakdown <property> — segment funnel by a property (e.g. country, variant). Property is extracted from step 1 events. Returns overall + per-group results.
--breakdown-limit <N> — max groups returned (default: 10, max: 50). Groups ordered by step 1 users descending.
Breakdown use case — A/B experiments:funnel my-site --steps "page_view,signup" --breakdown variant shows which experiment variant converts better through the funnel.
API-only: per-step filters — each step can have a filters array with { property, op, value } (ops: eq, neq, contains). Example: filter step 1 to path=/pricing to see conversions from the pricing page specifically.
Example output:
page_view → signup → purchase
500 users → 80 (16%) → 12 (15%) — 2.4% overall
Biggest drop-off: page_view → signup (84%). Focus on signup CTA visibility.
Avg time to signup: 4.2 hours. Avg time to purchase: 2.1 days.
/retention → Are users coming back?
CLI: retention my-site --period week --cohorts 8. API: GET /retention?project=X&period=week&cohorts=8.
By default uses session-based retention — a user is "retained" if they have any return visit (session) in a subsequent period. Pass --event to switch to event-based retention.
API returns cohorts: [{ date, users, retained: [...], rates: [...] }], average_rates: [...], and users_analyzed.
How to interpret:
Each cohort row = users who first appeared in that period
rates[0] is always 1.0 (100% — the cohort itself)
rates[1] = % who came back the next period — this is the critical number
Declining rates across offsets is normal; the slope matters more than absolutes
average_rates is weighted by cohort size — larger cohorts count more
Compare recent cohorts vs older ones: improving rates = product is getting stickier
Options:
--period <P> — day, week, month (default: week)
--cohorts <N> — number of cohort periods, 1-30 (default: 8)
Use arrows: ↑ up, ↓ down, — flat. Flag anything that needs attention.
Anomaly detection
Proactively flag — don't wait to be asked:
Spike: any metric >2× its previous period → "unusual surge, check referrers"
Drop: any metric <50% of previous → "significant decline, worth investigating"
Dead project: zero page_view events → "⚠ no traffic detected"
Errors: any error events in the window → surface the message property
Visualizing results
When reporting to messaging platforms (Slack, Discord, Telegram), raw text tables break. Use companion skills:
table-image-generator — render stats as clean table images
chart-image — generate line, bar, area, or pie charts from analytics data
Growth Playbook — How to grow, not just track
Tracking is step one. Growth comes from a repeatable system: clear messaging → focused distribution → obsessive tracking → rapid experimentation → learning. Here's how to apply each principle using Agent Analytics.
Principle 1: Promise clarity
The #1 conversion lever is messaging. If someone lands and has to think hard to understand the value, they're gone.
What your agent should do:
Set up an A/B experiment on the hero headline immediately: experiments create PROJECT --name hero_headline --variants control,b,c --goal cta_click
Test 2-3 headline variations that frame the same value differently
Use declarative HTML: data-aa-experiment="hero_headline" data-aa-variant-b="New headline"
Check results after ~500 visitors per variant: experiments get EXP_ID
Ship the winner, start testing the subtitle or CTA next
Rule: Spend more time testing messaging than adding features. Even the best product won't convert if the value isn't obvious in seconds.
Principle 2: Track what drives decisions, not everything
Don't be Mixpanel. Track only what answers: "Is this project alive and growing, and what should I do next?"
The essential events (pick 3-5):
Event
What it tells you
cta_click (with id)
Which buttons drive action — your conversion signal
signup
Are people converting? At what rate?
feature_used (with feature)
Are they finding value after signup?
checkout
Revenue signal
Agent workflow for tracking setup:
Look at the site — identify the 2-3 most important user actions
Add tracking on those specific actions (not everything)
Verify with events PROJECT that data flows
Set up a weekly check: insights PROJECT --period 7d
Anti-pattern: Don't track scroll depth, mouse hovers, every link click, or form field interactions. Noise kills signal.
Principle 3: Find the activation moment
Conversion doesn't happen at checkout. It happens when the user realizes the product solves their problem — the "aha moment."
How to find it:
Track key feature interactions: feature_used with specific feature names
Use breakdown --property feature --event feature_used to see which features correlate with retention
Check sessions-dist — if most sessions are 0s bounces, the landing page is the problem. If sessions are long but signups are low, the activation path is the problem
Use pages --type entry — compare bounce rates across landing pages to find which first impression works
What to optimize:
Time to first value — how fast does the user get a result?
Onboarding friction — where do users drop off?
Feature discovery — are users finding the thing that makes them stay?
Principle 4: One channel, iterate relentlessly
Don't try to be everywhere. Pick one acquisition channel and go deep.
How Agent Analytics supports this:
breakdown --property referrer --event page_view → see where traffic actually comes from
