Content
# 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](LICENSE). 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](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and the
[source-available release checklist](docs/09-source-available-release.md) 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](ARCHITECTURE.md) | System overview, components, and principles |
| [docs/01-data-model.md](docs/01-data-model.md) | Tenancy, data types, and table schemas |
| [docs/02-storage.md](docs/02-storage.md) | Storage design and the Postgres-to-ClickHouse path |
| [docs/03-mcp-server.md](docs/03-mcp-server.md) | MCP server tools and resources |
| [docs/04-http-api.md](docs/04-http-api.md) | Ingest and Query API |
| [docs/05-gap-analysis.md](docs/05-gap-analysis.md) | Current scope versus PostHog and next priorities |
| [docs/06-instrumenting-a-product.md](docs/06-instrumenting-a-product.md) | Agent and manual instrumentation workflow |
| [docs/07-vps-deployment.md](docs/07-vps-deployment.md) | Deploying the Platform API, MCP, SDK, and skills |
| [docs/09-source-available-release.md](docs/09-source-available-release.md) | Source-available release and GitHub hygiene |
| [docs/10-self-host.md](docs/10-self-host.md) | Short Docker Compose self-hosting path |
| [docs/11-repository-split.md](docs/11-repository-split.md) | System, site, and Cloud repository boundaries |
| [sdk/README.md](sdk/README.md) | `@poolstatis/sdk` client usage |
| [.claude/skills/poolstatis-instrument](.claude/skills/poolstatis-instrument/SKILL.md) | Agent skill for product instrumentation |
## Local Development
```bash
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:
```bash
pnpm typecheck && pnpm test
```
Run the admin build before shipping UI changes:
```bash
pnpm --dir web build
```
## Self-Host In 3 Commands
```bash
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](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.
```json
{
"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:
```bash
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](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.
