lajosdeme/mole: a Go deep-research agent with an enforced budget and a local-data boundary

The problem mole targets: research you can audit and afford

A chat interface with web search will answer a research question, but it will not tell you which sentence in which page supports each assertion, and it will not promise a spend ceiling. mole is built for the opposite trade: slower, more explicit, and bounded. The README frames it as a deep-research agent that decomposes a question, 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. The audience is engineers and analysts who need to hand a research result to someone else and defend it, or who are paying per token and want a number they can commit to before the run starts. Two design choices carry that promise. First, the budget is reserved before each model call and settled after, against a ledger with non-negative constraints in the database schema itself, so the ceiling is a property of the storage layer rather than a prompt instruction. Second, 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. That is a stricter filter than most research tools apply, and it is the reason the output looks thinner than a chat answer: anything the extractor could not tie back to source text is gone.

How the pipeline and the budget ledger actually work

The repository layout matches the README's description of the stages. The Go module depends on codeberg.org/readeck/go-readability/v2 for article extraction, github.com/anthropics/anthropic-sdk-go for the Anthropic path, github.com/modelcontextprotocol/go-sdk for the MCP server, and modernc.org/sqlite, a pure-Go SQLite driver, which is consistent with the CGO_ENABLED=0 static build the Makefile uses. The Makefile also names internal/budget as the package carrying the concurrency guarantees, and its race target exists specifically because those guarantees are only meaningfully tested under -race. That tells you where the interesting correctness work lives: concurrent reservations against a shared ledger, not the prose generation. Data flows in one direction. A question is decomposed, sources are fetched and reduced to readable text, claims are extracted with quotes, quotes are matched against the page text, surviving claims are compared for contradictions, and the answer is assembled with citations. The privacy path is a separate branch of the same machine. When you point mole at a CSV or folder, the model chooses a hypothesis template and column names, mole renders and runs the SQL itself, and only aggregates are allowed back: counts, means, test results, and buckets covering at least five records. The README says mole crossings shows you exactly what left. The five-record floor is the part worth pausing on. It is a real disclosure control, and it also means small tables cannot be analysed at the granularity you might want.

Installing mole and running a first bounded research query

The README offers five install paths and they all install the same two static binaries, mole and mole-mcp, built with CGO_ENABLED=0 and no runtime dependencies. The script path is the shortest on Linux and macOS.

curl -fsSL https://raw.githubusercontent.com/lajosdeme/mole/main/install.sh | sh

It downloads the release archive for your platform, verifies its SHA-256 against the checksums published with the release, and installs into ~/.local/bin, or /usr/local/bin if that is writable. The README notes that --dry-run shows what it would do. If you prefer a package manager, the Homebrew formula must be fully qualified, because an unrelated macOS cleanup tool named mole occupies the plain name in homebrew/core.

brew install lajosdeme/mole/mole

On Arch, the AUR package is mole-research-bin for prebuilt binaries or mole-research to build from source; the README is explicit that mole and mole-bin on the AUR belong to an SSH tunnelling tool. From source you need Go 1.25 or newer.

go install github.com/lajosdeme/mole/cmd/mole@latest
go install github.com/lajosdeme/mole/cmd/mole-mcp@latest

Configuration is a JSON file at ~/.config/mole/config.json with mode 0600, written through the CLI rather than by hand. The README gives the reason: keys should not sit in environment variables that leak into process listings, and never in .mcp.json. You need a search provider and a model provider.

mole config set search.provider tavily
mole config set search.tavily-key tvly-...
mole config set llm.provider anthropic
mole config set llm.api-key sk-...
mole config set llm.model claude-sonnet-5
mole config set llm.cheap-model claude-haiku-4-5
mole doctor

mole doctor verifies the settings above. Then a first run, with the budget flag that is required:

mole research "how much electricity does the bitcoin network use?" --usd 0.50

