🦆 quackscore

"Every PR merged is a feather in your cap. Or your tail. Ducks aren't picky."

quackscore turns your GitHub pull request history into a Duck RPG-style developer card. It fetches your merged PRs, scores them, classifies them with an LLM, and generates a slick local HTML report — because your contributions deserve more than a green square.

npx quackscore create <your-github-username>

That's it. Quack.

What it does

• Fetches your merged pull requests from GitHub
• Uses an LLM to classify each PR (complexity, area, type, technologies)
• Awards points and levels based on your contribution history
• Generates a local HTML developer card you can be proud of
• Stores history locally so incremental updates are fast
• Separates PR analysis from profile summary regeneration for fine-grained control
• Generates repository-level PR stats reports with review speed, merge speed, comment load, and weekly contribution charts

Requirements

• Node.js 18+
• A GitHub personal access token — set via QUACKSCORE_GH_TOKEN env var or --github-token flag. See GitHub fine-grained token setup
• An LLM API key — set via QUACKSCORE_LLM_API_KEY env var or --llm-api-key flag. See LLM provider setup. Not required for Ollama or unauthenticated LiteLLM proxies.

Install

npm install -g quackscore

Or run without installing:

npx quackscore --help

Supported LLM providers

| Provider | Value | Notes | |---|---|---| | Anthropic | anthropic | | | OpenAI | openai | | | Google | google | | | OpenRouter | openrouter | | | MiniMax | minimax | | | Ollama (local) | ollama | No API key needed | | LiteLLM proxy | litellm | Routes to Azure OpenAI, Bedrock, and more |

All remote providers use QUACKSCORE_LLM_API_KEY. Ollama needs no key. LiteLLM's key is optional (only needed if your proxy requires auth).

Need setup help? See LLM provider setup.

Quick start

1. Set credentials

Need a GitHub token first? Follow GitHub fine-grained token setup.

Option A — environment variables (recommended for repeated use):

export QUACKSCORE_GH_TOKEN=<your-github-token>
export QUACKSCORE_LLM_API_KEY=<your-llm-api-key>

Option B — CLI flags (useful for one-off runs or CI):

quackscore create <github-username> \
  --github-token <your-github-token> \
  --llm-api-key <your-llm-api-key>

2. Pick your LLM provider

Need help choosing or configuring a provider? See LLM provider setup.

quackscore init --provider anthropic --model claude-haiku-4-5-20251001

Config is saved to ~/.quackscore/config.json.

3. Generate your card

quackscore create <github-username>

This always rebuilds from scratch — fetches all merged PRs, analyzes each one, generates your profile summary, and produces a fresh card. Any existing local profile is overwritten.

Filter by org or repo:

quackscore create <github-username> --organisation <org> --repository <repo>

Limit to the last N weeks of PRs (useful for developers with large PR histories):

quackscore create <github-username> --weeks 30

4. Create profiles for multiple users

quackscore create-batch user1 user2 user3

Runs create for each username one by one in the order given — never concurrently. All the same flags as create are supported and applied to every user in the batch:

quackscore create-batch user1 user2 user3 \
  --organisation my-org \
  --weeks 12 \
  --github-token <token> \
  --llm-api-key <key>

If a user's run fails (e.g. a network error), the batch stops at that point. Users processed before the failure keep their generated profiles.

6. Update later (only new PRs)

quackscore update <github-username>

Fetches only PRs merged since the last run, analyzes them, and updates your stats, level, and charts. Your existing profile summary is left untouched — use update-summary when you want to regenerate it.

You can also limit the update window to a specific number of weeks:

quackscore update <github-username> --weeks 12

7. Refresh your profile summary

quackscore update-summary <github-username>

Regenerates the RPG title and written summary by sending your full PR history to the LLM. Does not re-fetch or re-analyze any PRs. Useful after a batch of update runs, or whenever you want a fresh take on your narrative.

8. Re-open a saved card

quackscore show <github-username>

9. Remove a profile

quackscore remove <github-username>

Deletes the locally stored JSON data and HTML report for the given user. Useful for cleaning up or starting fresh. Does not affect GitHub or any remote data.

10. Leaderboard

quackscore leaderboard

11. Repository stats

quackscore stats <repo> --organisation <org>

Generates a local HTML report for merged PRs in the repository, including average approval time, average merge time, weekly contribution charts, average comments, per-author stats, and per-approver review speed.

Filter the report to PRs authored by members of a GitHub team slug:

quackscore stats <repo> --organisation <org> --team <team>

The generated report opens automatically and includes built-in filters for all time, last month, last 3 months, last 6 months, last year, and a custom date range.

12. Try it without credentials

quackscore mock-report

Generates a demo card from 20 hardcoded PRs. No GitHub or LLM key needed.

Other provider examples

# OpenAI
quackscore init --provider openai --model gpt-4o-mini

# Google
quackscore init --provider google --model gemini-2.0-flash

# OpenRouter
quackscore init --provider openrouter --model anthropic/claude-haiku-4

# MiniMax
quackscore init --provider minimax --model MiniMax-M2.7

# Ollama (local)
quackscore init --provider ollama --model llama3.2

# LiteLLM proxy — Azure OpenAI
quackscore init --provider litellm --model azure/gpt-4o-mini --base-url http://localhost:4000

# LiteLLM proxy — AWS Bedrock
quackscore init --provider litellm --model bedrock/claude-3-5-sonnet --base-url http://localhost:4000

LiteLLM lets you run a single proxy that routes to Azure OpenAI, AWS Bedrock, Hugging Face, and many other backends. Start it with:

pip install litellm
litellm --model azure/gpt-4o-mini  # or whichever backend you want

Then set your key if the proxy requires auth:

export QUACKSCORE_LLM_API_KEY=<your-litellm-master-key>

Data storage

Everything lives in ~/.quackscore/:

| File | Contents | |---|---| | config.json | Provider and model settings | | <username>.json | Analyzed PR data | | <username>.html | Your generated developer card | | leaderboard.json | Local leaderboard cache | | stats-<org>-<repo>.html | Repository stats report |

Notes

• The GitHub token is required regardless of LLM setup.
• API keys passed via --github-token and --llm-api-key take precedence over environment variables and are never written to disk.
• create always rebuilds from scratch; update only fetches and analyzes new PRs without touching the existing summary; update-summary regenerates the summary without touching PRs.
• create-batch runs create for each listed username sequentially (one at a time, never in parallel). All flags are forwarded to every user's run.
• Use --weeks <n> on create or update to limit PR fetching to the last N weeks — handy for developers with years of history who only want a recent snapshot.
• Use stats <repo> --organisation <org> to generate repository-level HTML stats without running LLM analysis.
• remove deletes only local files (~/.quackscore/<username>.json and ~/.quackscore/<username>.html).
• Add --diagnostics to any command for detailed internal tracing.