DEV Community

Cover image for I Built a GitHub Achievement Automation Toolkit (CLI + Local Dashboard)
Raja Irfan Ahmed
Raja Irfan Ahmed

Posted on

I Built a GitHub Achievement Automation Toolkit (CLI + Local Dashboard)

#github #opensource #devtools #productivity

Have you ever looked at a GitHub profile and wondered how people get badges like Pull Shark, Galaxy Brain, and Quickdraw?? If so, this post is for you.

I created a toolkit that automates GitHub achievement tasks. You can use it from your terminal or a local browser dashboard. No cloud, no third-party service; your tokens stay on your machine.

What It Does

The toolkit handles the repetitive GitHub actions that trigger achievement milestones

  • Pair Extraordinaire — co-authored commits on merged PRs (tiers: 1 / 10 / 24 / 48)
  • Pull Shark — merged pull requests (tiers: 2 / 16 / 128 / 1024)
  • Galaxy Brain — accepted answers in Discussions (tiers: 2 / 8 / 16 / 32)
  • Quickdraw — close an issue within 5 minutes (single tier)
  • YOLO — merge a PR without a code review (single tier)
  • Starstruck — star milestones on one repository (tiers: 16 / 128 / 512 / 4096)
  • Public Sponsor — verifies your public sponsorship status

You run it from the CLI or the dashboard. It checks your GitHub REST rate limit first. Then, it uses delays and controls to avoid throttling. It also shows the API reset ETA live.

Two Modes

CLI (npm start) — Terminal menus powered by Ink. Use them for setup, running achievements, checking status, and repo helpers.

Dashboard (npm run web:dev) — A local Next.js app (port 3000) with four tabs

Tab What it shows
Overview .env check, token validity, repo access, Discussions status, rate limit
Achievements Pick a tier, hit Run or Resume — one job is active at a time
History Paginated local log with links to GitHub
Settings Env summary (no secrets shown)

The "Stop run" button is cooperative. It waits for the current GitHub request to finish before stopping. No hard kills, no broken states.

How It Works (Two Accounts Required)

You need two GitHub accounts: a main account (where the badges appear) and a helper account (acts as the second party for co-authoring, PR reviews, discussion answers, etc.).

The main account owns a test repository. The team adds the helper as a collaborator with write access. Each account gets its own Personal Access Token (classic).

GITHUB_TOKEN=ghp_your_main_account_token
GITHUB_USERNAME=your-main-username
TARGET_REPO=your-main-username/your-test-repo-name
HELPER_TOKEN=ghp_your_helper_account_token
Enter fullscreen mode Exit fullscreen mode

Both tokens stay in a .env file on your machine; never committed, never sent anywhere.

Quick Setup (4 Steps)

Part A — Main account + test repo

  1. Create a new repo under your main account
  2. Enable Discussions: Repo Settings → General → Features → Discussions (needed for Galaxy Brain)
  3. Note your TARGET_REPO as username/repo-name (not the full URL)

Part B — Helper account + collaborator invite

  1. Log in as your helper account
  2. From your main account: repo Settings → Collaborators → invite the helper with write access
  3. Accept the invite from the helper account

Part C — Generate tokens

  • Main account token: scope repo
  • Helper account token: scopes repo + write:discussion

Part D — Install and run

git clone https://github.com/rajairfanahmed/github-achievement-unlocker-badge-automation-toolkit
cd github-achievement-unlocker-badge-automation-toolkit
npm install      # automatically creates .env from .env.example
# fill in your .env values
npm start        # CLI
npm run web:dev  # Dashboard at localhost:3000
Enter fullscreen mode Exit fullscreen mode

A Note on Public Sponsor and Starstruck

We manage these two in distinct ways. The tool does not provide hacks or shortcuts for them.

Public Sponsor — You sponsor on GitHub first (real sponsorship). The tool only verifies your account's public sponsor state afterward.

Starstruck — Requires real stars from real users. The tool can poll your star count and help you track progress, but the stars have to be genuine.

Local State, Not GitHub State

The system saves progress to achievements-data-<username>.json in the project root. Git has ignored this file. It tracks local operation history and tier progress. It does not interact with GitHub's badge system in a direct manner. GitHub awards badges on its end based on the actual actions performed.

Common Mistakes to Avoid

Wrong Right
TARGET_REPO=https://github.com/user/repo TARGET_REPO=user/repo
Same token for both accounts Separate tokens, separate accounts
Helper invited but invite not accepted Helper must accept the invite
GITHUB_TOKEN="ghp_..." with quotes GITHUB_TOKEN=ghp_... without quotes

Built On

This project is based on and improved from the original work by n0.

This version includes several updates

  • A local Next.js dashboard
  • A live rate limit display
  • Achievement cards with tier protection (finished tiers can't be rerun)
  • Cooperative stop behavior
  • History pagination
  • Post-install bootstrap for .env

Requirements

  • Node.js 18+
  • npm
  • Two GitHub accounts
  • A test repository owned by the main account

Repo

Everything is open source. Check the setup guide, the .env.example, and the dashboard at:

👉 github.com/rajairfanahmed/github-achievement-unlocker-badge-automation-toolkit

If this saves you time, drop a star — it helps others find it.

Top comments (0)