Feat/analytics

.github/workflows/release.yml

@@ -34,9 +34,9 @@ jobs:
         run: |
           echo "Building gh-oss-stats ..."
           mkdir -p dist
-          GOOS=linux  GOARCH=amd64  go build -o dist/gh-oss-stats-linux-amd64   ./cmd/gh-oss-stats/*.go
-          GOOS=linux  GOARCH=arm64  go build -o dist/gh-oss-stats-linux-arm64   ./cmd/gh-oss-stats/*.go
-          GOOS=darwin GOARCH=arm64  go build -o dist/gh-oss-stats-darwin-arm64  ./cmd/gh-oss-stats/*.go
+          GOOS=linux  GOARCH=amd64  go build -o dist/gh-oss-stats-linux-amd64  -ldflags="-X github.com/mabd-dev/gh-oss-stats/internal/analytics.mixpanelToken=${{ secrets.MIXPANEL_TOKEN }}" ./cmd/gh-oss-stats
+          GOOS=linux  GOARCH=arm64  go build -o dist/gh-oss-stats-linux-arm64  -ldflags="-X github.com/mabd-dev/gh-oss-stats/internal/analytics.mixpanelToken=${{ secrets.MIXPANEL_TOKEN }}" ./cmd/gh-oss-stats
+          GOOS=darwin GOARCH=arm64  go build -o dist/gh-oss-stats-darwin-arm64 -ldflags="-X github.com/mabd-dev/gh-oss-stats/internal/analytics.mixpanelToken=${{ secrets.MIXPANEL_TOKEN }}" ./cmd/gh-oss-stats
 
       - name: Trigger pkg.go.dev indexing
         run: |

.github/workflows/tests.yml

@@ -14,18 +14,14 @@ jobs:
     name: Run Tests
     runs-on: ubuntu-latest
 
-    strategy:
-      matrix:
-        go-version: ['1.23', '1.24', '1.25']
-
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: ${{ matrix.go-version }}
+          go-version: 1.25
           cache: true
 
       - name: Download dependencies
@@ -59,9 +55,9 @@ jobs:
         run: |
           echo "Building gh-oss-stats ..."
           mkdir -p dist
-          GOOS=linux  GOARCH=amd64  go build -o dist/gh-oss-stats-linux-amd64   ./cmd/gh-oss-stats/*.go
-          GOOS=linux  GOARCH=arm64  go build -o dist/gh-oss-stats-linux-arm64   ./cmd/gh-oss-stats/*.go
-          GOOS=darwin GOARCH=arm64  go build -o dist/gh-oss-stats-darwin-arm64 ./cmd/gh-oss-stats/*.go
+          GOOS=linux  GOARCH=amd64  go build -o dist/gh-oss-stats-linux-amd64  -ldflags="-X github.com/mabd-dev/gh-oss-stats/internal/analytics.mixpanelToken=${{ secrets.MIXPANEL_TOKEN }}" ./cmd/gh-oss-stats
+          GOOS=linux  GOARCH=arm64  go build -o dist/gh-oss-stats-linux-arm64  -ldflags="-X github.com/mabd-dev/gh-oss-stats/internal/analytics.mixpanelToken=${{ secrets.MIXPANEL_TOKEN }}" ./cmd/gh-oss-stats
+          GOOS=darwin GOARCH=arm64  go build -o dist/gh-oss-stats-darwin-arm64 -ldflags="-X github.com/mabd-dev/gh-oss-stats/internal/analytics.mixpanelToken=${{ secrets.MIXPANEL_TOKEN }}" ./cmd/gh-oss-stats
 
       - name: Verify binaries
         run: |

.gitignore

@@ -1,6 +1,7 @@
 .claude
 .serena
 .mcp.json
+claude.local.md
 commands.nu
 /gh-oss-stats
 scripts/

README.md

@@ -100,7 +100,7 @@ Customize your badge by passing inputs to the action:
   with:
     github-token: ${{ secrets.GITHUB_TOKEN }}
     badge-path: 'images/oss-badge.svg'
-    badge-style: 'detailed'      # summary, compact, or detailed
+    badge-style: 'detailed'       # summary, compact, or detailed
     badge-theme: 'nord'           # dark, light, nord, dracula, gruvbox-light, gruvbox-dark, etc...
     badge-variant: 'text-based'   # default or text-based
     min-stars: '100'              # Filter repos by minimum stars
@@ -131,6 +131,31 @@ For local development or custom integrations, see [docs/TECHNICAL.md](docs/TECHN
 
 📖 **Full technical documentation:** [docs/TECHNICAL.md](docs/TECHNICAL.md)
 
+***
+
+## Telemetry
+
+`gh-oss-stats` collects anonymous usage data to help understand how the tool 
+is used and improve it over time. You'll see a one-time notice about this on 
+first run.
+
+**What is collected:**
+- `os` — operating system (linux, windows, darwin)
+- `version` — tool version being used
+- `ci` — whether the tool is running in a CI environment
+
+Nothing personal is collected — no usernames, tokens, or file paths.
+Events are sent to a [mixpanel](https://mixpanel.com/home/) (a third-party analytics service) and visible only to the maintainer.
+
+### Disable telemetry
+
+Add this to your shell config (`~/.zshrc` or `~/.bashrc`):
+```sh
+export GH_OSS_STATS_TELEMETRY_DISABLED=1
+```
+
+***
+
 ## License
 
 See [LICENSE](LICENSE) file.

cmd/gh-oss-stats/main.go

@@ -3,28 +3,34 @@ package main
 import (
 	"fmt"
 	"os"
+
+	"github.com/mabd-dev/gh-oss-stats/internal/telemetry"
 )
 
-const version = "0.3.2"
+const version = "0.3.5"
 
 func main() {
 	args := os.Args[1:]
 
 	if len(args) == 0 {
+		telemetry.Send(version)
 		runMainCmd(args)
 		return
 	}
 
 	// Route to sub-commands, or fallback to main command
 	switch args[0] {
 	case "badge":
+		telemetry.Send(version)
 		runBadgeCmd(args[1:])
 	case "demo":
+		telemetry.Send(version)
 		runDemoCmd(args[1:])
 	case "version":
 		fmt.Printf("gh-oss-stats v%s\n", version)
 		os.Exit(0)
 	default:
+		telemetry.Send(version)
 		runMainCmd(args)
 	}
 }

docs/release-notes/v0.3.5.md

@@ -0,0 +1,15 @@
+# Release Notes: v0.3.5
+
+Release Date: April XX, 2026
+Codename: 
+
+
+## ✨ Features
+
+- **NEW**: add anonymous usage telemetry via Mixpanel
+
+Collects anonymous usage data (os, version, ci) on each run.
+Disable with GH_OSS_STATS_TELEMETRY_DISABLED=1.
+See README for full details.
+
+

go.mod

@@ -1,3 +1,8 @@
 module github.com/mabd-dev/gh-oss-stats
 
 go 1.25.4
+
+require (
+	github.com/google/uuid v1.6.0
+	github.com/mixpanel/mixpanel-go v1.2.1
+)

go.sum

@@ -0,0 +1,4 @@
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/mixpanel/mixpanel-go v1.2.1 h1:iykbHKomTJjVoWU95Vt1sjZy4HLt8UOYacMEEEMFBok=
+github.com/mixpanel/mixpanel-go v1.2.1/go.mod h1:mPGaNhBoZMJuLu8k7Y1KhU5n8Vw13rxQZZjHj+b9RLk=

internal/analytics/analytics.go

@@ -0,0 +1,39 @@
+package analytics
+
+import (
+	"context"
+
+	"github.com/mixpanel/mixpanel-go"
+)
+
+var mixpanelToken = ""
+
+type Analytics struct {
+	userUUID string
+	Client   *mixpanel.ApiClient
+}
+
+func CreateAnalytics(userUUID string) Analytics {
+	mixpanelClient := mixpanel.NewApiClient(mixpanelToken)
+	return Analytics{
+		userUUID: userUUID,
+		Client:   mixpanelClient,
+	}
+}
+
+func (analytics Analytics) Track(name string, params map[string]any) error {
+	ctx := context.Background()
+	return analytics.Client.Track(ctx, []*mixpanel.Event{
+		analytics.Client.NewEvent(name, analytics.userUUID, params),
+	})
+}
+
+func (analytics Analytics) TrackToolUsage(os string, version string, ci bool) error {
+	params := map[string]any{
+		"os":           os,
+		"tool-version": version,
+		"ci":           ci,
+		"project":      "gh-oss-stats",
+	}
+	return analytics.Track("usage", params)
+}