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

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/10-self-host.md	Short Docker Compose self-hosting path
docs/11-repository-split.md	System, site, and Cloud repository boundaries
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 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
• 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, feature flags, experiments, and funnel correlation.