🧭 SWECC OSS Explorer

A SWECC Labs project: a polished, searchable browser for open issues across the ~100 most active open-source projects on GitHub — available as a Python CLI and a web app.

Think "good first issue" aggregator, but with actual UX.

Philosophy

Nothing is stored, anywhere. There is no database, no cache server, no background crawler. Every search hits the GitHub REST API live and shows you exactly what GitHub sees right now. The only thing ever saved is an optional personal access token, and that lives in your own browser's localStorage — never on a server.

Surface	What it is	Where it lives
CLI	swecc-oss — search issues from your terminal	src/swecc_oss_explorer/
Website	filterable, shareable issue browser	web/ (static, zero build step)

The website is themed with the SWECC design system: its tokens and component styles are ported by hand into web/styles.css because @swecc/ui is a React + StyleX library and this site intentionally has no build step.

Quickstart (CLI)

Requires Python 3.10+.

git clone https://github.com/swecc-uw/swecc-oss-explorer
cd swecc-oss-explorer
pip install -e .

# Open issues across the top 100 most active repos on GitHub (default)
swecc-oss explore

# Only issues created in the last week; or 'any' to disable the age filter
swecc-oss explore --max-age 1w
swecc-oss explore --max-age any

# Python issues needing docs help in active projects, newest first
swecc-oss explore --label documentation --language python

# Free text search, JSON output for scripting
swecc-oss explore --scope all --query "pagination" --json
swecc-oss repos --scope top --json

GitHub allows 10 searches/minute unauthenticated. Set GITHUB_TOKEN to raise that to 30/minute — any token with no extra scopes works.

export GITHUB_TOKEN=ghp_yourtokenhere

Website

The site is plain HTML/CSS/JS in web/ — no build step, no framework, no npm install. Open web/index.html in a browser or serve it:

python -m http.server 8000 --directory web

A Max age filter (default: past 2 months) keeps results fresh; it's shareable in the URL via the age parameter (in days, or age= for any time).

It deploys automatically to GitHub Pages via .github/workflows/deploy-pages.yml (enable Settings → Pages → Source: GitHub Actions once).

How scope discovery works

Both surfaces build queries the same way — see src/swecc_oss_explorer/query.py:

• top scope — GitHub caps search queries at 256 characters, so OR-ing 100 repo: qualifiers in one query isn't possible. Instead we (1) discover the top repos with a single stars + recency heuristic (stars:>5000 pushed:>=last-30-days, sorted by stars), (2) greedily pack them into repo:-qualifier batches that each fit the 256-char budget, and (3) run one live search per batch, merging and re-sorting the results. The website streams batches in as they arrive, so results appear progressively.
• all scope — one global issue search, no repo filtering.

Both steps are live on every request. The activity heuristic is deliberately simple and tracked in #7.

Project structure

src/swecc_oss_explorer/
├── cli.py         # typer commands: explore, repos, web, version
├── github.py      # minimal stateless GitHub REST client
├── discovery.py   # top-100-active heuristic
├── query.py       # query building (256-char budget, scoping rules)
└── explore.py     # chunked multi-repo search orchestration
web/
├── index.html     # single-page app shell
├── app.js         # live search, filters, URL sync, progressive batch search
└── styles.css     # @swecc/ui design tokens, ported to vanilla CSS

Contributing

This repo is intentionally seeded with beginner-friendly issues so SWECC members can make their first open-source contribution here. Start with issues labeled good first issue, then read CONTRIBUTING.md.

License

MIT