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. A versioned poolstatis.yml connects a product hypothesis to registered metrics.
4. CI registers the deployed commit; Poolstatis monitors the fixed evidence window and proposes keep, fix, rollback, or inconclusive from trusted facts.
5. A human approves or corrects the decision before any prepared action can execute.

Documentation

Document	What it covers
ARCHITECTURE.md	System overview, components, and principles
docs/01-data-model.md	Tenancy, data types, and table schemas
docs/02-storage.md	Storage design and the Postgres-to-ClickHouse path
docs/03-mcp-server.md	MCP server tools and resources
docs/04-http-api.md	Ingest and Query API
docs/05-gap-analysis.md	Current scope versus PostHog and next priorities
docs/06-instrumenting-a-product.md	Agent and manual instrumentation workflow
docs/07-vps-deployment.md	Deploying the Platform API, MCP, SDK, and skills
docs/09-source-available-release.md	Source-available release and GitHub hygiene
docs/09-product-decision-loop.md	Contracts, releases, evidence, approvals, workers, actions, outbox, and decision memory
docs/10-self-host.md	Short Docker Compose self-hosting path
docs/11-repository-split.md	System, site, and Cloud repository boundaries
docs/12-mcp-package-release.md	Public MCP package release and provenance gates
sdk/README.md	@poolstatis/sdk client usage
.claude/skills/poolstatis-instrument	Agent skill for product instrumentation

Local Development

docker compose up -d
pnpm install
pnpm build
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. Choose an analytics job and optional product outcome; onboarding generates one project/environment-scoped agent request without embedding either token.
4. 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.

The JSON below is the verified Claude MCP shape. Setup & MCP renders Codex as config.toml; for other hosts it shows generic stdio command, args, and env fields instead of pretending every client accepts Claude JSON.

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

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

The public runner is version-pinned so a hosted deploy cannot silently change its MCP runtime. @poolstatis/[email protected] includes the production browser analytics standard: immediate collection, finite route keys, server-derived country, bounded legacy SDK compatibility, and the existing historical-data and audited-correction tools. Each release remains fail-closed until its exact registry artifact passes fresh install, initialize, tool-list, and scoped-read smoke checks.

Verify MCP from the configured client by calling get_onboarding_status with the target project and environment, then refresh Setup & MCP. A copied config is not server evidence.

Install the three Poolstatis workflow skills in the product repo. MCP supplies live tools and project data; skills tell Codex, Claude, and other compatible agents to read the standard, project schema, and current documentation before they instrument, analyze, or maintain measurement:

pnpm dlx skills add https://github.com/lim5max/poolstatis \
  --skill poolstatis-instrument poolstatis-analyze poolstatis-maintain \
  --agent '*' -y
pnpm dlx skills list --json

Use --agent codex or --agent claude-code instead of '*' to target one runtime. An absolute local Core checkout path can replace the GitHub URL. The GitHub-source install resolves the repository state supported by the skills CLI; it is not a pinned-commit promise, so verify the installed names and source. See the public quickstart, instrumentation standard, and MCP reference.

Send product events through the ingest API:

curl -X POST https://api.poolstatis.xyz/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, measurement trust, release changes, decision inbox/review/action history, API keys, onboarding, webhook delivery, 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
• Repository-owned measurement contracts, immutable release provenance, evidence snapshots, human decision revisions, bounded release monitoring, correlation hypotheses, approval-gated actions, encrypted webhook outbox, and project-scoped decision memory
• 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.