HQ Stats
Any open source developer, even with a single product, can collect usage for their projects across every channel they publish to (downloads and website page views) and show it publicly, with no AI and little set-up. Shares branding with HQ as a product, ships before it and is marketed first, as the low-friction way in to HQ.
Context
Section titled “Context”- Pulled out of HQ as a product (decided 2026-11-15): stats need no agents, so they suit a wider audience and can launch without waiting for the agentic parts.
- Released:
@rhizomatics/hq-stats0.1.1 (2026-11-19), source in rhizomatics/hq-stats. Before it:hq-private/scripts/collect_stats.py, snapshots inhq-private/data/stats/and the site’s ownbuild-stats.mjsand Usage pages. - Channels are selected by fields in
repos.toml(pypi,npm,ghcr,hacs_zip,ha_domain,goatcounter), so adding a user’s repos is config, not code. - Platform channels (HACS, HA analytics, SignalK) are what nobody else offers; generic ones (PyPI, npm, ghcr, GitHub traffic, GoatCounter page views) make it useful beyond those platforms.
- Shape (2026-11-16): a plain npm package,
@<org>/hq-stats, published the same way as the org’s other npm packages (release policy: GitHub Actions, gated on CI, staged npm release with manual approval, immutable semver releases). Its source lives in its own repo; nothing about a user lives there.- Configuration and outputs live in the user’s
hqrepo:repos.toml(or a skeleton one for someone without HQ), anhq-statssection for options, and the snapshots and public aggregates underdata/. Snapshots record only public data. The user’s own scheduled workflow runsnpx @<org>/hq-stats collectand commits the results. A copy-in workflow is in the docs. - Two ways to use it, both from the same package: the built-in UI (
hq-stats buildwrites the Usage pages as a static site, or as pages an Astro/Starlight site such as the HQ site mounts in its own navigation) or the raw data, a documented JSON format for anyone’s own pages or reports. - This replaces the earlier plan of an
hq-statsrepo per user holding config and data, served on its own subdomain with a navigation manifest. The HQ site mounts the built-in pages directly, so one site, one menu.
- Configuration and outputs live in the user’s
- Stats are for open source products, so everything collected is assumed public. Private repos are skipped by the
collector (since 2026-11-15). Someone who wants private stats keeps their
hqrepo private; the docs give that advice. - The collector token needs push access (GitHub traffic API), so the workflow runs on schedule and manual dispatch only, never on PR code.
- Branding: the HQ logo with
statsbeneath in a complementary colour, a similar binary style at a smaller size. - Community: contributed projects built on the org’s products (
[community.<id>]inrepos.toml, design in HQ as a product) are collected from public sources only: stars, forks, releases, downloads per channel; no traffic or clones. Kept apart from the org’s own figures: separate in the data, their own pages, never in the org’s totals. - Not stats:
collect_github.py(alerts, referrers, discussions) stays inhq-private. Security (incl. OpenSSF Scorecard) stays on the HQ site’s Security page.
- @agent Collector skips private repos, so current snapshots hold only public ones (2026-11-15)
- @agent Site views:
collect_stats.pycollects daily page views (14-day overlapping window) and top pages per website from the GoatCounter API,goatcounterfield per repo,GOATCOUNTER_TOKENsecret; the HQ site’s Usage is split into Downloads and Page views, with page views on each component’s page (2026-11-16) - @human
GOATCOUNTER_TOKENsecret inhq-private(API key with “Read statistics”); check one key reads every site (2026-11-17, hq-private#115; also inhq) - @pair Package skeleton:
hq-statsrepo, npm package with acollectand abuildcommand, CI and the staged npm release workflow the other npm packages use (2026-11-19, local only until the repo exists) - @pair Port the collectors (
collect_stats.py) to JavaScript in the package, with org and repos fromrepos.toml; done when nothing outside config names Rhizomatics (2026-11-19) - @pair Config: an
hq-statssection (inrepos.tomlor its own file inhq) for the data directory, site options and the parent site’s label and URL; skeletonrepos.tomlin the docs (2026-11-19:[stats]; the parent site’s label and URL weren’t needed, as the pages mount in the host site) - @pair Document the snapshot and aggregate formats as the raw-data interface, versioned with the package (2026-11-19)
- @pair Built-in UI: move
build-stats.mjs,usage.ts, the Usage pages andChart/Kpiinto the package; standalone static site plus pages the HQ site mounts in its own sidebar (2026-11-19: an Astro integration and sidebar helper, plus a standalone Starlight example; the HQ site still uses its own copy until 0.1.0 is published) - @pair Community: move
build-community.mjsand its page into the package;[community.*]from public sources only, stored apart, never in the org’s totals - @pair Workflow for users to copy: schedule and manual dispatch only,
npxthe pinned version, commit tohq(2026-11-19) - @pair Brand: HQ logo with
statsbeneath in a complementary colour; site look in the HQ family - @human Create the
hq-statsrepo, its npm package and trusted publishing (hq-private#123); then @agent pushes the local repo (../hq-stats, one commit) and drafts the 0.1.0 release (2026-11-19: the maintainer pushed and released 0.1.0 and 0.1.1) - @pair Rhizomatics on the package: snapshots and legacy HACS history moved from
hq-private/data/statsintohq/data/, GitHub traffic (views, clones) kept,hq-private’s stats collector retired, the HQ site’s Usage pages served by the package (2026-11-19: built as hq#14 and hq-private#126); merged the same day, firsthqsnapshot 2026-11-19 with no errors - @agent Seed a throwaway org end to end from the docs; fix whatever needed hand edits
- @pair README and docs; announcement drafts for HA and SignalK developer forums
- @human Post announcements
Success test
Section titled “Success test”Rhizomatics HQ runs on the released hq-stats package unchanged, and at least one outside developer has it
running within 2 months of the announcement.
Decisions
Section titled “Decisions”Decided:
- 2026-11-15 — Everything public: private repos aren’t collected; private stats are a documented do-it-yourself option.
- 2026-11-16 — Shape: a plain npm package published like the org’s other npm packages, with its configuration and
outputs in the user’s
hqrepo, usable through its built-in UI or the raw data. Replaces the 2026-11-15 shape (anhq-statsrepo per user holding config and snapshots, its own subdomain and a navigation manifest). - 2026-11-16 — Daily snapshots live in
hqand record only public data. GitHub traffic for public repos (repo page views and clones) counts as public and is kept. Referrers and popular paths stay withcollect_github.pyinhq-private.
Open:
None.
- 2026-11-15 — Created from the HQ as a product decision to ship stats and site first, as a separate product with shared branding.
- 2026-11-15 — Collectors plus optional pages on a subdomain, with a navigation manifest for HQ’s menu; everything
public.
hq-private/scripts/collect_stats.pynow skips private repos. Community projects added, collected from public sources and kept out of the org’s totals. - 2026-11-15 — Page views: GitHub gives none for Pages sites, only repo traffic. GoatCounter chosen (cookieless,
no consent banners; no Google Analytics). HQ site wired to it via
[org].goatcounter; collector task added. - 2026-11-16 — Reshaped by the maintainer: an npm package published like the rest, with config and outputs in
hq, built-in UI or raw data; no per-userhq-statsrepo, subdomain or manifest. Plan rewritten to match. GoatCounter collection added tocollect_stats.pyand the Usage section split into Downloads and Page views; page views appear once theGOATCOUNTER_TOKENsecret exists. - 2026-11-16 — Decided: snapshots live in
hq, public data only. GitHub traffic (repo page views, clones) counts as public and is kept. - 2026-11-19 — Started (moved to active) as the last Phase 0 task of HQ as a product. Built in a
local
hq-statsrepo next tohq, not yet on GitHub (the repo is the maintainer’s to create):hq-stats collect(the JS port ofcollect_stats.py, same snapshot format plus each repo’s description and archive state, sobuildno longer needs the private GitHub snapshot),hq-stats build(frombuild-stats.mjs), and the Usage pages as an Astro integration (@rhizomatics/hq-stats/astro) with a sidebar helper. Checked against Rhizomatics’ data:buildgives the same aggregate as the site’s own (descriptions aside, which old snapshots lack), and an HQ site built with the packed package renders the same 21 Usage pages. Tests, lint, CI and the staged npm release workflow are in place; README anddocs/data-format.mddocument the config and both data formats. Generalised on the way: no hard-coded family (the HA installs column shows where a family has installs), components outside[families]go under “Other”. - 2026-11-19 — Released by the maintainer as 0.1.0 and 0.1.1. Rhizomatics moved onto it (hq#14 and hq-private#126): the
36 snapshots and the legacy HACS history copied into
hq/data/with the three repos that aren’t public now (hq-private,brands,appliances_autonotify) removed,[stats]inrepos.toml, a dailycollect-stats.ymlinhqrunning the version in the site’s lockfile (so Dependabot updates it), and the site’s Usage pages, sidebar and chart code replaced by the package’s. The package’s aggregate matched the old script’s exactly on the same data, apart from its addedorgandformatfields.hq-privatekeeps only the GitHub snapshot. - 2026-11-19 — Both PRs merged.
STATS_TOKENadded tohq; the first run ofcollect-stats.ymlcollected all 22 public repos with no errors (GitHub views and clones, 14 GoatCounter sites), and the site deployed with the package’s Usage pages. No snapshots were lost in the switch. - 2026-11-20 — project-review: no new entries since the 11-19 switch. Next: community page, brand, throwaway-org test.