myGeeKy

Find GitHub people who share your research — and will actually follow you back.
_{Your CV, your repos, your ORCID & Google Scholar papers → people and projects worth your time.}

Quick start · Live panel · How it works · Safety · All settings

_{Real screenshots, real data: the Live feed, people likely to follow back, and repos you could contribute to.}

Why this exists: I don't have Facebook. I only want to follow people I can genuinely learn from — and who might learn something from me too. myGeeKy is a GitHub-friendly alternative for people like me: we want real friends, and we're wary of fake ones.

✨ Highlights

🚀 Quick start

pip install "mygeeky[gui,pdf]"
mygeeky init          # GitHub username (required); CV, ORCID, Google Scholar (optional)
mygeeky run           # who to follow
mygeeky contribute    # which repos to improve
mygeeky gui           # the live panel

init asks a few questions — only your GitHub username is required, every other answer can be skipped and changed later. Details in Quick start below.

🪟 The live panel

Live — friends' activity + top suggestions, scrolling	Suggestions — click someone to open them; they leave the list	Repos — projects in your field with starter issues
Activity — what people you follow are doing	Model — how well it predicts follow-backs, over time	Folded — just the icon on the screen edge, half-transparent until you hover it

More in Live glass panel below.

How it works

GitHub's Markdown renderer strips <script> tags (security), so it can't run a live JS diagram inline — the image below is a preview of a real, animated, click-to-expand HTML/JS page that ships in this repo at docs/flowchart.html:

