GitHub Download Button

The download button GitHub forgot to ship.

---

What it does

GitHub is great for storing software. It is not great for downloading it. Most repos bury their releases under tabs, use inconsistent naming for assets, and give no indication of whether a file requires a terminal or will just open like a normal app.

GitHub Download Button solves that. Paste any public GitHub repo URL and it surfaces the correct download for your operating system, classifies whether the release is a simple double-click installer or something that requires developer knowledge, and summarises the README so you know what you are getting before you commit to the download.

The project ships in two forms: a web app you can open in a browser, and a Chrome extension that injects a floating panel on any GitHub repository page so you never have to leave the tab.

---

Features

• OS detection. Automatically highlights the release asset that matches your platform, Windows, macOS, or Linux, and pushes it to the top of the list.
• Three-tier complexity rating. Every repo is rated Simple (download and run, litle to no setup needed), Technical (has releases but needs a runtime like Java), or Highly Technical (requires a terminal to run, built for developers). The rating is determined by a README parser that reads installation instructions, detects terminal commands in user-facing sections, identifies the tech stack, and checks for runtime prerequisites.
• README summaries. The backend extracts a plain-text summary from the README so you know what the project does before downloading anything.
• Chrome extension. A shadow-DOM panel injects on any github.com/owner/repo page, auto-fetches release data, and dismisses per session. The popup also works as a standalone search for repos you are not currently viewing.
• No login, no tracking. Everything goes through GitHub's public API. No account required.

---

How it works

Browser / Extension
       |
       | GET /api/repo?owner=&repo=
       v
  Express backend
       |
       |-- GitHub API: repo metadata
       |-- GitHub API: releases (up to 5)
       |-- GitHub API: README (base64 decoded)
       |
       |-- analyzeReadmeComplexity()
       |     Splits README by section, skips build/dev headings,
       |     scores asset filenames and prose signals to return
       |     Simple / Technical / Highly Technical
       |
       |-- extractSummary(): plain-text excerpt from README prose
       |
       v
  JSON response: { repoJson, releases, readmeSummary, appRating }
       |
       v
  React frontend: OS-filtered asset list, rating badge, README summary

---

Stack

Layer	Technology
Frontend	React 18, Vite 6, vanilla CSS
Backend	Node.js 18+, Express 4
GitHub data	GitHub REST API v3, public endpoints
Extension	Chrome Manifest V3, shadow DOM, no build step
Deployment	Railway, Render, or Fly.io

---

Project structure

github-download-button/
  web-app/
    server.js          Express server, GitHub API proxy, README analysis
    vite.config.js     Vite config, proxies /api to Express in dev
    package.json
    client/
      index.html       Vite entry point
      public/          Static assets (logo, author mark)
      src/
        main.jsx       ReactDOM entry
        App.jsx        Main React application
        icons.jsx      SVG icon components
        styles.css     All styles
  extension/
    manifest.json      Chrome MV3 manifest
    utils.js           Shared: detectOS, labelAsset, enrichReleases, computeRating, fetchRepo
    content.js         Injected panel on GitHub repo pages
    popup.js           Extension popup logic
    popup.html         Popup shell
    popup.css          Popup styles

---

Running locally

Prerequisites: Node.js 18+. A GitHub personal access token is optional but raises the rate limit from 60 to 5,000 requests per hour.

git clone https://github.com/madebyorunto/github-download-button.git
cd github-download-button/web-app

npm install

# Copy and fill in environment variables
cp .env.example .env.local

npm run dev

This starts both the Express server (port 3000) and the Vite dev server (port 5173) in parallel. Open http://localhost:5173. The Vite dev server proxies /api requests to Express, so both hot module replacement and the backend work at the same time.

To build and serve the production bundle locally:

npm run build
npm start        # serves client/dist from Express on port 3000

---

Deploying

The web app is a standard Node.js server. Any platform that runs npm run build && npm start works.

Railway / Render: Connect the repo, set the root directory to web-app/, add GITHUB_TOKEN and ANTHROPIC_API_KEY as environment variables. Both platforms detect the start script automatically.

Fly.io: Same, using fly launch inside web-app/.

---

Loading the Chrome extension

1. Open chrome://extensions in Chrome.
2. Enable Developer mode in the top right.
3. Click Load unpacked and select the extension/ folder.
4. The extension injects automatically on any github.com/owner/repo page, provided the backend is running at http://localhost:3000.

To point the extension at a deployed backend, update RG_BACKEND at the top of extension/utils.js before loading it.

---

Environment variables

Variable	Required	Description
GITHUB_TOKEN	No	Personal access token. Raises the GitHub API rate limit from 60 to 5,000 requests per hour.
PORT	No	Port the server listens on. Defaults to 3000.

---

Contributing

Pull requests are welcome. A few things to keep in mind before opening one.

Branching. Branch off master. Name your branch after what it does: fix/asset-detection, feat/firefox-extension, refactor/rating-algorithm.

Opening a PR. Describe what the change does and why. If it touches the rating algorithm, include a few repo URLs that demonstrate the before and after behaviour.

Issues. Bug reports should include the repo URL that triggered the issue, the rating shown, and what you expected. Feature requests should explain the user problem, not just the proposed solution.

Scope. This tool is for non-technical users who just want to download an app. Features that add complexity for the sake of power-users are out of scope. Keep the surface simple.

---

Built by Orunto Eniola. Public beta.