Skip to content
Back to search

pug

Open-source product analytics

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 14 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/pug-sh/pug with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/pug-sh/pug'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pug-sh--pug/badge.svg)](/listings/pug-sh--pug)

HTML

<a href="/listings/pug-sh--pug"><img src="/api/listings/pug-sh--pug/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Build the binary into bin/pug
make build

# Start dev infrastructure (PostgreSQL, NATS, ClickHouse)
make infra

# Run migrations (Postgres, NATS, ClickHouse)
./bin/pug migrate

# Seed the demo project with events, profiles, and dashboards
# (resets the local Postgres and ClickHouse databases; see "Demo data" below)
./bin/pug seed

# Start the dev server + workers together
./bin/pug dev

[`docs/development.md`](docs/development.md) walks through each step, including signing in as the demo org's admin.

Environment variables are documented in [`.env.example`](.env.example). Google and generic OIDC sign-in are documented in [`docs/authentication.md`](docs/authentication.md), with a ready-to-copy [`config.example.json`](config.example.json).

Demo data

`./bin/pug seed` fills a "Pug & Pals" demo project with ~6 months of history, so dashboards, insights, and profiles have something to show. Profiles are seeded only for users that produced events, so the data is internally consistent.

> **Local databases only.** By default `seed` migrates Postgres and ClickHouse > all the way down and back up, dropping every table, not just the demo rows. > There is no confirmation prompt and no environment check: it connects to > whatever `DATABASE_URL` and `CLICKHOUSE_URL` resolve to, and an already > exported variable beats `.env`. Point it at a disposable local or demo > database.

Pass `--no-reset` to keep the schema; it then deletes the demo project's own events and profiles before re-seeding them, leaving other projects untouched. Volume is tunable with `--count` (default 500,000 events) and `--batch` (default 10,000 events per insert). Run it from the repo root; it reads the same `.env` as the rest of the CLI.

Two read-only accounts are seeded, plus an admin if you ask for one:

- `woof@pug.sh` owns the demo org and its data. It has no password. - `snoop@pug.sh` is a viewer with no password; open `/demo` with `PUG_DEMO_ENABLED=true` to sign in as it. - `admin@pug.example` is the demo org's admin, seeded only when `PUG_DEMO_ADMIN_PASSWORD` is set (16 characters to 72 bytes, no surrounding whitespace), with that password. The address can't receive mail. Nothing logs the password, and later runs never change it, so change it in the dashboard, to 16 characters or more, and update the variable to match, since the seeder restores the admin's role only while they match. A default `pug seed` resets the database, though, and so recreates the admin from the current value.

