Mole deep-research agent – budget‑enforced, quote‑verified terminal tool

Mole delivers budget‑enforced, quote‑verified research directly from the terminal

Mole decomposes a natural‑language question, searches the web, extracts claims, checks each claim against its source, and synthesises a citation‑rich answer—all while guaranteeing that the total cost never exceeds a user‑specified budget.

Enforced budget eliminates surprise spend

Every model call is reserved before it is made and settled after, against a ledger with non‑negative constraints.

Use --usd 0.50 to stop the run after fifty cents of combined search‑API and LLM usage.
Use --tokens 200000 for a token‑only ceiling when the model’s pricing is unknown.
The project reports 0 % overshoot across its test corpus, meaning no run has ever exceeded the ceiling.

"Never spend more than you budgeted" – a user asked on HN how LLM overruns are prevented. Mole’s reservation system guarantees that the sum of search and LLM costs never exceeds the configured limit; token limits and pricing tables are applied before each call, and caching does not affect the reservation logic.

Verbatim‑quote verification guarantees claim integrity

Every claim must contain a verbatim quote that appears in the source page; otherwise the claim is discarded.

Claims that survive are stored with their source URL and exact quote.
During a post‑run verification pass, claims are re‑read against their sources; any mismatch is flagged rather than silently omitted.
Reported metrics show 100 % claim integrity and 100 % citation accuracy.

Local‑data privacy boundary

Mole can ingest CSV, TSV, JSON, JSONL, or Parquet‑like files (Parquet not yet supported) without sending any row data to the LLM.

The model only receives hypothesis templates and column names; it renders deterministic SQL and returns aggregated results (counts, means, statistical tests, buckets of ≥ 5 records).
The mole crossings command lists exactly what information left the machine.

Installation – single static binary, multiple package managers

Method	Platforms	Notes
Script (curl)	Linux/macOS, amd64 & arm64	Verifies SHA‑256, installs to `~/.local/bin` or `/usr/local/bin`
Homebrew	macOS & Linux	`brew install lajosdeme/mole/mole` (conflicts with unrelated `mole` tool)
AUR	Arch Linux	`yay -S mole-research-bin` (pre‑built) or `yay -S mole-research` (build from source)
.deb/.rpm	Debian/Ubuntu	Download from the releases page
`go install`	Any OS with Go 1.25+	`go install github.com/lajosdeme/mole/cmd/mole@latest`

All distributions produce two static binaries (mole and mole-mcp) with no runtime dependencies; the SQLite ledger is created on first use under the XDG data directory.

Configuration – API keys live securely on disk

mole config set search.provider tavily          # or brave
mole config set search.tavily-key <key>

mole config set llm.provider anthropic          # or openai-compatible
mole config set llm.api-key <key>
mole config set llm.model claude-sonnet-5
mole config set llm.cheap-model claude-haiku-4-5

mole doctor   # validates configuration

Keys are stored in ~/.config/mole/config.json with mode 0600, never in environment variables. Any OpenAI‑compatible endpoint (DeepSeek, Ollama, vLLM, etc.) works, and a locally hosted model can be used at zero monetary cost while still counting tokens for budget enforcement.

Core usage patterns

1. Autonomous deep research

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

The tool plans, searches, extracts, verifies, and answers in one run.
Options: --max-sources, --max-depth, --json for machine‑readable output.

2. Follow‑up queries without extra spend

mole ask <session-id> "what did the Cambridge estimate say?"

Reuses previously collected claims; only a single LLM call is needed to phrase the answer.

3. Structured dataset extraction

mole research "largest UK supermarket chains and their revenue" \
  --mode dataset \
  --schema 'company:text!,revenue:number=annual revenue in GBP,employees:number' \
  --usd 0.50

mole dataset <session-id> --format csv > chains.csv

Rows are merged across sources; the CSV includes a contested column for fields with differing values.

4. Private analysis of local files

mole connect add sales ./exports/sales.csv
mole research "how does spend differ between regions?" --actors local_compute --usd 0.30
mole crossings <session-id>

The LLM never sees raw rows; only aggregated statistics are returned.

MCP server mode – programmatic access for coding agents

mole serve   # listens on a private Unix socket

Clients configure their mcpServers to point to mole-mcp. No credentials are stored in the client config; the daemon holds them securely.

Toolkit mode – let the surrounding agent own the model

mole serve --toolkit

The external coding agent performs reasoning with its own model; Mole supplies deterministic operations (search, quote verification, SQL rendering). This is ideal when using Claude Code, Qwen Code, or any subscription where model tokens are already paid for.

Transparency – honest metrics from real runs

Metric	Value
Budget overshoot	0 %
Claim integrity	100 %
Citation accuracy	100 %
Grounding rate (claims re‑read)	80 %
Contradiction precision	70 % (with confirm pass)
Merge precision / recall	1.000 / 1.000

These numbers are generated by mole eval <session-id>; any metric that cannot be computed is reported as unavailable rather than silently defaulting to zero.

Community feedback from Hacker News

Conflict of interest note – a commenter linked to a different project named “Mole” (tw93/Mole) and warned about potential naming confusion.
Budget handling question – a user asked how unexpected LLM token usage is kept within the budget; the answer is that Mole reserves cost before each call and caps total spend, with token limits providing an additional safety net.
Feature‑to‑code ratio – one comment called the codebase “a LOT of code for a pretty basic feature,” reflecting a perception that the implementation is heavyweight relative to its core functionality.
Humor about honesty – a light‑hearted comment praised the “honest numbers” section, underscoring the project's transparency.
Clarifications – users asked what “deep research” means compared to ordinary web search; Mole’s pipeline (planning, claim extraction, verification, contradiction detection) distinguishes it from simple retrieval.

Contributing and quality standards

Pull requests require a Contributor License Agreement.
The project enforces falsify‑your‑own‑fix: after a change, revert the mechanism and confirm the test fails.
Code must pass gofmt -l ., go build ./..., and go test ./... with no skips.

License

Mole is released under the Apache‑2.0 license.