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. An owner/repo is cloned with gh when it is there, so a private repository uses your login, and with plain git when it is not, since a public repository needs no token; owner/* lists repositories through gh. 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. Once, on a run with a terminal, gitmole asks five yes/no questions about its own findings and writes your answers to a file it tells you how to send — it still uploads nothing, and GITMOLE_NO_FEEDBACK=1 turns the question off for good.
• 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, the numbers it fired on and, where a rule rests on a paper, the citation. The same commit gives the same bytes: gitmole's own CI runs it twice on every commit, compares the exports and attests the report. One gitmole version is one toolchain, since the three tools are pinned and installed with it, and every report records the versions it ran.
• Fast. A default run over a large repository takes a minute or two (the example reports below give their times). The expensive passes have budgets: code age is skipped when its blame pass is projected past a minute (projected from the history it walks, so the same commit decides the same way on any machine), and the report says so and how to force it (--deep).

What it is for

Trusting and triaging a repository you did not write, or one you are about to change.

• A gate you can check. Secrets in history, vulnerable dependencies, invisible and mixed-script characters, unsafe workflows and agent settings: each a plain rule with its evidence, the same on every run. --fail-on and SARIF fit it into CI, a scan that did not finish exits 4 instead of passing, and --baseline gates only on what is new.
• A place to start looking. The watch list ranks files by changes × lines of code (Tornhill's hotspots) and names what to read first in each; --hook gives a coding agent the same ranking for the files it just edited. It is not a defect model: validation.md says what it finds and what it does not.
• Who and when. Ownership, knowledge islands, code age and the files that change together, read from the history itself. People who left are marked gone, coding assistants are counted apart from authors, and --path DIR narrows all of it to one part of a monorepo.

What each rule counts, and what it leaves out, is in output.md.

Install

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

# anywhere else: gitmole from PyPI, then the same three pinned tools into gitmole's own directory
pipx install gitmole
gitmole --install-tools

# either way: every tool gitmole runs, the version found against the one pinned
gitmole --doctor

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 . --sarif gitmole.sarif        # the findings for GitHub code scanning or GitLab
gitmole . --sbom sbom.cdx.json         # a CycloneDX SBOM of every package the lock files pin
gitmole . --compare last.json          # what changed since an earlier --json export
gitmole . --fail-on critical --baseline last.json  # gate only on what is new since last.json
gitmole . --path backend/plugins/github  # one directory: its history, owners and watch list
gitmole analysis-repo --no-run --hook  # an agent's edit hook, over the output of one earlier `gitmole . --out analysis-repo`
gitmole . --since 2y --full            # the current team, every section and every finding
gitmole analysis-repo --no-run --section people --csv  # every row of one table of an earlier run, as CSV
gitmole --clean                        # list what gitmole left behind, delete on a yes
gitmole --doctor                       # every tool gitmole runs, the version found against the one pinned
gitmole --install-tools                # the three pinned tools, downloaded into gitmole's own directory

A CI job that runs gitmole . --fail-on critical --markdown - >> "$GITHUB_STEP_SUMMARY" blocks on secrets in source files and still posts the report; in GitHub Actions, uses: antvinni/gitmole@v0.45.0 does that with the pinned tools installed and cached (GitHub Actions), and a Dockerfile runs it anywhere else. The same scoring wires into Claude Code, Cursor, Gemini CLI and pre-commit as a hook that tells the agent what history says about the files it edited, without blocking it, after one gitmole . --out analysis-repo for it to score against (Agent hooks). Every option: docs/cli.md. What each part of the report means and what to do first: Reading your first report.

What you get

Reports on repositories you know, each at a pinned commit, published as gitmole wrote them:

Run times are one gitmole CLONE with every default step, on a MacBook Pro (M4, 16 GB).

Evolution

Every release that changes what gitmole finds or ranks is run from its own source over the same pinned repositories and judged by the same yardsticks (measurement.md).

The ranking has held since 0.8.0. On the four repositories every release is drawn over, headroom rose from 0.73 to 0.92 at 0.8.0 and has been 0.93 since 0.11.0. The lower figures in the history's table (0.62 at 0.28.0, 0.65 at 0.37.0, 0.60 at 0.38.0) are changes to the yardstick, not to the ranking: repositories joined the set at 0.28.0 and 0.38.0, and 0.37.0 rebuilt the set and took its cut-offs from first-parent commits. Recent releases cut cost rather than raising effectiveness: from 0.38.0 to 0.42.0, on the same development set, the median findings per repository fell from 19.5 to 10, the report from 216 to 198 lines, and 0.40.0 to 0.42.0 answered findings that reviewers had checked and found false.

Every run completes, and the gate catches 3 of 3, since 0.28.0.

Every release's numbers, including what it costs in report length, run time and memory: measurement-history.md.

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

Using gitmole:

• Install: macOS, Linux, pipx, the check, pinned releases.
• Command line: every option, portfolio mode, exports and CI gates, big repositories.
• Reading your first report: one screen, each section in plain words, and what to do first.
• 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.
• Why these tools: the rationale, what was left out, licences.
• References: the research and tools gitmole's rules are built on.
• Validation: the watch list against other ways of ranking the same files at six cut-offs on the development set and the thirteen held-out repositories.

Working on gitmole:

• Measurement and its history: how a release is judged better, and every measured release.
• Development: setup, tests, releases, code layout.
• Pipeline: how a change earns its place, and which decisions an agent does not make.
• Contributing: bugs, ideas, pull requests, security reports.
• AGENTS.md: the rules a coding agent working on gitmole follows, unattended or not.

Safety

• Everything is offline except the optional clone step (gh with your existing login, else plain git), the tool download you ask for with --install-tools or a yes to the missing-tools question, and the vulnerability database you ask for with --fetch-vuln-db. None of the tools send data anywhere; osv-scanner runs against that local copy of its database, and gitmole never refreshes it on its own, so the same commit gives the same report until you fetch again.
• 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 the whole history of the checked-out commit and the objects no branch reaches; everything else describes the branch that is checked out. gitmole --clean lists every directory gitmole created and deletes them after a y/N question, except the tools --install-tools placed for the version you run, which are in use.
• 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.