Comments
A deep-research agent with an enforced budget, verified quotes, and a privacy boundary for local data.
Ask a question. mole decomposes it, searches, reads sources, extracts claims, checks each claim against the text it came from, looks for contradictions between them, and writes an answer with citations. Every model call is reserved against a budget before it happens and settled after, so the ceiling you set is the ceiling
It runs as a single static binary on your machine, uses your own API keys, and speaks MCP so a coding agent can drive it — either by handing mole a question and collecting the answer, or, in toolkit mode, by doing the reasoning with its own model while mole supplies the parts that are not model calls.
Three things mole does that a chat interface with web search does not.
The budget is enforced, not estimated. Every call is reserved before it is made and settled after, against a ledger with non-negative constraints in the database schema itself. --usd 0.50 means the run stops at fifty cents. Measured overshoot across the test corpus is 0%.
Every claim carries a quote, checked against the source. A claim whose quote does not appear verbatim in the page it was mined from is discarded at extraction, before it can reach an answer. Claims that survive can be re-read against their source afterwards, and one that turns out not to be supported is marked as such in the report rather than quietly dropped.
Your local data stays local. Point mole at a CSV or a folder and it will analyse it without the contents leaving your machine: the model chooses a hypothesis template and column names, mole renders and runs the SQL, and only aggregates — counts, means, test results, buckets covering at least five records — are allowed back. mole crossings shows you exactly what left.
Script — Linux and macOS, amd64 and arm64:
Downloads the release archive for your platform, verifies its SHA-256 against the checksums published with the release, and installs mole and mole-mcp into ~/.local/bin (or /usr/local/bin if that is writable). It uses sudo only if the target directory needs it, and --dry-run shows what it would do. If piping a script into a shell makes you uneasy — reasonable — read it first, or use one of the paths below.
Homebrew — macOS and Linux:
Fully qualified, and it has to be: an unrelated mole (a macOS cleanup tool) is in homebrew/core, so brew install mole will always mean that one. Both install a binary called mole, so only one can be linked at a time.
Arch Linux — from the AUR:
Not mole: that name and mole-bin on the AUR belong to an SSH tunnelling tool that has held them since 2020. The package installs /usr/bin/mole and declares the conflict, so pacman will tell you rather than overwrite anything.
Debian and Ubuntu — .deb from the releases page:
An .rpm is published for the same platforms.
From source — needs Go 1.25+:
Or clone and make install, which stamps the version so mole version reports the tag rather than dev.
Every path installs the same thing: two static binaries with no runtime dependencies, built CGO_ENABLED=0. The database is SQLite, created on first use under your XDG data directory.
You need a search provider and a model provider. Keys live in ~/.config/mole/config.json, mode 0600 — never in environment variables that leak into process listings, and never in .mcp.json.
Any OpenAI-compatible endpoint works — DeepSeek, Ollama, llama.cpp, vLLM, a proxy:
A model served from localhost is priced at zero and still counted in tokens, so --tokens bounds a self-hosted run that costs no money at all.
Budget is required, and the two units are mutually exclusive. Only dollar mode can price a search call; only token mode can bound a model whose rates mole does not
Answers from the claims that session already collected. No new searching, no new spending beyond the one call to phrase the answer.
! marks the field that identifies a row. Rows are merged across sources by fuzzy key, so Aldi and Aldi UK become one row with two sources. CSV holds one value per cell and says so — it carries a source count and a contested column naming the fields the sources disagree about. JSON carries every disagreeing value with the sources behind each.
CSV, TSV, JSON and JSONL are supported; Parquet is not. The model never sees a row and never writes SQL — it picks a template and column names, and mole renders the statement.
Listens on a unix socket, mode 0600, in a private directory, and refuses connections from any other user. Point a client at the shim:
No credentials in that file — the shim forwards to the daemon, which holds them.
The arrangement above has mole own the model: it plans, mines and writes with your API key, and the coding agent driving it is pressing a button. Toolkit mode inverts that. The agent's model does the reasoning; mole contributes the deterministic half — which is the half worth having, and the half that does not care whose model is on the other side of it.
If you are inside Claude Code or Qwen Code on a subscription, your model tokens are already paid for. This is the mode for that.
Fourteen tools, each named mole., alongside the research.* tools — the flag adds a surface rather than replacing one:
Three actor types feed the same graph. web searches and reads pages. academic queries Crossref, OpenAlex, arXiv and PubMed, deduplicates by DOI and prefers open-access full text. local_compute runs deterministic SQL over data you registered and never lets a row reach the model.
Toolkit mode runs the same machinery with the arrows reversed: the agent decides what to search, what to read and which claims relate, and mole does the quote checking, the pair retrieval, the merging and the SQL rendering. Both modes share one copy of each — the same AcceptRow for dataset rows, the same aggregation gate, the same lexical retriever — so a toolkit graph and an autonomous one are built the same way.
mole grades its own runs. mole eval prints a scorecard, and any metric it cannot compute says so instead of quietly reading zero.
Bug reports and issues are welcome. Code contributions go through a CLA — see CONTRIBUTING.md, which explains what it is for and what it
Maintainers: the release runbook is RELEASING.md.
The one practice this project asks for that most do not: falsify your own fix. After a change, revert the mechanism and confirm the test fails. A test that passes with the fix removed proves nothing, and several of this project's own tests have been caught doing exactly that.