You should see the staged pipeline run and an answer with citations. The same command accepts --tokens 200000 instead of --usd, 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 know. Adding --json gives a machine-readable result.

Where mole is the wrong tool

The extraction filter is the first limitation, and it is deliberate. A claim whose quote is not verbatim in the source page is discarded, so paraphrased or synthesized findings never reach the answer. If your question needs interpretation across sources rather than quotable sentences, mole will return less than a chat model would. The second limitation is input format. CSV, TSV, JSON and JSONL are supported for local analysis; the README states plainly that Parquet is not. A data team whose exports are Parquet has to convert before mole can touch them. The third is the budget model itself. The budget flag is required, and dollar mode and token mode cannot be combined, so a run that needs both a priced search provider and a self-hosted model with unknown rates has no single flag that bounds everything. The README notes that 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. That is a workaround, not a unified budget. There is also a naming hazard on every install path: an unrelated mole exists in homebrew/core, an SSH tunnelling tool has held mole and mole-bin on the AUR since 2020, and both install a binary called mole, so only one can be linked at a time. Finally, the project is young. The only release is v0.1.0, published on 2026-08-13, and the last push to main was the same day. Nothing in the README documents rollback or migration between versions, so a session database written by one build has no stated upgrade path.

mole against a general web-search assistant

The obvious alternative is a general assistant with a browsing tool, and the difference is not quality, it is accounting. A browsing assistant gives you prose and a list of links; you cannot see which sentence supports which claim, and the cost is whatever the conversation consumed. mole's answer carries citations that were checked against the page text at extraction time, and the run stops at the ceiling you named, with the README claiming 0% measured overshoot across its test corpus. The reverse trade is flexibility. A browsing assistant will happily reason across sources, combine numbers, and answer a question whose evidence is spread thinly; mole discards any claim it cannot quote verbatim, which makes it conservative by construction. A second alternative for the local-data case is running an analysis model directly against your files. That is simpler, but the model sees the rows. mole's arrangement is that the model chooses a hypothesis template and column names, mole renders and runs the SQL, and only aggregates come back. If your question can be answered from a small table with fewer than five records per bucket, that floor will block the analysis entirely, and a direct approach is the only one that works.

Maintenance, upgrade cost and the Apache-2.0 terms

The last push to main was on 2026-08-13, and the sole release, v0.1.0, was published the same day. That is recent, but it is one release, and the README does not describe a deprecation policy or a migration path for the SQLite database that is created on first use under your XDG data directory. Upgrading is therefore a matter of installing the new binary and hoping the schema is compatible; there is no documented rollback. The Makefile shows the release discipline: goreleaser drives packaging, make release-check dry-runs the whole pipeline into dist/ without publishing, and make install stamps the version so mole version reports the tag rather than dev. If you build from source without that stamp, you get dev, which makes bug reports less useful. The licence is Apache-2.0, and the repository carries a NOTICE file and a CLA.md, which is the standard arrangement for a project that wants contributions under a contributor licence agreement. Apache-2.0 includes an explicit patent grant and requires that you preserve notices; if you redistribute mole inside a product, read the NOTICE file rather than assuming the licence text is the whole story. None of this is legal advice, and the licence file in the repository is the authoritative text.

Editorial conclusion

Adopt mole if you need research output whose every claim carries a quote checked against the page it came from, and you want the spend ceiling enforced by the schema rather than estimated by the prompt. It is the wrong tool if you need Parquet inputs, if you cannot supply both a search key and a model key, or if you expect it to run unattended with no budget flag, since the budget is required and dollar and token modes are mutually exclusive. Before trusting it, run mole doctor to confirm the config, then do one small research run and read mole crossings to see exactly what left the machine. The last push to main was on 2026-08-13, and the only published release is v0.1.0 from the same day, so treat the surface as young.

Frequently asked questions

Official sources

1. Issues
2. lajosdeme/mole on GitHub
3. License: Apache-2.0
4. README
5. Releases