Docs · everything in one place
How to use Irv.
I'm your co-founding data wizard for Lovable apps. I watch what users do, attribute what changed when, and write you a morning brief. This page covers everything end to end. Skim the headings, dive into what you need.
01
What Irv is
Three things rolled together — analytics, AI analyst, code-aware tracking.
- Standard analytics on a HyperLogLog backbone. Sub-50ms year-of-history queries. Visitors / pageviews / sessions / bounce / duration / countries / devices / browsers / OS / languages / UTM / channels / new-vs-returning / hourly distribution / top-clicked elements per page / forms / outbound clicks / JS errors / 404s / scroll depth.
- Daily morning brief written by an AI senior analyst — headline, tl;dr, what moved, ranked priorities (action / expected impact / why-now), EOD watchpoints, continuity from yesterday.
- Code-aware everything. Connect GitHub and I read your repo, derive the tracking plan, comment on your PRs, and pair every commit with the metric movement around it.
You ship via Lovable, I write you the morning analysis. We close the loop.
02
Install
One script tag. Pageviews, clicks, sessions, sources, country, device, browser, OS, language, UTM, screen, forms, scroll, errors, 404s — all autocaptured.
One line, anywhere in your <head>:
<script src="https://irv.dev/i.js?p=pk_live_xxx"></script>
Replace pk_live_xxxwith your project key from the dashboard. That's it — autocapture, sessions, sources, UTM, Web Vitals, all on. Open the page once and your first event lands in /app/<project> within a couple of seconds.
Custom events + identity — the script exposes a global window.irv so you can call:
irv.track("checkout_started", { plan: "pro" });
irv.identify("user@example.com");For production:pin the SDK with Subresource Integrity so a compromised deploy can't run arbitrary code on your customers — see SDK versions + SRI for the pinned snippet (~6 extra chars).
Prefer the npm package? (Next.js / tree-shaking)
npm install @irv/web
import { irv } from "@irv/web";
irv.init({ projectKey: "pk_live_xxx" });Same wire format, same autocapture surface — just imported as ESM. The npm path is the right pick for Next.js (use the helper from @irv/next in the App Router) and any bundled SPA.
03
CLI
Talk to Irv from your terminal. Same MCP endpoint Claude Desktop uses, fourteen commands, read-only and stable across releases. Drop into CI for free dashboards in your build summary.
Install
npm install -g irv-cli
(Beta: package isn't on npm yet. For now, clone the monorepo and npm install && npm run build && npm link inside packages/cli.)
Authenticate
Generate a token at /app/account (same token Claude Desktop uses), then:
irv login --token <your-64-char-hex-token>
Stored at ~/.irv/config.json (chmod 600). Run irv ping to verify.
Pick a default project
irv projects # see your project keys irv use pk_live_xxx # set default — subsequent commands omit <key>
Run things
irv stats --range=30d # headline metrics + top breakdowns irv insights # active AI insights irv outcomes # measured outcomes from shipped insights irv plan # code-derived tracking plan irv log --since=24h # project event log --kinds=commit,prompt_shipped irv causation # correlations + counterfactuals + anomalies irv install pk_live_xxx # print SDK install snippet irv tools # MCP tools the server exposes irv ping # connectivity + auth check
All commands
| Command | What it does |
|---|---|
| irv login [--token <t>] | Save an API token to ~/.irv/config.json |
| irv logout | Clear the saved token |
| irv whoami | Show API URL + token status + default project |
| irv projects | List your projects |
| irv use <key> | Set the default project for subsequent commands |
| irv stats [--range=24h|7d|30d|90d] | Headline metrics + breakdowns |
| irv insights | List active insights |
| irv outcomes | Measured outcomes from shipped insights |
| irv plan | Code-derived tracking plan |
| irv log [--since=24h] [--kinds=...] | Project event log |
| irv causation | Correlations + counterfactuals + anomalies |
| irv install <key> | Print the SDK install snippet |
| irv tools | List MCP tools the server exposes |
| irv ping | Verify connectivity + auth |
CI / automation
The CLI is read-only and stable across releases. A common GitHub Actions one-liner:
- name: Daily Irv summary
run: |
npm install -g irv-cli
echo ${{ secrets.IRV_TOKEN }} | irv login
irv stats --range=24h >> $GITHUB_STEP_SUMMARY
irv log --since=24h --kinds=outcome_evaluated >> $GITHUB_STEP_SUMMARYOverride the API host with IRV_API_URL for self-hosted. Edit ~/.irv/config.json directly to change the saved token, or rerun irv login.
04
Claude Desktop (MCP)
Add Irv as a Model Context Protocol server in Claude Desktop. Then ask Claude conversational questions about your project — it'll call my tools to fetch real numbers and return tool-driven answers.
1 · Generate an MCP token
At /app/account, click Generate token. 64 hex chars. Save it once — we hash it server-side, so we can't show it again.
2 · Add Irv to Claude Desktop
Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your OS, then add an irv entry under mcpServers:
{
"mcpServers": {
"irv": {
"url": "https://irv.dev/api/mcp",
"headers": {
"Authorization": "Bearer mcp_<your-64-char-hex-token>"
}
}
}
}Restart Claude Desktop. The MCP indicator (lower right) should turn green and Irv's tools become available in the model picker.
3 · Ask things
A few prompts that work well:
- “What's the highest-priority fix on my SaaS this week?”
- “Why did /pricing bounce go up?”
- “Which channel converts best on signup?”
- “Compare last week vs the week before — what changed?”
- “Show me everything weird in the project log.”
Tools the MCP exposes
| Tool | Returns |
|---|---|
| get_stats | Headline metrics + WoW deltas + top dimensions |
| get_top_dimension | Top pages / sources / countries / etc |
| get_insights | Active AI insights with confidence + ranked causes |
| get_outcomes | DiD lift + bootstrap CI for shipped insights |
| get_change_effects | Commits + shipped prompts paired with metric movement |
| get_engagement | Outbound clicks / forms / errors / 404s / scroll |
| get_audience | Channels + new-vs-returning + hourly distribution |
| get_project_log | Filterable timeline of every project event |
| get_tracking_plan | Code-derived plan + tracking-debt grade |
| get_causation | Correlations + Granger + DiD + anomalies |
Run irv tools to list the live MCP tool surface against any deployment. The endpoint speaks JSON-RPC 2.0 — usable from any MCP client, not just Claude Desktop.
03
What I watch (autocapture)
The SDK captures these without you writing any tracking code. They power every breakdown in the dashboard.
Pageviews, SPA navigation, sessions, entry / exit pages, bounce rate, time-on-page.
Tag, text, href, page path. Outbound link clicks get a separate$click_outbound event with the destination host.
$form_submit fires on every submission with form id / name / action / field counts. Never field VALUES (PII protection).
$scroll_milestone at 25 / 50 / 75 / 100% reached, once per pageview, throttled.
$error for both sync throws and unhandled promise rejections, with truncated stack.
$page_not_found via heuristic (title / H1 patterns, body[data-irv-404]) or explicit irv.notFound() call.
Initial referrer per session, classified into Direct / Search / Social / Email / Paid / Referral. Plus utm_source / medium / campaign / term / content from URL params.
Server-side UA parse on every event: device class / browser / OS / language / screen / viewport. No client-side fingerprinting.
04
What I tell you
Three AI-written surfaces, three cadences. All written in senior-analyst voice — specific, honest about what didn't work, no fluff.
Daily morning brief
top of dashboardSix sections: headline (subject-line quality) · tl;dr (2-3 sentences) · what moved (ranked metric movements with cause + confidence) · top priorities (3 items: action / expected impact / why-now) · watching (1-2 EOD checkpoints with thresholds) · continuity (callback to yesterday).
Generated daily at your project's morning hour, ~$0.05 per run. Click Generate on the dashboard to refresh on demand.
Insight cards
3-7 per refreshShort, actionable cards alongside the brief. Each has a confidence badge, a ranked top-3 candidate causes panel (for change_attribution + anomaly types), and a paste-ready Lovable prompt to ship the fix.
Categories: drop_off · page_improvement · tracking_gap · source_attribution · change_attribution · anomaly. Dismissed insights stay dismissed for 7 days; the AI learns from what you copy.
Weekly executive narrative
Saturday morningSix paragraphs of prose: state of the business · what worked · what didn't · where to look next · recommendations · metric to watch. Honest. Names cohorts. Attributes revenue in dollars where possible.
POST /api/v1/weekly-narrative?project_key=…&send=1 to generate + email manually. Add ?send=1 to deliver via Resend.
05
What I measure
The trust layer — every claim is auditable. Numbers come from rollups, verdicts come from real statistics.
Change-effects log
Every commit, shipped prompt, and tracking-plan change auto-paired with the [-3d, +3d] before/after metric delta. Verdict: positive / negative / inconclusive (within ±5% noise band). Confidence scales with magnitude × sample size. One-sentence rationale you can audit.
Tracking-debt index
Lighthouse-style 0-100 score with A/B/C/D/F grade. Three weighted components: form coverage (40%) · declared events firing in last 30d (30%) · top-clicked elements matching tracked events (30%). Surfaces severity-sorted gaps with snake_case event-name suggestions. Updates on every push to main.
Outcomes (shipped insights)
When you click Ship-to-AI, I snapshot the cited metrics at ship-time. Seven and fourteen days later, I run difference-in-differences vs auto-picked control pages. Bootstrap 95% CI from 1000 day-resamples. Synthetic control fit via projected gradient descent. The verdict is a real lift estimate, not a hand-wave.
Causation discovery
Pairwise Pearson + Spearman with lag scan. Benjamini-Hochberg FDR-corrected p-values. Granger causality F-test for directional pairs. STL trend + seasonal decomposition for anomalies (residuals beyond 3σ flagged). The AI only narrates findings that already passed significance.
08
Canvas — freeform investigation board
Drop metrics, pages, cohorts, and shipped commits onto a freeform board. Shift + drag between two widgets and Irv writes the analytical interpretation onto the line.
Mental model
Most analytics tools are single-question UIs (one chart, one funnel). The Canvas is multi-question by design — the line is the question. Drop two metrics, connect them, see Pearson + p-value. Drop a cohort + a page, connect them, see conditional behavior. Drop a commit + a metric, connect them, see the [-3d, +3d] DiD-ish lift.
Interactions
- Drag a widget to move it.
- Shift + drag between two widgets to connect them. Irv runs the right statistical test and writes the result on the line.
- Space + drag to pan the whole canvas; ⌘ + wheel to zoom; +/-/0 keyboard shortcuts.
- Backspace / Delete on a selected widget removes it (and its connections).
- Click a connection's pill to delete that edge.
Magic Wand
Toggle the Wand button, click multiple widgets to multi-select, then click Analyze N. Irv writes a 2-4 sentence senior- analyst summary tying the selected widgets together, drops it as asummary widget connected to each of them. ~2-5¢ per analysis.
Templates
Three starter investigations available from the empty-state picker: Pricing investigation, Signup deep-dive,Revenue cohort spread. Each materializes against your live 30d analytics so the connection labels are populated on first load.
Public sharing
Share button in the toolbar → toggle on → get/canvas/<slug>. Read-only. Numbers frozen at share time. Send the URL to investors / co-founders / customers and the interpretation prose Irv wrote travels with the share.
Drop things from elsewhere in the app
Look for + canvas pills throughout the app — Daily Brief priorities, Change-effects rows, Top pages list, Causation correlations. Each click queues that widget seed; the canvas page shows a pending-items pill to drop them onto a fresh board.
09
Dashboard tour
Top to bottom, what you'll see at /app/{your-project}.
- Range picker. 24h / 7d / 30d / 90d. Everything below re-queries when you change it. Sub-50ms.
- Morning brief. The AI senior-analyst writeup of yesterday. See What I tell you.
- Insights. 3-7 short cards with confidence badges + ranked causes + Ship-to-AI button.
- What worked. Past insights that shipped + their measured 7d / 14d lift via DiD. Color-tinted by verdict.
- What changed → what happened. Every commit / shipped prompt / plan change in the last 30d, auto-paired with the metric movement around it.
- Headline metric cards. Visitors / Pageviews / Sessions / Avg duration / Bounce rate, each with WoW delta + sparkline.
- Time series chart. Visitors + pageviews per hour/day across the range.
- Top sources. Initial referrer per session, classified to host.
- Breakdowns panel — tabbed, 9 dimensions: Pages · Entry/Exit · Sources · Countries · Devices · Browsers · OS · Languages · UTM · Audience (channels + new-vs-returning + hourly heatmap) · Engagement (outbound clicks · form submits · JS errors · 404s · scroll depth + top clicked elements per page).
- Metric freshness + Tracking debt.Side-by-side. Stale badge if cron hasn't run in 36h. Tracking-debt grade + top gaps with file:line refs.
- Funnel builder. Custom multi-step funnels. Steps can be event names or page paths (prefix with
/). - Recent events. Live tail of the raw event stream.
07
Connect GitHub
Unlocks code-aware tracking, change attribution, the PR-bot, and the tracking-debt index.
From /app/<project>/settings: click Connect GitHub. The next screen at /app/connect/github lets you pick the OAuth scope:
- Public repos only (
public_repo, recommended) — the right pick if your app lives in a public Lovable / Bolt / Replit project. - All repos (
repo) — needed only if your project code is in a private repository. Picks up private code; nothing else changes.
After OAuth, pick the repo to link. I'll register a webhook on the default branch. (Per-repo GitHub-App installations are next on the roadmap — that'll replace the scope picker with explicit repo-by-repo grants.)
What I do once it's connected:
- Read the repo on every push, regex-derive the tracking plan, diff against the prior version, surface added/removed events.
- Re-run the AI analysis with code context (recent commits + key file contents).
- Pair every commit with the metric movement around it (change-effects).
- Comment on every PR with predicted impact + tracking suggestions (see PR-review bot below).
- Score your tracking-debt index based on what's declared in code vs what's firing live.
08
Connect Stripe
Tie real revenue into the analytical path. MRR, ARPU, churn, plan changes — all joined to your identity graph.
From /app/<project>/settings: click Connect Stripe, OAuth, pick the account. I'll register a webhook for invoice + customer + subscription events.
Make sure your app calls irv.identify(email) at signup so I can join Stripe customers to event sessions. Then the daily brief can attribute revenue lift to specific shipped prompts.
09
PR-review bot
I comment on every PR with the analytics impact — high-traffic page touches, tracking suggestions, removed-track warnings, past insights touching the same files, what I'll be watching after merge.
Auto-enabled once GitHub is connected. The bot runs on opened, synchronize, reopened, ready_for_review events. Drafts are skipped. PRs with no actionable signals get no comment (no spam).
On subsequent pushes, the bot updates the same comment in place (identifies it via a magic marker line) — your PR doesn't fill with stale Irv comments.
# To opt out of a single PR, reply with: @irv ignore
13
Daily emails + weekly narrative
Yesterday's headline numbers + top insights every morning. A six-paragraph executive narrative every Saturday. Sent via Resend.
Setup
- Open /app/account → toggle Send digests on, set the email address + hour (UTC), pick daily or weekly.
- Click Save preferences. Irv sends a test email immediately so you can confirm the delivery + see what the format looks like.
- Real digests follow your schedule from the next morning on.
What's in a daily digest
- Yesterday's headline metrics + WoW deltas
- Prompts shipped + outcomes measured
- Up to 3 highest-severity active insights
- Tracking-plan changes (events added / removed)
- Stripe revenue events when connected
What's in the weekly narrative
Six prose sections — state of the business · what worked · what didn't · where to look next · recommendations · metric to watch. Sent Saturdays. Honest, specific, no corporate fluff.
14
Send feedback
There's a floating Feedback button bottom-right on every page when you're signed in. Bugs, ideas, praise, complaints — all welcome.
- Tap the pill → modal opens with a category picker (bug · idea · praise · other) and a text field.
⌘ + ↵to send. - Every submission lands in the creator's inbox. I read every one. If there's something worth replying to, I do.
- The path you were on when you submitted is captured automatically so I know which screen the feedback is about. No clicks, network requests, or input contents from other parts of your session are included.
- Rate-limited to 10 submissions per hour per user (in case the button gets clicked by accident).
11
How to read me
Two voices, used deliberately. Knowing which is which makes the brief easier to skim.
When I sound like an analyst
Daily brief body, insight cards, weekly narrative. Tight, specific, honest. I distinguish observation from hypothesis: declarative voice for what I measured, “I'd check whether…” / “It looks like…” for guesses. I acknowledge uncertainty plainly. I never invent numbers — if I don't have visibility, I say so.
When I sound like a co-founder
Headers, openers, empty states, errors, marketing copy. Calm. Spare warmth. First-person with a perspective. The partnership is “we”, the work is “I”. Permission to push back when I think you shouldn't ship something yet.
12
Privacy
What I store, what I don't, who can see it.
- No IPs stored. Country comes from the edge geo header and is bucketed at write time.
- No form values captured. Form submits track field counts only — never the actual input contents.
- 30-day raw retention. Per-day rollups (HLL + counters) live longer for trend queries.
- No PII in AI prompts. The identity graph stays server-side; the daily-brief / insights pipeline only sees aggregates + metric refs.
- GDPR-aware. Cookies are first-party only. The SDK respects Do-Not-Track when set.
- See the full privacy notice for the legal version.