For a live stream of traffic instead of a one-shot backfill, set `PUG_DEMO_ENABLED=true`: `./bin/pug dev` then also runs the demo worker. It backfills an **empty** project once, so after `pug seed` it skips straight to playing new sessions out in real time. If you seed with a smaller `--count`, lower `PUG_DEMO_SEED_COUNT` to match: the worker reads a project holding fewer events than that as an interrupted backfill and warns rather than topping it up.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 199 lines
  1. # Pug
  2. [![CI](https://github.com/pug-sh/pug/actions/workflows/ci.yaml/badge.svg)](https://github.com/pug-sh/pug/actions/workflows/ci.yaml)
  3. [![codecov](https://codecov.io/gh/pug-sh/pug/branch/main/graph/badge.svg)](https://codecov.io/gh/pug-sh/pug)
  4. [![Discord](https://img.shields.io/badge/Discord-Join%20chat-5865F2?logo=discord&logoColor=white)](https://discord.gg/kDNHDWcBHP)
  5. Pug is an open-source product analytics platform. Capture events, identify the
  6. people behind them, and explore behavior through funnels, retention, trends,
  7. segmentation, and user-flow analysis, all surfaced on customizable dashboards.
  8. Built in Go on PostgreSQL, ClickHouse, and NATS.
  9. ## Features
  10. - **Event ingestion**: a NATS-backed capture pipeline with automatic geo,
  11. user-agent, bot-detection, and web-attribution enrichment.
  12. - **Web analytics**: an overview auto-built from your events: visitors,
  13. sessions, pageviews, bounce rate, and traffic sources, with no tile to wire up.
  14. - **Live view**: every visitor on a real-time world map, down to the person and
  15. the event they just fired.
  16. - **Profiles**: identify and alias the users behind events, with a
  17. ClickHouse-backed profile and activity API.
  18. - **Insights**: trends, funnels, retention, segmentation, user flow (Sankey),
  19. and top-K breakdowns, with filtering, breakdowns, and period-over-period
  20. comparison.
  21. - **Dashboards**: compose insight and markdown tiles on a grid with a
  22. board-level time window, accelerated by a pre-aggregated rollup fast path.
  23. - **Privacy & compliance**: GDPR/DPDP data-subject erasure of a person's
  24. events and profile.
  25. <p>
  26. <picture>
  27. <source media="(prefers-color-scheme: dark)" srcset="docs/assets/overview-dark.webp" />
  28. <img src="docs/assets/overview-light.webp" alt="Pug's overview page showing visitors, sessions, pageviews, and traffic sources" />
  29. </picture>
  30. <br /><sub><b>Overview</b>: a web-analytics view auto-built from your events, with the previous period alongside.</sub>
  31. </p>
  32. <p>
  33. <picture>
  34. <source media="(prefers-color-scheme: dark)" srcset="docs/assets/breakdowns-dark.webp" />
  35. <img src="docs/assets/breakdowns-light.webp" alt="Pug's overview breakdowns: a choropleth of pageviews by country, plus locations, devices, and events" />
  36. </picture>
  37. <br /><sub><b>Breakdowns</b>: pageviews by country, plus locations, devices, and events; click any value to filter the whole view.</sub>
  38. </p>
  39. <p>
  40. <picture>
  41. <source media="(prefers-color-scheme: dark)" srcset="docs/assets/live-dark.webp" />
  42. <img src="docs/assets/live-light.webp" alt="Pug's live map flying between real-time visitors around the world" />
  43. </picture>
  44. <br /><sub><b>Live view</b>: every visitor on a live world map; click one to fly to them and see the page, device, and profile behind it.</sub>
  45. </p>
  46. <p>
  47. <picture>
  48. <source media="(prefers-color-scheme: dark)" srcset="docs/assets/events-dark.webp" />
  49. <img src="docs/assets/events-light.webp" alt="Pug's events explorer listing raw events with location, platform, and properties" />
  50. </picture>
  51. <br /><sub><b>Events</b>: every raw event as it lands, with its location, platform, properties, and the person behind it.</sub>
  52. </p>
  53. <p>
  54. <picture>
  55. <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dashboards-dark.webp" />
  56. <img src="docs/assets/dashboards-light.webp" alt="A Pug dashboard composed of insight and markdown tiles" />
  57. </picture>
  58. <br /><sub><b>Dashboards</b>: compose insight and markdown tiles on a time-windowed grid.</sub>
  59. </p>
  60. <p>
  61. <picture>
  62. <source media="(prefers-color-scheme: dark)" srcset="docs/assets/insights-dark.webp" />
  63. <img src="docs/assets/insights-light.webp" alt="A Pug trends insight broken down by country" />
  64. </picture>
  65. <br /><sub><b>Insights</b>: trends, filters, and breakdowns; here product views split by country.</sub>
  66. </p>
  67. <p>
  68. <picture>
  69. <source media="(prefers-color-scheme: dark)" srcset="docs/assets/funnels-dark.webp" />
  70. <img src="docs/assets/funnels-light.webp" alt="A Pug funnel from product view to add to cart, checkout, and purchase" />
  71. </picture>
  72. <br /><sub><b>Funnels</b>: step-by-step conversion; here product view to purchase.</sub>
  73. </p>
  74. <p>
  75. <picture>
  76. <source media="(prefers-color-scheme: dark)" srcset="docs/assets/profiles-dark.webp" />
  77. <img src="docs/assets/profiles-light.webp" alt="A Pug user profile showing traits and recent activity" />
  78. </picture>
  79. <br /><sub><b>Profiles</b>: the person behind the events, with traits, sessions, and activity.</sub>
  80. </p>
  81. ## Tech stack
  82. - **Go**: backend services and workers, exposed over [Connect RPC](https://connectrpc.com/) (HTTP/2)
  83. - **PostgreSQL**: relational store (orgs, projects, dashboards, auth)
  84. - **ClickHouse**: analytical store for events, insights, and profiles
  85. - **NATS**: messaging backbone for the ingestion and worker pipelines
  86. ## Self-hosting
  87. See the [self-hosting guide](https://docs.pug.sh/self-hosting/). A Pug
  88. instance is this repo's backend, published as container images on
  89. `ghcr.io/pug-sh`, plus the dashboard from
  90. [`pug-sh/app`](https://github.com/pug-sh/app), served as static files.
  91. ## Quick start
  92. ```bash
  93. # Build the binary into bin/pug
  94. make build
  95. # Start dev infrastructure (PostgreSQL, NATS, ClickHouse)
  96. make infra
  97. # Run migrations (Postgres, NATS, ClickHouse)
  98. ./bin/pug migrate
  99. # Seed the demo project with events, profiles, and dashboards
  100. # (resets the local Postgres and ClickHouse databases; see "Demo data" below)
  101. ./bin/pug seed
  102. # Start the dev server + workers together
  103. ./bin/pug dev
  104. ```
  105. [`docs/development.md`](docs/development.md) walks through each step, including
  106. signing in as the demo org's admin.
  107. Environment variables are documented in [`.env.example`](.env.example).
  108. Google and generic OIDC sign-in are documented in
  109. [`docs/authentication.md`](docs/authentication.md), with a ready-to-copy
  110. [`config.example.json`](config.example.json).
  111. ### Demo data
  112. `./bin/pug seed` fills a "Pug & Pals" demo project with ~6 months of history, so
  113. dashboards, insights, and profiles have something to show. Profiles are seeded
  114. only for users that produced events, so the data is internally consistent.
  115. > **Local databases only.** By default `seed` migrates Postgres and ClickHouse
  116. > all the way down and back up, dropping every table, not just the demo rows.
  117. > There is no confirmation prompt and no environment check: it connects to
  118. > whatever `DATABASE_URL` and `CLICKHOUSE_URL` resolve to, and an already
  119. > exported variable beats `.env`. Point it at a disposable local or demo
  120. > database.
  121. Pass `--no-reset` to keep the schema; it then deletes the demo project's own
  122. events and profiles before re-seeding them, leaving other projects untouched.
  123. Volume is tunable with `--count` (default 500,000 events) and `--batch` (default
  124. 10,000 events per insert). Run it from the repo root; it reads the same `.env`
  125. as the rest of the CLI.
  126. Two read-only accounts are seeded, plus an admin if you ask for one:
  127. - `woof@pug.sh` owns the demo org and its data. It has no password.
  128. - `snoop@pug.sh` is a viewer with no password; open `/demo` with
  129. `PUG_DEMO_ENABLED=true` to sign in as it.
  130. - `admin@pug.example` is the demo org's admin, seeded only when
  131. `PUG_DEMO_ADMIN_PASSWORD` is set (16 characters to 72 bytes, no surrounding
  132. whitespace), with that password. The address can't receive mail. Nothing logs
  133. the password, and later runs never change it, so change it in the dashboard,
  134. to 16 characters or more, and update the variable to match, since the seeder
  135. restores the admin's role only while they match. A default `pug seed` resets
  136. the database, though, and so recreates the admin from the current value.
  137. For a live stream of traffic instead of a one-shot backfill, set
  138. `PUG_DEMO_ENABLED=true`: `./bin/pug dev` then also runs the demo worker. It
  139. backfills an **empty** project once, so after `pug seed` it skips straight to
  140. playing new sessions out in real time. If you seed with a smaller `--count`,
  141. lower `PUG_DEMO_SEED_COUNT` to match: the worker reads a project holding fewer
  142. events than that as an interrupted backfill and warns rather than topping it up.
  143. ## Development
  144. ```bash
  145. make test # run tests (race detector enabled)
  146. make cover # run tests and write coverage.out
  147. make lint # lint Go code
  148. make sqlc # regenerate sqlc queries after editing SQL
  149. make rpc # regenerate protobuf code after editing .proto files
  150. make templ # regenerate templ email templates
  151. ```
  152. ## Architecture
  153. Per-subsystem documentation lives in [`docs/architecture/`](docs/architecture/)
  154. (insights, ClickHouse, profiles, ingestion, email, telemetry). Contributor
  155. guidance and conventions are in [`CLAUDE.md`](CLAUDE.md).
  156. ## License
  157. Copyright (C) 2025 pug.sh contributors.
  158. Pug is licensed under the [GNU AGPL v3.0](LICENSE), or (at your option) any
  159. later version. Contributors sign a [CLA](CLA.md) before their first pull
  160. request is merged; see [CONTRIBUTING.md](CONTRIBUTING.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.