gitmole

A toolkit for digging into any cloned git repository: who works on it, where the risk is, how old the code is, whether the repo itself is healthy, and whether anything sensitive was ever committed.

Free. Any Stack. Local. Offline. Deterministic. Fast.

• Free. MIT licence, no paid tier, no account, no token. A local clone needs no credentials, and a public owner/repo is cloned with plain git. Your gh login is only used for private repositories and for owner/*, and only when you ask for them. The tools it runs are open source too.
• Any stack. It reads what every repository has: the git log, git blame and the files themselves.
• Local & Offline. Everything runs against a clone on your machine. Nothing is uploaded, nothing phones home; the vulnerability database is a copy you download once.
• Deterministic. No AI at runtime. Every finding is a plain rule over counts you can recompute by hand. The JSON export carries each finding's rule and the numbers it fired on. The same clone gives the same report every time.
• Fast. A 4,400-commit repository takes under thirty seconds.

Install

# macOS, or Linux with Homebrew: gitmole and the five tools it runs
brew tap antvinni/gitmole https://github.com/antvinni/gitmole
brew trust antvinni/gitmole
brew install gitmole

# anywhere else: scc, git-sizer, betterleaks, jscpd and osv-scanner on your PATH, then
pipx install gitmole

Linux package names, the release binaries, --plots and the pip caveats: docs/install.md.

Usage

gitmole .                              # the clone you are in
gitmole /path/to/clone                 # any local clone
gitmole owner/repo                     # clones into a temp dir first, with gh or plain git
gitmole 'owner/*'                      # every non-archived repo of a user or org, one summary table

gitmole . --markdown report.md         # the same report as a Markdown document
gitmole . --json report.json           # every table, the watch list and the findings
gitmole . --fail-on warning            # exit 3 if any finding is a warning or worse
gitmole . --risk main --risk-threshold 10  # exit 3 if the files changed since main hold over 10% of the risk
gitmole . --since 2y --full            # the current team, every row and column
gitmole --clean                        # list what gitmole left behind, delete on a yes

A CI job that runs gitmole . --fail-on critical --markdown - >> "$GITHUB_STEP_SUMMARY" blocks on secrets in source files and still posts the report. Every option: docs/cli.md.

What you get

The opening of the report for react, 21,703 commits since 2013, at a pinned commit:

╭─ react ──────────────────────────────────────────────────────────────────────────────────────────╮
│ 21703 commits  ·  2013-05-28 → 2026-09-16  ·  1843 identities  ·  branch main                    │
│ 681,078 lines in 4781 files  ·  JavaScript, TypeScript, Rust, CSS                                │
│ most commits on Wed at 15:00  ·  14% of commits are fixes  ·  1% of commits are reverts  ·  19%  │
│ of surviving code from 2026                                                                      │
│ 1 critical, 6 warnings, 9 notes                                                                  │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

◎ Watch list
  file                                              why                                             
  ──────────────────────────────────────────────────────────────────────────────────────────────────
  packages/react-server/src/ReactFlightServer.js    changed 319 times · fixed once in six months ·  
                                                    visitAsyncNodeImpl() complexity 46              
  packages/react-server/src/ReactFizzServer.js      changed 297 times · fixed twice in six months · 
                                                    retryNode() complexity 41                       
  packages/react-reconciler/src/ReactFiberWorkLoo   changed 312 times · fixed 4 times in six months 
  p.js                                              · flushSpawnedWork() complexity 48              
  packages/react-reconciler/src/ReactFiberCommitW   changed 284 times · fixed 28 times ·            
  ork.js                                            commitLayoutEffectOnFiber() complexity 72       
  packages/react-reconciler/src/ReactFiberBeginWo   changed 361 times · fixed once in six months ·  
  rk.js                                             beginWork() complexity 52                       
  ranked by revisions × lines of code alone; the reasons say what to look at there                  
  6 months ago this list would have named 11 of the 46 files fixed since (a random 15 of the 1802   
  files that had changed more than once would name 0.3; the 15 most changed would name 7)           

The watch list is the point: the five source files most likely to need a fix next, the reasons in words, and a backtest that says how the same list, drawn six months earlier, would have done against the fixes that followed. The list ranks by revisions × lines of code: measured at six cut-offs on three repositories (validation), that named more of the files fixed next than churn alone, size alone or a weighted product of fixes, complexity and ownership. Between the header and that list the full report puts its findings, 16 for react (1 critical, 6 warnings, 9 notes); below it, tables for people, the knowledge map, the timeline, change coupling, complex functions and repo health; --full adds the hotspots table behind the list, size, activity and code age. Every section is explained in docs/output.md.

Reports on repositories you know, each at a pinned commit with a fixed reference date, published as gitmole wrote them; the repo-health numbers come from git-sizer over the whole clone, so a fresh clone can differ there:

The tool set

One tool per question; together they cover what a single command can tell you about a clone.

Why these and not others: docs/tools.md.

Docs

• Install: macOS, Linux, pipx, the check, pinned releases.
• Command line: every option, portfolio mode, exports and CI gates, big repositories.
• The report and the output files: what each section and each file means.
• Example reports: curl, django and react at pinned commits, regenerated by bin/render-examples.
• Validation: the watch list against other ways of ranking the same files at six cut-offs on three repositories.
• Why these tools: the rationale, what was left out, licences.
• Development: setup, tests, releases, code layout.
• Contributing: bugs, ideas, pull requests, security reports.

Safety

• Everything is offline except the optional clone step, which uses your existing gh auth. None of the tools send data anywhere; osv-scanner runs against a local copy of its database that you download once, and gitmole never downloads it for you.
• Remote targets are cloned into a fresh temp directory that is removed when the run ends. Local clones are only read. The secrets scan reads every branch; everything else describes the branch that is checked out. gitmole --clean lists every directory gitmole created and deletes them after a y/N question.
• Secret values never reach the output directory. betterleaks reports to gitmole in memory, and gitmole stores a short keyed hash in place of the value, the matched text and the commit message. The key is random, made for that one report and never saved.

License

MIT. gitmole runs the tools it wraps as separate processes and bundles none of them; their licences are listed in docs/tools.md.