README clones badge (accumulated GitHub traffic)

[fdaviddpt]

Goal

Show a clones badge in the README (like Rector's Packagist downloads badge), as a demo before rolling it out to our other plugin repos and the dp.tools homepage.

Label it "clones", not "downloads": it is GitHub's clone count, which includes Claude Code re-cloning the marketplace for updates. It is GitHub's number, shown as-is.

What we learned

• Plugins install via marketplace git clone, so no registry (npm/Packagist) counts installs. The only source is the GitHub traffic API: GET /repos/{owner}/{repo}/traffic/clones.
• That API only keeps the last 14 days. A total needs a scheduled job that accumulates daily counts. History before the first run is lost.
• Snapshot 2026-09-27 (14 days): 2,910,120 clones / 144,943 uniques. For comparison, claude-supertool: 9,905 / 704.
• The default GITHUB_TOKEN cannot read traffic: the endpoint needs "Administration: read" (fine-grained PAT) or repo scope (classic PAT), and Actions permissions: has no administration key.
• Existing Action MShawon/github-clone-count-badge does this (Gist storage), but it runs on @master with a PAT that has admin read. Not worth the supply-chain risk for ~30 lines of YAML, so we write our own.
• shields.io caches endpoint badges for a few hours, so expect some lag.

Plan

1. Fine-grained PAT, "Administration: read" on this repo only, stored as repo secret (e.g. TRAFFIC_TOKEN). Created by a maintainer.
2. Workflow .github/workflows/clones-badge.yml, nightly cron + workflow_dispatch, no third-party actions:
   • fetch traffic/clones with the PAT
   • merge daily entries into history.json on an orphan badges branch, deduplicated by timestamp
   • write clones.json in shields endpoint format: {"schemaVersion":1,"label":"clones","message":"2.9M","color":"blue"}
   • push to badges with GITHUB_TOKEN (permissions: contents: write); a non-default branch triggers no other workflows
3. README badge:
   ![clones](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Digital-Process-Tools/claude-remember/badges/clones.json)

Later

• Same workflow on claude-supertool, claude-jit-context, claude-oss, claude-swarm-builder, claude-marketplace, claude-5h-window-spread.
• Total across repos for the dp.tools homepage.