<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset=".github/logo-dark.svg">
    <img src=".github/logo.svg" width="220" alt="The Git for Me mascot: an ink-drawn hermit crab that has just moved into a spiral shell it found, eyes on stalks looking up at it, one claw raised, an exclamation mark beside it">
  </picture>
</p>

<h1 align="center">Git for Me</h1>

<p align="center">
  <a href="https://www.npmjs.com/package/git-for-me"><img src="https://img.shields.io/npm/v/git-for-me?color=cb3837&logo=npm" alt="npm"></a>
  <a href="https://github.com/bikemeardsley/git-for-me/actions/workflows/test.yml"><img src="https://github.com/bikemeardsley/git-for-me/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
  <a href="https://registry.modelcontextprotocol.io/?q=git-for-me"><img src="https://img.shields.io/badge/MCP_Registry-111111?logo=modelcontextprotocol&logoColor=white" alt="In the official MCP Registry"></a>
  <a href="https://skills.sh/bikemeardsley/git-for-me/git-for-me"><img src="https://img.shields.io/badge/skills.sh-111111" alt="On skills.sh"></a>
  <a href="https://cursor.directory/plugins/git-for-me"><img src="https://img.shields.io/badge/cursor.directory-111111?logo=cursor&logoColor=white" alt="On cursor.directory"></a>
  <a href="https://smithery.ai/skills/bikemeardsley/git-for-me"><img src="https://img.shields.io/badge/Smithery-FF5601?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxODggMjExIiBmaWxsPSIjZmZmIj48cGF0aCBkPSJNNDEuNzAxMSA3Ny40OEgwVjEwMC4yNjRDMCAxMTguMTcxIDE0LjUyNzUgMTMyLjY5OCAzMi40MzQyIDEzMi42OThINTUuMjE4M1Y5MC45OTcxQzU1LjIxODMgODMuNTQxOCA0OS4xNTY1IDc3LjQ4IDQxLjcwMTEgNzcuNDhaIi8%2BPHBhdGggZD0iTTY2LjA4NzkgOTAuOTk3MVYxMzIuNjk4SDEwNy43ODlDMTE1LjI0NCAxMzIuNjk4IDEyMS4zMDYgMTI2LjYzNiAxMjEuMzA2IDExOS4xODFWNzcuNDhINzkuNjA1MUM3Mi4xNDk3IDc3LjQ4IDY2LjA4NzkgODMuNTQxOCA2Ni4wODc5IDkwLjk5NzFaIi8%2BPHBhdGggZD0iTTE1NC45OTUgNzcuNDhIMTMyLjIxVjExOS4xODFDMTMyLjIxIDEyNi42MzYgMTM4LjI3MiAxMzIuNjk4IDE0NS43MjggMTMyLjY5OEgxODcuNDI5VjEwNi4xNTJDMTg3LjQyOSA4OC4yNDQ5IDE3Mi45MDEgNzcuNTE0OCAxNTQuOTk1IDc3LjUxNDhWNzcuNDhaIi8%2BPHBhdGggZD0iTTAgNDUuOTUxNFY2Ni42MTAzSDQxLjcwMTFDNDkuMTU2NSA2Ni42MTAzIDU1LjIxODMgNjAuNTQ4NSA1NS4yMTgzIDUzLjA5MzJWMEMyNS44NDk4IDAuMjA5MDI4IDAuMDM0ODM4IDE0LjY2NjggMCA0NS45NTE0WiIvPjxwYXRoIGQ9Ik02Ni4wODc5IDUzLjA5M0M2Ni4wODc5IDYwLjU0ODMgNzIuMTQ5NyA2Ni42MTAxIDc5LjYwNTEgNjYuNjEwMUgxMjEuMzA2VjExLjQ2MTVDMTAwLjkyNiA4LjM2MDkyIDkwLjMwMDMgMS43NDE2OSA2Ni4wODc5IDAuMjQzNjUyVjUzLjA1ODFWNTMuMDkzWiIvPjxwYXRoIGQ9Ik0xNDQuMDkgMTMuMDYzOUMxMzkuNzcgMTMuMDYzOSAxMzUuODM0IDEyLjkyNDYgMTMyLjIxIDEyLjY4MDdWNjYuNjFIMTU0Ljk5NUMxNzIuOTAxIDY2LjYxIDE4Ny40MjkgNTIuMDgyNSAxODcuNDI5IDM0LjE3NThWMC4xNzM4MjhDMTc3LjI5MSA4LjExNjkgMTYyLjkwMyAxMy4wNjM5IDE0NC4wOSAxMy4wNjM5WiIvPjxwYXRoIGQ9Ik0wIDE3Ni4wMDJWMjEwLjAwNEMxMC4xMzc5IDIwMi4wNjEgMjQuNTI2IDE5Ny4xMTQgNDMuMzM4NSAxOTcuMTE0QzQ3LjY1ODQgMTk3LjExNCA1MS41OTUxIDE5Ny4yNTMgNTUuMjE4MyAxOTcuNTMyVjE0My42MDNIMzIuNDM0MkMxNC41Mjc1IDE0My42MDMgMCAxNTguMTMgMCAxNzYuMDM3TDAgMTc2LjAwMloiLz48cGF0aCBkPSJNMTA3Ljc4OSAxNDMuNjAzSDY2LjA4NzlWMTk4LjcxNkM4Ni40NjgxIDIwMS44MTcgOTcuMDkzOCAyMDguNDM2IDEyMS4zMDYgMjA5LjkzNFYxNTcuMTJDMTIxLjMwNiAxNDkuNjY0IDExNS4yNDQgMTQzLjYwMyAxMDcuNzg5IDE0My42MDNaIi8%2BPHBhdGggZD0iTTEzMi4yMSAxNTcuMDg1VjIxMC4xNzhDMTYxLjU0NCAyMDkuOTY5IDE4Ny4zMjQgMTk1LjUxMSAxODcuNDI5IDE2NC4yOTZWMTQzLjU2OEgxNDUuNzI4QzEzOC4yNzIgMTQzLjU2OCAxMzIuMjEgMTQ5LjYzIDEzMi4yMSAxNTcuMDg1WiIvPjwvc3ZnPg%3D%3D" alt="On Smithery"></a>
  <a href="https://github.com/search"><img src="https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white" alt="GitHub"></a>
  <a href="https://gitlab.com/explore/projects"><img src="https://img.shields.io/badge/GitLab-FC6D26?logo=gitlab&logoColor=white" alt="GitLab"></a>
  <a href="https://codeberg.org/explore/repos"><img src="https://img.shields.io/badge/Codeberg-2185D0?logo=codeberg&logoColor=white" alt="Codeberg"></a>
  <br>
  <a href="#development"><img src="https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white" alt="TypeScript"></a>
  <a href="#install"><img src="https://img.shields.io/node/v/git-for-me?color=339933&logo=nodedotjs&logoColor=white" alt="Node 22.18 or later"></a>
  <a href="LICENSE"><img src="https://img.shields.io/npm/l/git-for-me?color=blue" alt="MIT license"></a>
  <a href="https://buymeacoffee.com/bikemeardsley"><img src="https://img.shields.io/badge/Buy_Me_a_Coffee-FFDD00?logo=buymeacoffee&logoColor=black" alt="Buy Me a Coffee"></a>
  <a href="https://www.als.net/donate/"><img src="https://img.shields.io/badge/Donate-ALS_Research-blueviolet" alt="Donate to ALS research"></a>
