Mole enforces a hard spending budget on AI research runs
A developer using the handle lajosdeme posted Mole on Show HN: a terminal based "deep research agent." Given a question, it decomposes the question into sub-questions, searches, reads sources, extracts claims, checks each claim against the text it came from, looks for contradictions between claims, and writes an answer with citations. It runs as a single static binary using the user's own API keys, and it also speaks MCP, so a coding agent can either hand Mole a question and collect the answer, or drive Mole's deterministic parts itself.
The project's own framing is that a chat interface with web search does not do three things Mole does. First, the spending budget is enforced rather than estimated: every model call is reserved against a ledger before it happens and settled after, with non-negative constraints built into the database schema itself, so a flag like --usd 0.50 caps a run at fifty cents. The project states measured overshoot across its own test corpus is 0 percent, though the text gives no sample size or description of what that corpus contains. A token budget (--tokens) is also available and is mutually exclusive with the dollar budget; only dollar mode can price a search call, and only token mode can bound a model whose rates Mole does not know, which covers self-hosted models that cost nothing but still consume tokens.
Second, every claim must carry a quote that appears verbatim in the page it was mined from; a claim whose quote cannot be matched is discarded at extraction, before it can reach an answer. A sample of claims that survive extraction can be re-checked against their sources afterward by a separate verifier stage, and one that turns out not to be supported is marked as such in the final report rather than quietly dropped.
Third, Mole can point at a local CSV file or folder and analyze it without the row level contents leaving the machine. The model is only allowed to choose a hypothesis template and column names; Mole itself renders and runs the SQL, and only aggregates, such as counts, means, test results and buckets covering at least five records, are permitted back to the model. A command called "mole crossings" shows exactly what data left the machine during a session.
Installation ships as two static Go binaries with no runtime dependencies, via a shell script that verifies a SHA-256 checksum, via Homebrew, via a .deb or .rpm package, via the AUR, or by building from source with Go 1.25 or later. The naming needed care: an unrelated macOS cleanup tool already occupies the plain "mole" name in Homebrew's core repository, so the formula is published as the fully qualified lajosdeme/mole/mole, and only one binary named "mole" can be linked at a time either way. On the AUR, the names "mole" and "mole-bin" have belonged since 2020 to an unrelated SSH tunnelling tool, so Mole's packages are published as mole-research and mole-research-bin instead; the package still installs a binary at /usr/bin/mole and declares the conflict, so pacman will warn rather than silently overwrite the other tool.
Beyond acting as a standalone agent, Mole runs as an MCP server. In its default mode, Mole owns the model and plans, searches and writes using the user's own API key. A "toolkit mode" inverts that: the calling coding agent's own model does the reasoning, and Mole exposes fourteen tools, each named mole.
The project includes a self-evaluation command, mole eval, that prints a scorecard for a session and reports when a metric cannot be computed rather than defaulting to zero. Its stated testing practice is to "falsify your own fix": after making a change, revert the underlying mechanism and confirm the associated test then fails, on the grounds that a test which still passes with the fix removed has proven nothing. For local data connections, CSV, TSV, JSON and JSONL are supported; Parquet is not.
The text does not name the company or affiliation, if any, behind the project, gives no release date or version number, states no license name (a CLA is mentioned, but only as a requirement for code contributions), gives no pricing for the third-party search and model providers it depends on, and offers no comparison numbers against any other research-agent or chat-with-search tool.
Key facts
- Spending is enforced through a reserve-then-settle ledger with non-negative constraints in the database schema; the project reports 0 percent measured overshoot across its own test corpus, and an example flag, --usd 0.50, stops a run at fifty cents.
- A claim is discarded at extraction unless its supporting quote appears verbatim in the source page it was mined from; a sample of claims that survive can be re-checked afterward, and any that turn out unsupported are flagged in the report rather than silently removed.
- Local CSV or folder data is analyzed without raw rows leaving the machine: the model only picks a hypothesis template and column names, Mole renders and runs the SQL, and only aggregates covering at least five records return, with a "mole crossings" command showing exactly what left.
- Installing it requires dodging two unrelated tools already named "mole": a macOS cleanup utility that holds the name in Homebrew's core repository, and an SSH tunnelling tool that has held the AUR names "mole" and "mole-bin" since 2020.
- As an MCP server, Mole can either drive its own model with the user's API keys, or run in "toolkit mode" with fourteen mole.
tools that let a coding agent's own model, such as inside Claude Code or Qwen Code, do the reasoning while Mole handles quote checking, source retrieval and SQL.
Why it matters
Two failure modes plague chat tools that bolt on web search: spending that is only estimated after the fact, and citations that look real but were never checked against their source. Mole's pitch is that both are structural rather than aspirational. The budget is enforced in the database layer itself, with calls reserved before they happen and settled after, so a run cannot silently blow past a cap. Citations work the same way in reverse: a claim only survives if its quote can be matched verbatim in the page it came from, and a sample of claims that pass can be checked again afterward rather than trusted once. Whether that discipline holds up outside the project's own test corpus is unverified, but the design choice, reserve-and-settle plus verify-and-reverify, is more concrete than most research-agent marketing.
Who it affects
Anyone running command-line AI tooling on Linux or macOS who wants a research agent that will not overspend and that shows its work. It particularly targets two groups: developers already using an MCP-capable coding agent, such as Claude Code or Qwen Code on a paid subscription, who can run Mole in toolkit mode so their already-paid-for model does the reasoning; and anyone who wants to point an agent at local CSV data, such as spreadsheets of sales or survey results, without sending the underlying rows to a model provider.
How to use it
Mole installs as two static binaries with no runtime dependencies, via an install script that checks a SHA-256 sum, via a fully qualified Homebrew formula (lajosdeme/mole/mole, since the plain name belongs to a different tool), via AUR packages named mole-research or mole-research-bin, via a .deb or .rpm, or by building from source with Go 1.25 or later. After installing, a user configures a search provider (Tavily or Brave) and a model provider (Anthropic, or any OpenAI-compatible endpoint, including DeepSeek, Ollama or a local server) in a config file, then runs commands such as "mole research "
How solid is it
The only evidence in the text is the project's own description and a Show HN post that had drawn 67 points and 10 comments about 13 hours after posting, which measures interest, not correctness. The claimed 0 percent budget overshoot and the claim-verification behavior are both self-reported, with no sample size, time period or corpus description given, and no outside benchmark or comparison to another research agent is offered. The project does include its own scoring tool, mole eval, and states a specific testing discipline, reverting a fix to confirm its test then fails, which is a meaningful rigor signal but still an internal one; none of it has been checked by anyone outside the project as far as the source shows.
Risks and caveats
The text does not name an author, company or affiliation behind the project, gives no version number or release date, and states no license name for the software itself, only that code contributions go through a CLA. No pricing is given for the third-party search and model providers Mole depends on, so total cost depends on services the source does not describe. Parquet files are not supported as a local data connection, only CSV, TSV, JSON and JSONL. The overlapping names with two unrelated existing tools, a macOS cleanup utility on Homebrew and an SSH tunnelling tool on the AUR, create real room for installing or reading about the wrong "mole" by mistake.
“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.”
— Mole's project documentation