Documentation

Beacon docs

Everything you need to run Beacon, read a Beacon Score, embed widgets, and self-host. Beacon is a newly published open-source project — these docs describe what ships in the monorepo today.

Introduction

Beacon is an open-source GitHub repository intelligence platform. Point it at any owner/repo and it collects a full snapshot from the GitHub API, computes a deterministic Beacon Score across five weighted pillars, and generates a natural-language summary.

The same analysis engine (@beacon/core) powers every surface — a CLI, a Fastify REST API, and a Next.js dashboard — so they always agree on the numbers. Beacon also ships an embeddable widget system, a self-hostable GitHub App for webhook re-scoring, and historical health snapshots.

Deterministic 0–100 health score with explainable pillars
Six embeddable SVG widgets + a maintenance badge
Self-hostable GitHub App that re-scores on webhooks
Historical snapshots and trends over 30 / 90 / 365 days
Pluggable AI summaries: heuristic (default), OpenAI, or Anthropic

NoteBeacon is self-hosted — there is no public hosted service. You run the API, dashboard, and (optionally) the GitHub App on your own infrastructure. It is MIT licensed.

Quickstart

Clone the monorepo and start the stack. Requires Node 20+ (and Docker for the container path).

Option A — Docker

bash

git clone https://github.com/martin-k-m/beacon.git
cd beacon
docker compose up

Option B — Node

bash

git clone https://github.com/martin-k-m/beacon.git
cd beacon
npm install
npm run dev

The dashboard comes up on http://localhost:3000 and the API alongside it. Set a GITHUB_TOKEN (see Self-hosting) for higher GitHub API rate limits.

NoteBeacon is not published to a package registry yet, so run the CLI from the monorepo rather than installing it globally. Check the repo README for the current workspace scripts.

The Beacon Score

The Beacon Score is a deterministic 0–100 number computed from five weighted pillars. Each pillar is scored independently and combined by weight — the same math in the CLI, API, and dashboard.

Pillars & weights

Pillar	Weight	What it measures
Activity	30%	Push recency, commit volume over 12 weeks, and release cadence.
Community	20%	Contributor base and the balance of external contribution.
Maintenance	20%	Issue and pull-request throughput and time-to-close.
Documentation	15%	README depth — install, usage, badges, and license sections.
Security	15%	Security policy, Dependabot, and vulnerability signals.

Grade bands

Grade	Score range
Excellent	90–100
Healthy	75–89
Fair	60–74
At risk	40–59
Critical	< 40

Preview · sample data

Widgets

Beacon renders embeddable SVG widgets from your instance. There are two endpoints — a rich widget endpoint and a compact badge endpoint:

Embed URL pattern

https://<your-beacon-host>/widget/repo/:owner/:repo?type=<type>&theme=<theme>&size=<size>
https://<your-beacon-host>/badge/:owner/:repo?theme=<theme>&size=<size>

Widget types

health/widget

The headline Beacon Score with its grade and the five pillar bars — the full-health snapshot in one card.

activity/widget

Weekly commit volume over the last year, drawn as a compact trend.

language/widget

The repository language breakdown as a stacked bar with a legend.

contributor/widget

Top contributors and the balance of external contribution.

release/widget

The latest tagged release — version, name, and date.

maintenance/badge

A shields-style badge — the Beacon grade at a glance for any README.

Options

theme — dark, light, transparent
size — small, medium, large
type — the widget type (widget endpoint only), one of the keys above

Embed snippets

Markdown (README):

Markdown

