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, 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, invisible and mixed-script characters, vulnerable dependencies and dependency-confusion shapes, agent settings that turn approval off: each a plain rule with its evidence, the same on every run, fit for CI (--fail-on, SARIF). It fails closed: a gate whose scan did not finish exits 4 instead of passing, and --baseline gates only on what is new since an earlier run, so a secret committed years ago does not block every build. A value the repository itself declared allowed (a gitleaks or betterleaks allowlist, gitleaks:allow) is a note, not a critical, and --require-vuln-db makes a run without a vulnerability database fail rather than pass unchecked.
• A place to start looking. The watch list is Tornhill's hotspots, revisions × lines of code. It tells you where to read first, and --hook gives an agent the same ranking for the files it just edited. It is not a defect model: on repositories nobody tuned against, at the top it names about as many soon-to-be-fixed files as churn alone, and per line read it finds fewer (validation.md).
• Who and when. Ownership, knowledge islands, code age and the files that change together, read from the history itself. Advice names only people still committing; someone who left is marked (gone). A coding assistant credited in commit trailers is counted apart, as an area's agent-assisted share, never as an owner or an author. --path DIR narrows all of it to one package or plugin of a monorepo.

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 row and column
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.40.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 exits 2 over a threshold, 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): is the watch list right against churn alone, and does it run on awkward inputs and catch the gate's planted problems. The second graph is weaker evidence than the other two: every "actionable" label behind it is one agent's reading, the same agent that wrote the rules, and no outside labels exist. Read it as that agent's opinion, not as a measure of whether the findings are worth acting on.

What it costs (findings per repository, report length, run time, memory) and every release's numbers: 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), and the tool download you ask for with --install-tools or a yes to the missing-tools question. 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 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.