Poolstatis

Agent-native product analytics. Poolstatis is a lightweight PostHog-style
analytics system whose primary user is a coding agent over MCP, not a human
clicking through dashboards.

The core idea is that metrics are created with semantics from the start. Every
metric has a required purpose, and every funnel has a goal, so
instrumentation can be inspected, maintained, and queried by agents instead of
living as unnamed event clutter.

Source Available

Poolstatis is source-available under the
PolyForm Shield License 1.0.0. You can read, run, and modify the
software for permitted use cases, but you cannot sell Poolstatis as a competing
product or offer it as a competing hosted or managed service.

See CONTRIBUTING.md, SECURITY.md, and the
source-available release checklist for
project rules and release hygiene.

This repository contains the system itself: backend, ingest API, MCP server,
SDK, headless admin SPA, migrations, technical docs, and Docker self-hosting.
The marketing site, public docs UI, waitlist, and future Cloud-only code live in
separate repositories.

How It Works

1. A coding agent instruments a product and registers metrics in Poolstatis
   through MCP.
2. The product sends events and entities to the HTTP ingest API.
3. Poolstatis stores the data and exposes typed query tools, so the customer can
   build dashboards, checks, and insights in their own environment.

Documentation

Local Development

docker compose up -d
pnpm install
pnpm migrate
pnpm bootstrap "Poolstatis" poolstatis "Local project"
pnpm serve
pnpm --dir web dev

Run backend and shared-logic checks before opening a PR:

pnpm typecheck && pnpm test

Run the admin build before shipping UI changes:

pnpm --dir web build

Self-Host In 3 Commands

docker compose -f docker-compose.selfhost.yml up -d --build
curl http://localhost:3300/health
docker compose -f docker-compose.selfhost.yml run --rm poolstatis \
  node dist/cli/bootstrap.js "Acme" acme "Acme Product"

Then open http://localhost:8080 and paste the printed sk_ or pt_ token.
See the full self-hosting guide in docs/10-self-host.md.

Hosted Setup

1. Open the hosted admin and create the first project in onboarding.
2. Save the one-time pt_ token for the MCP client and pk_ token for ingest.
3. Add Poolstatis as an MCP server in Claude Code, Claude Desktop, Codex,
   Cursor, Warp, Windsurf, VS Code/Copilot, Cline, Zed, Continue, Replit,
   OpenCode, Hermes-style launchers, or any compatible custom MCP host.

{
  "mcpServers": {
    "poolstatis": {
      "command": "pnpm",
      "args": ["--silent", "dlx", "@poolstatis/mcp"],
      "env": {
        "POOLSTATIS_URL": "https://api.poolstatis.com",
        "POOLSTATIS_TOKEN": "pt_..."
      }
    }
  }
}

--silent is required because pnpm can print a banner to stdout, which breaks
the stdio MCP protocol.

Until @poolstatis/mcp is published, treat the JSON above as the publish-ready
template. Hosted deployments should expose copy-paste setup only after the real
MCP runner command and arguments are configured.

Send product events through the ingest API:

curl -X POST https://api.poolstatis.com/i/v1/events \
  -H 'Authorization: Bearer pk_...' \
  -H 'content-type: application/json' \
  -d '{"events":[{"event":"signup.completed","distinct_id":"u1"}]}'

Platform Admin

web/ is a minimal headless platform admin. It is not a per-project analytics
dashboard; customers consume analytics through MCP, SDK integrations, or their
own dashboards.

The admin includes tables for projects, metric registry management, data health,
events, entities, API keys, onboarding, and Setup & MCP presets. In hosted mode,
human login is handled through Auth0/OIDC, while scoped Poolstatis keys remain
the runtime access model:

• pk_ ingest keys are write-only and safe for product clients.
• sk_ secret keys provide project-level platform access.
• pt_ personal tokens provide organization-wide MCP access.

Status

Implemented:

• HTTP ingest API
• Semantic metric registry
• Funnels
• Entities
• Query DSL for trend, funnel, entities, retention, lifecycle, and
  stickiness
• Deterministic feature flags, automatic exposure events, and Bayesian A/B
  experiment results over registered metrics
• MCP server with typed tools and resources
• Headless admin SPA
• Instrumentation standard
• Agent instrumentation skill
• Docker Compose self-hosting path

Next priorities are tracked in docs/05-gap-analysis.md:
actor merge and identity, static cohorts, funnel correlation, Browser Experience
signals/interaction maps, and a privacy-gated Session Replay add-on.