Mole Puts a Budget on Terminal Research

mole is lajosdeme’s open-source deep-research agent for the terminal, written mainly in Go and licensed under Apache-2.0. It deals with a very real annoyance: research agents can spend too much, blur their sources, and send local context places you did not mean to send it. The useful idea is simple: make research runs behave more like reviewable jobs, with a cost ceiling, quote-backed claims, and a local-data boundary.

mole is a terminal research agent that decomposes a question, searches, reads sources, extracts claims, checks those claims against source text, looks for contradictions, and writes a cited answer. As of August 2026, the repository had 95 GitHub stars and was last pushed on 2026-08-13.

Follow the run like a ledger, not a chat

The headline feature is not “agent does research.” Plenty of tools do that now.

The interesting bit is that mole reserves each model call against a budget before the call happens, then settles it after the call completes. The project describes this as a database-backed ledger with non-negative constraints, so a run with --usd 0.50 is meant to stop at fifty cents, not “around fifty cents if the estimate was good.”

That is why developers on Hacker News cared. A research agent that quietly turns a small question into a long, expensive chain is hard to trust inside a coding workflow. It also makes review awkward, because nobody wants to approve an open-ended agent run just to answer “which migration introduced this behavior?”

The trap is treating a budget flag as magic. The hard question raised in the discussion was fair: model cost depends on tokens, max output, pricing tables, provider behavior, and caching. mole’s claim is stronger than a UI estimate, but you should still inspect how the tool maps providers, token limits, and cached calls before relying on it for expensive work.

Treat quotes as the output, not decoration

mole’s second useful move is that every claim must carry a quote, and the quote is checked against the source it came from. That matters because research agents often sound cleanest exactly when they have lost the plot.

A good terminal answer for a developer is not just “Redis streams are used by the worker.” It is “the worker consumes Redis streams,” plus the quoted line, the source path or URL, and enough surrounding context for a human to verify it without replaying the whole agent run.

That fits nicely with Cursor, Anysphere’s AI code editor, where you might ask the agent to investigate a flaky test, then review the final answer in the editor before touching code. For more on the broader guardrail pattern, see the related training topic on AI coding governance.

The trap is letting citations become theater. A citation is only useful if it points to the exact evidence for the claim. If the quoted text merely sits near the claim, or if the agent cites a page it did not actually use, you are back to trusting tone.

Keep local data behind a real boundary

The privacy pitch is also practical. mole runs as a single static binary on your machine, uses your own API keys, and is designed with a boundary for local data.

That is especially relevant for agentic coding work because the most useful questions often involve private context: incident notes, local CSV exports, logs, customer repro steps, or architecture docs. Those are exactly the inputs you do not want casually pasted into a hosted chat box.

The trap is assuming “terminal” always means “private.” A terminal tool can still call remote models, remote search APIs, or external MCP servers. Treat mole’s local-data promise as a boundary to verify in the mode you choose, not as a blanket privacy spell.

A small pattern helps: put private files in a named directory, ask the agent to summarize only derived facts, and keep the raw file out of any prompt that leaves your machine. This is the same instinct behind tools like Read it easy Is a Read-Only Code Editor: separate reading from changing, and make the boundary visible.

Use MCP as a narrow handoff, not a blank check

mole speaks the Model Context Protocol, so a coding agent can drive it. In normal mode, the coding agent can hand mole a question and collect the answer. In toolkit mode, the coding agent can do its own reasoning while mole supplies non-model-call parts of the workflow.

That is a neat fit for Cursor users because Cursor’s Agent can already work across files, tools, and reviewable changes. The safer shape is to let Cursor ask mole for a research receipt, then have Cursor propose code only after the evidence is visible.

Here is a small Cursor rule stub that keeps that boundary explicit:

---
description: Use mole research output as evidence, not authority
globs:
  - "**/*"
alwaysApply: false
---

When a task uses mole or another MCP research tool:
- Do not edit code until the research answer includes cited claims.
- Paste the short research receipt into the chat before proposing changes.
- Treat uncited claims as guesses.
- If local data was used, say which files were read and whether raw data left the machine.
- Prefer a small patch plus a review note over broad refactors.

The trap is giving every MCP tool full trust because it is convenient. Start with read-only research. Then decide whether the evidence is strong enough to justify edits.

Try it safely checklist

Use mole when the question has enough value to deserve a receipt. Do not use it just because it is fun to watch an agent think.

A safe first experiment is small:

• Pick one question with a clear answer shape, like “Which queue consumer handles invoice retries?”
• Set a low budget, such as the README’s example style of --usd 0.50.
• Use non-sensitive sources first.
• Require quote-backed claims in the final answer.
• Paste the receipt into Cursor before asking for any code change.
• Stop if the answer contains uncited claims, vague citations, or unexplained contradictions.

This is not an AI coding workshop in a box. It is a focused research agent with unusually concrete constraints, and that is exactly why it is worth studying.

Common questions

• How can mole promise a hard budget if model calls vary?

  mole’s design reserves spend before each model call and settles it after the call, against a ledger that is constrained in the database. The README says measured overshoot across its test corpus is 0%. The caveat is that provider pricing, max tokens, and caching behavior still need to be understood for your configuration.

• Does mole keep local data private?

  mole is designed to run locally as a static binary and provide a privacy boundary for local data. That is useful for CSVs, logs, and repo notes, but you should still check which model and search providers are called. “Runs locally” does not automatically mean “no network calls ever happen.”

• Why use mole instead of a chat tool with web search?

  Use mole when the budget and citations matter more than convenience. A chat search answer may be faster, but mole’s pitch is enforced spend, quote-checked claims, contradiction checks, and MCP access from coding agents. For disposable questions, a normal search box may still be enough.

• Is mole useful inside Cursor?

  Yes, the interesting use is as a research handoff into Cursor rather than as a code-editing agent itself. Let mole gather evidence, then let Cursor’s Agent work from that receipt inside the IDE. The review point is the cited answer, not a long hidden chain of prompts.

• Is there any naming confusion around Mole?

  Yes, there is at least one other GitHub project using the Mole name, so refer to this one as lajosdeme/mole when sharing it. That small detail matters in docs, MCP configs, and issue links, because “Mole” alone can point readers to the wrong repository.

Best ways to use this research

• Best for: evaluating whether terminal research agents can be made reviewable enough for agentic coding workflows.
• Best first artifact: a short research receipt with the question, budget, sources, quote-backed claims, contradictions, and any local files read.
• Best comparison angle: compare mole against a chat search workflow on cost control, citation quality, and privacy boundary, not on answer polish.
• Best Cursor workflow: ask mole for evidence first, then ask Cursor’s Agent to make the smallest code change that the evidence supports.

Further reading

• mole — source
• Cursor — Agent
• Model Context Protocol — specification
• Cursor — Rules

Next step

Try mole on one low-stakes research question with a hard budget and quote requirements. If the receipt is good enough that you would paste it into a code review, the tool is doing something real.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.