Introduction

Poolstatis is source-available, agent-first product analytics for teams that use coding agents to ship software. Instead of expecting a person to translate dashboards or write SQL, it gives an agent a small MCP surface for registering metrics, defining funnels, and asking whether a shipped change is working. The registry preserves meaning: every metric states the decision it supports, every funnel states the journey it measures, and clients query those registered definitions through a typed DSL. Humans retain control through a review workspace that exposes proposals, activation status, keys, recent data, and quality warnings. Teams can use the managed Cloud beta or run a Docker self-host with Postgres and a local MCP runner. The pinned public @poolstatis/mcp@0.7.0 runner and @poolstatis/sdk@0.4.0 analytics package are available on npm; the replay package boundary is documented below. Poolstatis reports observed product behavior. A trend or conversion change can guide investigation, but it does not by itself prove that a release caused the outcome.

Two rules hold the whole system together:

Every metric carries a purpose — one sentence naming the decision it informs. Every funnel carries a goal — what journey it measures and why.

If you can't name the decision a number informs, you don't track it. That single constraint is what makes an agent's analytics trustworthy instead of noise.

Why it exists#

Traditional analytics assume a person is sitting in front of a chart. An agent can write a feature, ship it, and open the PR — but then it goes blind, because the feedback half of the loop (ship → measure → decide) lives behind a SQL console and a dashboard UI.

Poolstatis closes that loop. The agent works through a small, typed surface instead of raw SQL, and every number is self-describing.

How it fits together#

• Ingest API receives events and entity updates from your product.
• Registry holds the semantic layer: metrics (with a purpose) and funnels (with a goal).
• Query DSL answers questions over registered metrics — never raw tables.
• MCP server exposes all of the above as tools your agent calls.
• Admin panel is a review workspace for people to audit and activate.

When Poolstatis fits#

• A coding agent instruments product changes and needs to verify the result after release.
• A product team wants stable metric definitions that both humans and agents can inspect.
• A self-hosting team wants event data and the semantic registry in its own Postgres.
• An MCP client needs narrow analytics tools instead of database or raw SQL access.

Poolstatis is not a replacement for data warehousing, unrestricted BI, or LLM trace observability. Browser Experience is an optional immediate interaction signal. Privacy-safe Session Replay is a separate explicit-consent module with its own storage, retention, and playback boundary.

What ships today#

• Manual capture: Browser, Node, and HTTP integrations send named events and entity updates.
• Browser and session analytics: page views, visitors, sessions, foreground engagement, bounce, routes, and bounded acquisition dimensions are available through REST, MCP, SDK, and the human analysis workspace.
• Labelled click autocapture: after Browser Experience starts, it observes clicks carrying a developer-owned data-poolstatis-label, normalized click coordinates, scroll milestones, registered section exposures, and coarse error or unhandled_rejection signals.
• Interaction evidence: bounded click and scroll maps plus a per-session interaction timeline show labelled behavior without loading the replay recorder.
• Privacy-safe Session Replay: current Core records sanitized rrweb full snapshots, DOM mutations, finite navigation and viewport context, click, scroll, and pointer movement only after versioned consent and exact-host approval. Playback runs in a scriptless sandbox; retention defaults to 7 days and is bounded to 1–30 days.
• Published replay entrypoint: @poolstatis/sdk@0.4.0 exposes the separate opt-in @poolstatis/sdk/replay module; consent and exact-host policy remain mandatory.
• Answer-first analysis: built-in graphs and tables cover trends, funnels, retention, lifecycle, stickiness, entities, Web analytics, and session evidence. The UI is not a general dashboard builder.
• Historical data controls: previewed, idempotent historical imports and audited optimistic event corrections preserve batch and revision history.

Poolstatis deliberately does not claim broad arbitrary-DOM analytics-event autocapture, screen video, full error tracking, or feature parity with a wider analytics suite. See Session Replay and the source-backed Poolstatis vs PostHog comparison for the exact shipped and excluded boundary.

Agent-first vs dashboard-first analytics#

Next: Quickstart.