![Beacon health](https://<your-beacon-host>/widget/repo/beacon-labs/aurora?type=health&theme=dark&size=medium)

HTML:

HTML

<img
  src="https://<your-beacon-host>/widget/repo/beacon-labs/aurora?type=health&theme=dark&size=medium"
  alt="Beacon health card"
  width="440" height="200" />

Script tag (auto-inserts the widget where the tag sits):

HTML

<script
  src="https://<your-beacon-host>/widget/embed.js"
  data-repo="beacon-labs/aurora"
  data-type="health"
  data-theme="dark"
  async></script>

Badge

Markdown

![Beacon](https://<your-beacon-host>/badge/beacon-labs/aurora?theme=dark)

Preview · sample data

NoteReplace <your-beacon-host> with your own Beacon host (e.g. beacon.example.com). See the showcase for every widget in both themes.

GitHub App

Beacon can run as a GitHub App that installs on your repositories and receives webhooks. When a subscribed event arrives, Beacon re-scores the repository automatically — no manual re-runs — and updates its history.

Events

push	New commits land — activity and maintenance refresh.
pull_request	PRs opened, merged, or closed feed throughput.
issues	Issue open/close activity feeds the Maintenance pillar.
release	A new tagged release updates cadence and the Release card.
star	Stargazer changes update community signals.
fork	Forks update community signals.

Deliveries hit the API at POST /api/github/webhooks, which verifies the signature against GITHUB_WEBHOOK_SECRET and queues a re-score.

NoteThis is a self-hostable GitHub App — there is no public app to install. You register your own GitHub App against your Beacon instance and set GITHUB_APP_ID and GITHUB_WEBHOOK_SECRET.

CLI reference

The beacon CLI wraps the same engine as the API and dashboard. Four commands:

beacon analyze owner/repo

Run a full analysis and print the score, pillars, and summary.

example

$ beacon analyze beacon-labs/aurora

beacon-labs/aurora
Beacon Score  92 / 100   Excellent
  Activity        95   ██████████
  Community       88   █████████
  Maintenance     90   █████████
  Documentation   94   ██████████
  Security        90   █████████
Summary  Thriving, well-maintained project — watch the bus factor.

beacon widget owner/repo

Print an embeddable widget SVG (or a URL) for the repository.

example

$ beacon widget beacon-labs/aurora --type health --theme dark

<svg width="400" height="180" ...>  <!-- Repository Health Card -->
… writes health-card.svg

beacon badge owner/repo

Emit a compact Markdown/HTML badge snippet for a README.

example

$ beacon badge beacon-labs/aurora --theme dark

![Beacon](https://<your-beacon-host>/badge/beacon-labs/aurora?theme=dark)

beacon watch owner/repo

Track a repository over time and report health trend changes.

example

$ beacon watch beacon-labs/aurora

watching beacon-labs/aurora …
2026-07-16  92  (+3 this month)  Excellent  ↑ trending up

REST API

The Fastify API exposes analyses, history, widgets, and the webhook receiver over HTTP. Key endpoints:

POST	/api/analyze	Analyze a repository on demand — body { owner, repo } — returns the full analysis.
GET	/api/repositories/:owner/:repo	Fetch the latest stored analysis for a repository.
GET	/api/repositories/:owner/:repo/history	Historical health snapshots for trends over 30 / 90 / 365 days.
GET	/widget/repo/:owner/:repo	Render an embeddable widget SVG. Query: type, theme, size.
GET	/badge/:owner/:repo	Render a compact badge SVG. Query: theme, size.
POST	/api/github/webhooks	Receives GitHub App webhook deliveries and re-scores the repository.

Example — analyze a repository

bash

curl -X POST https://<your-beacon-host>/api/analyze \
  -H 'content-type: application/json' \
  -d '{"owner":"beacon-labs","repo":"aurora"}'

Example — historical trend

bash

curl https://<your-beacon-host>/api/repositories/beacon-labs/aurora/history?range=90

Self-hosting

Beacon is designed to run on your own infrastructure. The fastest path is Docker Compose; you can also run each app in the monorepo directly.

Environment variables

Variable	Req	Purpose
GITHUB_TOKEN	yes	A GitHub token used to read repositories via the API (higher rate limits).
DATABASE_URL	yes	Postgres connection string for persisting analyses and history (Prisma).
AI_PROVIDER	opt	Summary provider: heuristic (default, offline), openai, or anthropic.
OPENAI_API_KEY	opt	Key for the OpenAI summary provider (only if AI_PROVIDER=openai).
ANTHROPIC_API_KEY	opt	Key for the Anthropic summary provider (only if AI_PROVIDER=anthropic).
GITHUB_APP_ID	opt	GitHub App id — set when running the self-hosted App for webhook re-scoring.
GITHUB_WEBHOOK_SECRET	opt	Shared secret used to verify incoming webhook deliveries.

Docker

bash

git clone https://github.com/martin-k-m/beacon.git
cd beacon
cp .env.example .env      # set GITHUB_TOKEN, DATABASE_URL, …
docker compose up -d

NoteThe exact variable names and compose services may evolve — treat the repo’s .env.example and docker-compose.yml as the source of truth for your version.

View the repo Explore widgets

#Introduction

#Quickstart

Option A — Docker

Option B — Node

#The Beacon Score

Pillars & weights

Grade bands

#Widgets

Widget types

Options

Embed snippets

Badge

#GitHub App

Events

#CLI reference

#REST API

Example — analyze a repository

Example — historical trend

#Self-hosting

Environment variables

Docker

Introduction

Quickstart

The Beacon Score

Widgets

GitHub App

CLI reference

REST API

Self-hosting