digs up forgotten work. ships it.

gitgoblin digs through public repositories for work that actually matters, backs every find with evidence, and crafts one small pull request a maintainer would be glad to merge. Nothing is published until you say so.

Star on GitHubSee how it works

Early development: discovery and analysis work from a clone, contributing is experimental, nothing on npm yet. MIT licensed.What works today

example engine run, scripted; the engine is experimental
  1. $gitgoblin-engine run --report analysis.json --opportunity acme/kelp#58
  2. intakeopportunity from intel: deprecation, small, score 0.81. “kelp/cache.py calls datetime.utcnow(), deprecated since Python 3.12; every call logs a warning.”
  3. workspacecloned acme/kelp at 9c1e4b2, new branch goblin/utcnow-deprecation.
  4. baselineran the project's own checks before touching anything: pytest 112 passed, ruff ok, mypy ok.
  5. orientread kelp/cache.py:41, tests/test_cache.py and CONTRIBUTING.md. reproduced the DeprecationWarning on Python 3.12. feasible.
  6. plan1 file plus 1 test, 3 steps. out of scope: other utcnow calls under scripts/. risk: timezone-aware values change comparisons; the test covers it.
  7. implementdatetime.utcnow() replaced with datetime.now(timezone.utc) in cache.py; regression test added.
  8. verifypytest 113 passed (baseline 112), ruff ok, mypy ok. no regressions.
  9. reviewfresh reviewer, never saw the implementer's transcript: approve. 1 nit on the commit subject, fixed.
  10. preparecommit “fix: use timezone-aware now() in cache”, pr.md and report.md written to .gitgoblin/runs/01JB3G6K/.
  11. awaiting approvalnothing has been pushed. a person decides what happens next.

A scripted run, not a recording: the scenario is invented, the phases and the approval gate are how the engine works.

How it works

Four stages that hand each other plain data. A person approves anything that gets published.

  1. Discover. Projects worth your time

    Tell it what you want: to contribute, learn, adopt, revive or explore. It ranks public repositories against that goal and shows the reasons behind every rank, so the quiet library your app depends on can beat the crowded project everyone else already found. This part works today.

  2. Understand. Read the repo like a careful new maintainer

    A profile of what the project is, how it is built and tested, how it treats outside contributors and which conventions it follows. Missing data stays unknown; nothing is punished for it. This works today too, with scores still being calibrated.

  3. Find the work. Loot, with receipts

    Concrete opportunities: issues nobody is working on, CI about to break, docs that contradict the code, dead links, tests missing where the code changes most. Each one points at something you can check and scores on named factors with reasons.

  4. Contribute. One good pull request

    For one opportunity, the engine investigates, plans, implements, runs the project's own checks against a baseline, gets an independent review and prepares the commit and the PR description. You read it and decide whether to publish.

The engine's full pipeline, retry rules and security boundaries are in How it worksand in the engine design.

What the goblin digs up

Twelve kinds of opportunity, straight from the contract in packages/intel/src/contracts.ts. Every one must carry at least one piece of evidence a person can check.

Things people asked for

issue
An open issue worth fixing.
feature_request
A maintainer-endorsed feature request with no implementation underway.
stale_pr
An abandoned pull request with maintainer interest, worth reviving.
triage
An unanswered issue that needs reproduction or an answer.

Things quietly rotting

ci_rot
CI that will break or has broken: deprecated actions, retired runners, unsafe triggers.
deprecation
Use of deprecated or removed APIs and libraries.
dependency
Vulnerable or deprecated dependencies.
docs_drift
Documentation that contradicts the code.
broken_link
Dead links or references in documentation.

Things nobody got to

test_gap
Frequently changed code with no tests, or tests that are skipped.
tech_debt
Self-admitted technical debt with enough context to act on.
hygiene
Missing project scaffolding that the repository's nature warrants.

Receipts included

An opportunity is not "this could be better". It is a claim with evidence, a score that decomposes into named factors with reasons, an estimate of effort, the files to read first, the steps to take, how to behave in that project, and the ways it might be wasted work.

The card shows the shape of one. The project and the numbers are made up.

deprecationsmall effortpython

kelp/cache.py calls datetime.utcnow(), deprecated since Python 3.12

Every call logs a DeprecationWarning; when the method is removed the cache stops working. One call site, already covered by tests.

Evidence
  • kelp/cache.py:41 return datetime.utcnow()
  • workflow run 4182 DeprecationWarning: datetime.utcnow() is deprecated
Score 0.81
value
0.60Warning noise now, breakage when the call is removed.
feasibility
0.95One call site, tests already cover the module.
welcomeness
0.85CONTRIBUTING invites small fixes; median PR response 20 hours.
confidence
0.90Reproduced the warning on Python 3.12.
novelty
0.80No open PR or issue mentions utcnow.
Etiquette
  • Small fixes need no issue first, per CONTRIBUTING.md.
  • Fill in the pull request template.