▶ Open the live interactive version — real vanilla JS (click any step to expand it), served straight off this repo via githack, no build step, no server. (If that link is ever slow/unavailable: clone the repo and open docs/flowchart.html directly in a browser — it's fully self-contained, zero dependencies.)

The pink "You follow — by hand" step is the only place a follow ever happens — myGeeKy has no follow/unfollow code anywhere in the project; see Safety.

What it does

1. Understands you — reads your CV (txt/md/pdf), your own GitHub repos (languages, topics, descriptions) and, if you give them, your ORCID/OpenAlex and Google Scholar publications to build a profile of what you're into, and auto-derives a weighted "domain vocabulary" from that corpus (not a hardcoded field-specific wordlist).
2. Collects candidates from multiple sources, not just a plain search: the owners and contributors of active repos matching your research terms (ranked first — a plain language search mostly returns famous accounts), GitHub user search (language/location/follower filters), followers of well-known accounts in your field (seed_accounts), stargazers of relevant repos (seed_repos), stargazers of your own repos, and optionally second-degree contacts (people followed by people you already follow). Candidates corroborated by more than one source get a small ranking boost.
3. Filters out noise before scoring: accounts following more than max_following people (a growth-hacking/mass-follow pattern, not genuine engagement), dormant/throwaway-looking accounts, organizations, and — for the top-ranked candidates — a real per-repo activity check (a maintained repo pushed to recently, or a freshly-created one; a profile's updated_at alone can just reflect a bio edit).
4. Scores each surviving candidate on:
   • content similarity to your CV/repos (TF-IDF + cosine similarity)
   • how likely they are to follow back (their own following/follower ratio); for the follow-back list, accounts that follow almost nobody relative to their audience, or have more than followback_max_followers, are skipped
   • how active their account is
   • once you've used it a while: a learned model (see below)
5. Suggests two ranked lists, not one — printed, or returned as JSON. Nothing is followed automatically:
   • Likely to follow back — the blended score above.
   • Domain-fit highlights — ranked purely by match to your CV/repos, independent of follow-back likelihood. A senior domain expert who follows almost no one on GitHub is exactly who the follow-back score would otherwise bury, and is often the best actual match.
6. Learns from real outcomes, not just from waiting:
   • mygeeky bootstrap seeds the model immediately from accounts you already follow (checks, read-only, who already follows you back) — so you get real training data on day one instead of waiting weeks.
   • mygeeky learn (meant to run weekly) looks at who you actually followed since the last check, checks whether they followed back, and retrains a logistic-regression model on the growing set of outcomes — reporting cross-validated AUC so you can see how trustworthy it is, and excluding mass-follow outliers from training.

Repos you could improve (mygeeky contribute)

Beyond people, myGeeKy suggests repositories you could fork, improve, and realistically get merged, matched to your CV, repos, and publications:

mygeeky contribute          # search + rank (a few minutes; GitHub's search API is rate-limited)
mygeeky contribute --last   # re-print the last results
mygeeky contribute --json   # for scripts / AI agents

1. Your profile is turned into a handful of search terms: your publications' OpenAlex keywords, topics used across your repos, and the CV vocabulary. Explicit topics / contribute_extra_terms always come first.
2. GitHub is searched for active, non-archived, non-fork repos matching those terms that have open good first issue / help wanted issues.
3. Each repo is ranked on fit (content similarity, a language you use, recency), then the top few get the check that actually predicts a merge: of its recently closed PRs from outside contributors, how many did the maintainers merge? Bot PRs and insiders' own PRs don't count.
4. Each suggestion lists its unassigned, recent starter issues and a plain-language "why".

As with people, this only ever suggests: there is no fork, PR, or comment code anywhere. You open the repo, fork it, and send the PR yourself.

Your profile: CV + GitHub + ORCID/OpenAlex + Google Scholar

mygeeky profile refresh --cv ~/cv.pdf --orcid 0000-0002-1825-0097 \
    --scholar "https://scholar.google.com/citations?user=XXXXXXXXXXXX"   # all remembered
mygeeky profile refresh     # after updating your CV: re-extract the PDF, re-fetch publications
mygeeky profile show        # what myGeeKy knows about you (no network)

• CV: PDF/txt/md, converted to text (pip install "mygeeky[pdf]" for PDF).
• ORCID (public API) and OpenAlex (looked up by your ORCID): your publication titles, abstracts, keywords and research topics. They're free and need no key. They feed both people matching and repo suggestions.
• Google Scholar (optional): your research interests and up to 100 paper titles, read from your own public profile page. Scholar has no API and limits automated access, so this is one request per profile refresh, never part of a normal run; if Google refuses it, the last fetched copy is kept and ORCID/OpenAlex still cover your publications.

Use it from any computer (mygeeky sync)

Your myGeeKy data can live in a private GitHub repo, so the model keeps learning no matter which machine you run it on:

mygeeky sync init                      # creates <you>/mygeeky-data (private) and pushes
mygeeky sync init --repo you/other     # or use/choose another private repo
mygeeky sync pull | push | status

On a new computer: pip install mygeeky, then gh auth login and mygeeky sync init again. It pulls your config, CV text, publications, history and training data. mygeeky pipeline (the weekly job) then does pull → learn → run → contribute → push automatically.

• It refuses to sync to a public repo.
• Never synced: any token, caches, logs, and the pickled model. Loading a pickle that came over the network could run code, so the model is retrained locally from the synced training data instead.
• .jsonl logs use git's union merge, so two machines in the same week merge cleanly.
• Git uses your own gh/git credentials. myGeeKy's API client stays read-only.

Install

pip install mygeeky

(For PDF CVs: pip install "mygeeky[pdf]".)

Quick start

mygeeky init      # asks for your GitHub username, CV, and the kind of people you're looking for
mygeeky run       # get your first batch of suggestions

mygeeky init asks a short set of questions — all optional, all editable later:

• Your GitHub username (the only required answer)
• Your CV (a file path, pasted text, or skip)
• Your ORCID iD and your Google Scholar profile URL (each optional)
• Languages / topics / keywords / locations you're looking for
• Optional extra candidate sources: well-known accounts in your field, relevant repos
• Follower-count range, max_following, minimum repo count, how many suggestions per run

Then it offers to store a GitHub token (see Safety — this is handled very deliberately), and — if a token is set up — offers to run mygeeky bootstrap immediately so you're not starting the learning model from zero.

Everyday use

mygeeky run                 # search + rank + suggest (two lists: followback + domain-fit)
mygeeky run --json          # same, as JSON (for scripts / AI agents)
mygeeky suggestions         # re-print the last run's results without re-querying GitHub
mygeeky bootstrap           # seed the model from accounts you already follow (run once, early)
mygeeky learn               # check who you followed since last time, learn from who followed back
mygeeky contribute          # repos you could fork, improve, and get merged
mygeeky profile refresh     # re-read your CV + publications (ORCID/OpenAlex)
mygeeky sync push|pull      # keep your data in your private GitHub repo
mygeeky pipeline            # sync pull, learn, run, contribute, sync push — the weekly job
mygeeky gui                 # launch the live glass panel (needs `pip install "mygeeky[gui]"`)

Running it weekly

myGeeKy doesn't run in the background by itself — you decide when it's allowed to touch your OS's task scheduler:

mygeeky schedule show          # print the exact command/cron line for your OS (does nothing)
mygeeky schedule install --yes # actually register it (Windows Task Scheduler / cron)
mygeeky schedule remove        # undo it

The scheduled job runs mygeeky pipeline — i.e. it checks and learns from what you did last week, then produces new suggestions. It still never follows anyone.

Live glass panel (optional GUI)

pip install "mygeeky[gui]"
mygeeky gui          # (or the standalone `mygeeky-gui` command)

A small, translucent, always-on-top panel docked to the edge of your screen (Windows and Linux), built with PySide6/Qt — native widgets, not a webview. (An earlier version used pywebview; its WebView2-on-Windows transparency turned out to be a confirmed, currently inconsistent upstream bug that even its maintainer can't reproduce reliably across machines — see pywebview#1611. Qt's WA_TranslucentBackground is the mature, well-supported way apps actually get real per-pixel window transparency on Windows.) Click the folded tab to expand it; click the arrow to fold it back to a slim strip.

• Suggestions tab — both lists from mygeeky run (avatar, bio, score), each with an Open → button that opens their GitHub profile in your browser. That's the only thing a click ever does — myGeeKy still never follows anyone; a "Refresh" button re-runs a real search on demand (it never does this on a timer, to avoid hammering GitHub's rate limits).
• Repos tab — the results of mygeeky contribute: repos you could improve, each with why it fits you, its top starter issues, and Fork → / Open → buttons. Those buttons only open the GitHub page; forking and the PR stay yours. It shows the last run's results, and "Refresh" runs a new repo search only when you click it.
• Activity tab — a live feed of what people you follow are actually doing (pushes, merged PRs, new repos, releases, stars...), from GitHub's own events API. Refreshes automatically, but no more often than gui_activity_refresh_minutes (default 5) — and that refresh is a single cheap API call, not a full search.
• Model tab — a chart of your learned model's cross-validated AUC and training-set size over time, so you can watch it actually improve as you run mygeeky bootstrap/learn.

⚙ Settings — click the small gear icon in the header to open a compact panel with:

• Theme, switchable live (no restart needed): Midnight Glass (dark, cool-toned, the default), Frosted White (light, warm, iOS-control-center-like), and Vibrant Aurora (saturated, colorful, leans into the geeky/hearts branding).
• Transparency, a slider from 0% (fully opaque) to 100% (fully transparent), applied live as you drag.

Both choices are saved (gui_theme, gui_opacity) and remembered next time you open the panel.

Clicking a person in the Suggestions list (or a suggestion in the Live tab) opens their profile and removes them from the list — they're added to your excluded list, so later runs skip them too. People you follow from the browser drop out on the next activity refresh (within gui_activity_refresh_minutes).

Folded, the panel shrinks to just the app icon on the screen edge, half-transparent until you hover it. It always stays inside the screen it's on, including on multi-monitor setups.

Config: gui_dock_side ("right"/"left"), gui_expanded_width, gui_folded_width, gui_folded_height, gui_folded_opacity, gui_panel_height_fraction, gui_activity_refresh_minutes, gui_activity_limit, gui_theme ("midnight"/"frosted"/"aurora"), gui_opacity (0.0-1.0, note the settings panel's slider shows this inverted, as "Transparency") — same mygeeky config set mechanism as everything else.

No LLM/AI is used anywhere in the GUI (or the rest of myGeeKy) — the suggestions, activity feed, and model chart are all built from the same TF-IDF/logistic-regression pipeline the CLI uses, so there's no API cost and nothing to configure to make it work. (There's deliberately no way to plug in a Claude subscription either — that kind of auth is scoped to Claude Code itself and isn't something a third-party tool can piggyback on; if you ever want AI-written explanations, that'd be a separate opt-in using your own API key or a local model, not something myGeeKy needs.)

Rendering note: the panel is genuinely transparent (real per-pixel alpha, confirmed on Windows 11), but it's a flat translucency, not a blurred "frosted glass" effect — Windows' native DWM Acrylic/Mica backdrop was tried and turned out to conflict with Qt's own transparency on tested hardware, reliably making the window opaque instead, so it isn't wired up. On Linux, real transparency depends on your compositor/window manager the same way it does for any Qt app.

All parameters (adjustable, or leave at the defaults)

mygeeky config show
mygeeky config set max_followers 3000
mygeeky config set languages "Python, Rust, Go"
mygeeky config reset

Safety

• No follow/unfollow code exists in this project. github_client.py only implements read endpoints (GET). There is no method that calls PUT /user/following/*, so myGeeKy cannot follow anyone even by accident, regardless of what token scope you provide.
• Your GitHub token is never written to a file. It's requested with hidden input (getpass) and stored only in your OS's encrypted secret store via the keyring package (Windows Credential Locker / macOS Keychain / Linux Secret Service). mygeeky auth status shows where it's coming from — never the value. An environment variable (MYGEEKY_GITHUB_TOKEN) is supported as an explicit, opt-in fallback for CI/agent contexts.
• Token fallback to the GitHub CLI. If no keyring token or env var is set, myGeeKy uses gh auth token when gh is logged in. This is still only used for GET requests.
• Sync writes only to your own private data repo, through git with your own credentials, never through myGeeKy's API client.
• Minimal token scope. myGeeKy only reads public profile/repo/follower data — create your token with no scopes at all, or a fine-grained token limited to read-only public repositories/followers. Never grant it write or admin scopes.
• All local state (config, CV text, suggestion history, the learned model) lives under your OS's standard config/data directories, not inside this project folder, so nothing personal ever ends up in a repo or a published package by accident.
• The GUI follows the same rule. open_profile() (the only thing a click in the panel can trigger) refuses to open anything that isn't a https://github.com/... URL, and there's no other code path from the panel to the network beyond the read-only suggestion/activity fetches described above.

Using myGeeKy from an AI agent / script

Every result-producing command supports --json:

mygeeky run --json

{
  "followback": [
    {
      "username": "example-geek",
      "profile_url": "https://github.com/example-geek",
      "score": 0.4123,
      "score_breakdown": {"heuristic": 0.41, "ml_proba": null, "blended": 0.41},
      "features": {
        "content_similarity": 0.31,
        "follow_back_ratio": 0.9,
        "activity_recency": 1.0,
        "shared_languages": 0.5,
        "shared_topics": 0.33
      },
      "domain_fit": 0.62,
      "followers": 120,
      "following": 140,
      "public_repos": 34,
      "bio": "...",
      "sources": ["search:language:Python followers:0..20000 ...", "starred_your_repo:you/tool"],
      "n_sources": 2,
      "timestamp": "2026-09-17T12:00:00+00:00",
      "list": "followback"
    }
  ],
  "domain_highlights": [
    { "...": "same shape, ranked by domain_fit instead of score", "list": "domain" }
  ]
}

An agent can read this list and present it to you — it should never be wired up to auto-follow anyone; that defeats the entire point of this tool.

How the "learning" works

Two lists, on purpose

mygeeky run produces a followback list (ranked by the blended score above) and a domain_highlights list (ranked purely by domain_fit, an auto-derived match to your CV/repo vocabulary, independent of follow-back likelihood). These optimize for different things: some of the best domain-specific matches — senior researchers, niche maintainers — follow almost no one on GitHub, so the reciprocation model correctly scores them low even though they may be the best actual fit. Both lists go through the same activity-QC and bot/dormant filters.

License

MIT — see LICENSE.