Dev

.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,32 @@ 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
+- `command` — subommand used ("", "badge", "demo", etc...)
+
+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, "badge")
 		runBadgeCmd(args[1:])
 	case "demo":
+		telemetry.Send(version, "demo")
 		runDemoCmd(args[1:])
 	case "version":
 		fmt.Printf("gh-oss-stats v%s\n", version)
 		os.Exit(0)
 	default:
+		telemetry.Send(version, "")
 		runMainCmd(args)
 	}
 }

docs/TECHNICAL.md

@@ -389,33 +389,6 @@ The tool implements smart rate limit handling:
 - Returns partial results if rate limited mid-fetch
 - Uses exponential backoff for retries
 
-## Architecture
-
-```
-gh-oss-stats/
-├── cmd/gh-oss-stats/           # CLI entry point
-├── pkg/ossstats/               # Public API (importable)
-│   ├── badge/                  # Badge generation folder
-│   │   ├── badgeTemplates/     # Defines all badge svg templates
-│   │   ├── badge.go            # Generate and save badge
-│   │   ├── badgeSortBy.go      # Defines sorting types
-│   │   ├── badgeStyle.go       # Defines all badge styles + helper function
-│   │   ├── badgeTheme.go       # Defines all badge themes + helper function
-│   │   ├── badgeVariant.go     # Defines all badge variants + helper function
-│   │   └── types.go            # Client + New()
-│   ├── client.go               # Client + New()
-│   ├── contributions.go        # GetContributions() logic
-│   ├── types.go                # Exported types
-│   └── options.go              # Functional options
-└── internal/github/            # GitHub API client (private)
-    ├── mockResponses/          # Fake github API responses for debug mode
-    ├── interface.go            # HTTP client interface
-    ├── api.go                  # Real Github HTTP client
-    ├── mock_client.go          # Mock Github HTTP client
-    ├── ratelimit.go            # Rate limit handling
-    └── types.go                # API response types
-```
-
 ## Development
 
 ```bash

docs/release-notes/v0.3.5.md

@@ -0,0 +1,9 @@
+# Release Notes: v0.3.5
+
+Release Date: April 18, 2026
+Codename: Anonymous Usage Telemetry
+
+
+## ✨ Features
+
+- **NEW**: add anonymous usage telemetry via Mixpanel [Feat/analytics #33](https://github.com/mabd-dev/gh-oss-stats/pull/33) 

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=