</p>

Odds are, most of what you want to build is already open source. Tell your AI
agent what you're making, and it finds it: which repos to use as they are,
which to adapt, and what's left for you to write. Every repo it names is real,
licensed for your use or flagged, and checked live.

It searches GitHub, GitLab and Codeberg. Works with Claude Code, Codex,
Copilot, Cursor, Gemini CLI, Cline, Devin, Open WebUI and any other MCP
client, or as an Agent Skill.

Its companion, [Where My Hug At?](https://github.com/bikemeardsley/where-my-hug),
does the same for Hugging Face models.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset=".github/flow-dark.svg">
    <img src=".github/flow.svg" width="820" alt="What you want to build, with four questions asked first (stack, platform, license, upkeep), is split into parts: jobs with an input and an output. A part a repo might do goes to Find it, which searches GitHub, GitLab and Codeberg: the most starred in the topic and names holding each keyword, and on GitHub the rising repos and README text too. Its verdict, use, adapt or build, comes from what the search found. A part not worth a dependency is marked write and needs no search. Your report checks every pick live: real, licensed, with its risks flagged.">
  </picture>
</p>

## Contents

- [Try it](#try-it)
- [How it works](#how-it-works): [four questions](#1-four-questions-first) ·
  [parts](#2-split-the-job) · [the search](#3-search-for-each-part) ·
  [verdicts](#4-decide-each-part-from-what-turned-up) ·
  [the live check](#5-check-every-pick) · [flags](#flags)
- [Example: PDF invoices](#example-pdf-invoices)
- [Install](#install) (every agent, step by step: [USAGE.md](USAGE.md))
- [What leaves your machine](#what-leaves-your-machine) · [Limits](#limits) ·
  [Security](#security)
- [Development](#development) · [License](#license)

## Try it

Add it to your agent (Claude Code here; [every other option](#install) below):

```sh
claude mcp add --scope user git-for-me -- npx -y git-for-me
```

Then ask:

> **Git for me: a CLI that pulls the tables out of PDF invoices into a spreadsheet.**

Your agent asks the few things it can't guess, splits the job into parts, and
comes back with a report like the [one below](#example-pdf-invoices), every
repo in it looked up moments before. It works for anything made of code:

> Git for me: typo-tolerant search for the recipes on my Next.js site.<br>
> Git for me: a nightly job that backs up Postgres to S3 and tells Slack if it fails.<br>
> Git for me: a browser extension that saves recipes without the life story.

## How it works

### 1. Four questions first

Ask for "a library that reads PDFs" and you get whatever is popular: in the
wrong language, under a license you can't ship, or abandoned years ago. So
before anything is named, four details come first. Your agent fills in what
the conversation or your codebase already says, and asks you the rest:

| | What it asks | What that decides |
|---|---|---|
| **Stack** | What will it be written in?<br>_TypeScript on Node, Python 3.12, Rust_ | Which repos work as libraries, and which only beside your code |
| **Platform** | Where will it run?<br>_a web app, a CLI, a server, a phone app_ | What fits at all |
| **License** | What may the result be used for?<br>_commercial, open source, personal_ | Which licenses are allowed |
| **Upkeep** | How much code are you willing to own?<br>_needs to stay maintained, happy to own a fork_ | A maintained dependency, or a fork you keep up |

"Not sure yet" is a fine answer: the picks then cover the range.

### 2. Split the job

The agent breaks the need into parts, each with an input and an output (a PDF
→ its tables, tables → a spreadsheet). A part not worth a dependency (glue,
configuration, logic only your project has, a few lines) is marked **WRITE**:
a dependency for ten lines is a cost, not a feature.

### 3. Search for each part

What an agent remembers of open source is as old as its training, and misses
the long tail. So nothing is picked from memory. For every other part, the
agent writes a search (a topic, the stack's language, a few keywords, the job
in a few words), and it runs on three forges:

| Way | What it finds | Where |
|---|---|---|
| Most starred in the topic | What's proven | GitHub, GitLab, Codeberg |
| Rising in the topic | New repos gaining stars, including ones newer than the agent's training | GitHub |
| Names and descriptions holding each keyword | Tools that aren't tagged with the topic | GitHub, GitLab, Codeberg |
| README text | The long tail, by what the README says, like a web search | GitHub |

The ways take turns in the results, so a niche tool isn't buried under
whatever is most starred. Archived repos are left out everywhere, and so are
forks on GitHub and Codeberg. A stack that can use more than one language
(TypeScript can use JavaScript) searches them all.

### 4. Decide each part from what turned up

| Verdict | Meaning |
|---|---|
| **USE** | A repo the search found does this job as it is: depend on it, or run it beside your code. |
| **ADAPT** | One comes close: fork it or copy the part you need, license permitting. |
| **BUILD** | Nothing it found does the job: build it, reading the closest repos first. |
| **WRITE** | Not worth a dependency: write the code. |

The agent judges the results by what they say: description, stars, recent
activity, license, language. It may add a repo it knows that the search
missed, but that pick ranks after the search's, and the report marks it
**from memory**.

### 5. Check every pick

Every pick is looked up on its forge, live. Any that don't exist are dropped,
and the agent goes back to the search for others. The rest are flagged for
what would bite later, and that report is what you see. It also lists what
the search found that wasn't picked, so nothing it turned up is hidden. A
BUILD part whose search found repos says to check them before building one.

Under the hood it's an MCP server with three tools: `git_for_me` for the
method (steps 1, 2 and 4), `git_for_me_search` for step 3, and
`git_for_me_verify` for step 5.

### Flags

| Flag | When |
|---|---|
| UNCHECKED | Its forge didn't answer (down, rate-limited). The repo is kept, and asked again next time. |
| ARCHIVED | Read-only: every fix is yours. |
| NO_LICENSE | No license: all rights reserved, so its code may not be reused. |
| OWN_TERMS | A license its forge can't identify: read it. |
| UNKNOWN_LICENSE | On Codeberg, which names no licenses: it has a license file, so read it. |
| COPYLEFT | GPL, AGPL and kin: shipping it with your code can bind your code to its license. |
| WEAK_COPYLEFT | LGPL, MPL and kin: changes to it must be shared, but using it unchanged usually doesn't bind your code. |
| STALE | No pushes in two years. |
| LITTLE_USED | Under 50 stars. |
| FORK | A fork: check whether the original is the better pick. |
| MIRROR | A mirror: pick the original it copies. |

## Example: PDF invoices

The prompt above, from a live run on 2026-10-14 for Python 3.12 on a laptop,
closed source, kept maintained (abridged):

```
_Searched and checked live just now: 6 named, 0 not there and dropped._

## USE  ·  Read the tables
**Repo: jsvine/pdfplumber**
Python · license MIT · 10.8k stars · pushed 2 months ago · found: most starred in table-extraction, name or description has tables
Also: camelot-dev/camelot
The search also found, not picked:
- pymupdf/PyMuPDF (10.9k stars): found as most starred in table-extraction

## USE  ·  Read scanned invoices
**Repo: ocrmypdf/OCRmyPDF**
Python · license MPL-2.0 · 35.0k stars · pushed 3 days ago · found: readme text, name or description has ocr, most starred in ocr
Watch out: weak copyleft: changes to it must be shared under its license, but using it unchanged usually doesn't bind your code.
Also: PaddlePaddle/PaddleOCR

## USE  ·  Write the spreadsheet
**Repo: jmcnamara/XlsxWriter**
Python · license BSD-2-Clause · 4.0k stars · pushed 2 months ago · found: name or description has xlsx, most starred in xlsx
Also: pyexcel/pyexcel

## WRITE  ·  Run it from the command line
No repo: write this one.

## WRITE  ·  Tidy the invoice tables
No repo: write this one.
```

Three of the five parts already existed, all turned up by the search, and the
agent left out PyMuPDF because its AGPL would bind closed-source code. What's
left to write is the glue and the logic only these invoices have.

## Install

Needs Node 22.18 or later. **[USAGE.md](USAGE.md) has step-by-step setup
and links for 20+ agents**: Claude Code and Desktop, Codex, Copilot (CLI and
VS Code), Cursor, Windsurf, Devin, Cline, Gemini CLI, Goose, OpenCode, Zed,
Junie, Kiro, Amp, Warp, Continue, LM Studio, Hermes, Mistral Vibe and Open
WebUI. The quick routes:

**Claude Code, Codex, Copilot CLI**, as a plugin: the tools, plus a skill that
knows when to reach for them. One marketplace serves all three.

```sh
/plugin marketplace add bikemeardsley/git-for-me          # Claude Code
/plugin install git-for-me@git-for-me

codex plugin marketplace add bikemeardsley/git-for-me      # Codex
codex plugin add git-for-me@git-for-me

copilot plugin marketplace add bikemeardsley/git-for-me    # Copilot CLI
copilot plugin install git-for-me@git-for-me
```

**Any other MCP client**: a stdio server in the client's config. Most call the
key `mcpServers` ([USAGE.md](USAGE.md) has the exceptions).

```json
{ "mcpServers": { "git-for-me": { "command": "npx", "args": ["-y", "git-for-me"] } } }
```

**Gemini CLI**, as an extension: `gemini extensions install https://github.com/bikemeardsley/git-for-me`

**As an Agent Skill**, for agents that read `SKILL.md`:
`npx skills add bikemeardsley/git-for-me`.

**`GITHUB_TOKEN` (optional, and worth setting).** Without one, GitHub allows
10 searches a minute, which covers about two parts of a job; with one, 30. A
[fine-grained token](https://github.com/settings/personal-access-tokens/new)
with no permissions is enough. Pass it as `GITHUB_TOKEN`
([how, per agent](USAGE.md#before-you-start)); the Claude Code plugin asks for
it and keeps it in secure storage. It goes to GitHub alone: GitLab and
Codeberg need none. Without a token, a private GitHub repo looks missing,
because GitHub answers 404 for both.

## What leaves your machine

The search the agent writes for each part (a topic, a language, keywords, a
few words about the job) and the repos it picks, as GETs to `api.github.com`,
`gitlab.com/api` and `codeberg.org/api`, plus your token, to GitHub alone, if
you set one. The token never appears in a report. The need as you wrote it,
the method and the report stay between you and your agent.

Starting it with `npx` (as the MCP server, or the skill's shell fallback)
downloads the `git-for-me` package from the npm registry, `registry.npmjs.org`.
Nothing is sent there but the request for the package.

## Limits

- The search finds what the forges' own searches can: topics, names,
  descriptions, and on GitHub README text. A repo with none of those words can
  still be missed.
- "Rising" is GitHub's alone: the topic's most starred repos created in the
  last half year, since GitHub has no trending API, and GitLab and Codeberg
  can't filter by creation date.
- GitLab's keyword search runs in any language (filtered by one, it times out
  on common words), and its results show no language until a pick is checked.
- License flags read each forge's license detection, not the license text.
  Codeberg detects none, so a repo there is flagged to read its license file,
  or as unlicensed if it has none.
- Only GitHub, GitLab.com and Codeberg are searched. Self-hosted GitLab and
  Gitea servers aren't, and Bitbucket can't be: it has no public search.

## Security

Report a vulnerability privately through
[GitHub Security Advisories](https://github.com/bikemeardsley/git-for-me/security/advisories/new),
not a public issue. [SECURITY.md](SECURITY.md) lists what it touches: GETs to
the three forges, and nothing on your machine.

## Development

```sh
npm install          # also builds build/, which is what npx runs
node src/server.ts   # the server, straight from source
npm test             # offline: the forges are mocked, and the server is driven over stdio and HTTP
npm run check        # types
```

From a clone, add it to your agent with
`claude mcp add --scope user git-for-me -- node /path/to/git-for-me/src/server.ts`.
`npm install` builds JavaScript into `build/` because Node won't strip types
from a package inside `node_modules`, which is where `npx` puts it.

## License

MIT. Not affiliated with the Git project, GitHub, GitLab or Codeberg.