Risks
  • A maintainer may prefer one sweep of every utcnow call instead.

What the goblin never does

Maintainers did not ask for this, so gitgoblin holds itself to rules that live in code.

  • A person approves every external action. Nothing is pushed, opened or commented without someone reading it and saying yes, from their own account.
  • The project's rules win. Contributing guides, templates, issue-first policies, CLA and DCO requirements and "we don't want this kind of change" are read and followed. Projects that do not take outside contributions are left alone.
  • One good contribution beats ten mediocre ones. Small, tested, evidence-backed changes. No sweeps, no spam, and nobody's claimed issue is taken.

The full policy, including how a maintainer opts a project out, is in docs/etiquette.md.

Inside a run, the agent cannot

  • push, or change a remote
  • call gh, or reach the network at all
  • install packages, or publish anything
  • use sudo, containers or system tools
  • write outside its workspace, or into .git
  • touch protected paths: CI workflows, release config, secrets

The sandbox is the hard boundary; tool allowlists and hooks are belts on top. The agent never sees your GitHub token. Publishing uses your own login from the engine process, after you approve.

Try it today

You need Node.js 24 or newer and git. There is no published package yet, so run it from a clone.

git clone https://github.com/anandkaranubc/gitgoblin.git
cd gitgoblin
npm install
npx gitgoblin discover contribute --language typescript

That ranks ten repositories for contributing, with the reasons behind each rank. Here are the first three from a run on 2026-10-22; yours will differ, because the ranking follows what changed on GitHub.

npx gitgoblin discover contribute --language typescript --limit 3
 1. Bitterbot-AI/bitterbot-desktop  ★ 2.5k · TypeScript · MIT  score 0.91
    Bitterbot - a mesh of agents that turns shared experience into collective capability.
    https://github.com/Bitterbot-AI/bitterbot-desktop
    + CONTRIBUTING guide, code of conduct
    + last change today, 68 pull requests in the past year
    + pull requests in ~2 days

 2. ccch1mneyyy/dsh-TUI  ★ 5.3k · TypeScript · MIT  score 0.90
    DSH's officially top-recommended TUI plugin — high performance, low overhead, cute pixel whale, smo…
    https://github.com/ccch1mneyyy/dsh-TUI
    + CONTRIBUTING guide, code of conduct
    + last change today, 555 pull requests in the past year
    + issues close in ~4 days, pull requests in ~21 hours

 3. mvschwarz/openrig  ★ 8.1k · TypeScript · Apache-2.0  score 0.90
    Build your own network of agents from Claude Code, Codex and Pi: persistent teams with roles, share…
    https://github.com/mvschwarz/openrig
    + CONTRIBUTING guide, code of conduct
    + last change today, 282 pull requests in the past year
    + README, description, homepage, changelog

It works without any configuration; a GitHub token unlocks more data and a higher rate limit. The getting started tutorial walks through the five goals, the filters, the explain command and the token.

Help build it

Bug reports, confusing-documentation reports and pull requests are welcome. Start with the contributing guide, pick an issue, and say hello in it before you start. AI-assisted contributions are welcome too, with you accountable for them.

Everyone taking part agrees to the code of conduct.

Questions people ask

Is this a bot that opens pull requests?

No. gitgoblin prepares work; a person reads it, approves it and publishes it from their own account. It never opens pull requests, pushes commits or posts comments on its own, and that rule is enforced in code, not in a prompt.

Does it work yet?

Discovery and repository analysis do, from a clone: gitgoblin discover ranks public repositories for a goal with the reasons behind each ranking, explain shows why one ranked where it did, and analyze profiles one repository and lists its evidence-backed opportunities, with scores still being calibrated. Preparing a contribution with the engine runs end to end on a test repository and is experimental. Nothing is on npm yet, and no single command runs from discovery to pull request. The README keeps the table of what works.

Which model does it use, and what does it see?

The engine drives its agent sessions through the Claude Agent SDK, inside a sandbox with a per-phase tool allowlist, so the target repository's code and issue text go to the model provider during a run. Discovery and analysis read public data from GitHub and the ecosyste.ms APIs and need no model at all. Publishing is the only step that writes to the outside world, and it waits for you.

I maintain a project. Can I keep it away?

Yes. Fill in the maintainer form in the gitgoblin repository and the project goes on the excluded list, which gitgoblin users must respect and its tools are expected to enforce. No reason needed. Archived projects and projects that say they do not take outside contributions are skipped anyway.

Can I point it at my own repository?

By design, yes: a repository reference can name a local checkout instead of something to clone, so you can analyze and contribute to your own code with the same pipeline. Like the rest, this is in progress.

Why a goblin?

Goblins hoard, scavenge and tinker in corners nobody visits. gitgoblin does the same in repositories: it finds the neglected and the half-finished and turns it into something worth having. It is small, a little mischievous, and it stops when told.