git-for-me

<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 re