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. 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?”

Don't treat 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 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, AI coding governance.

Don't let 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.

Don't assume “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.

Don't give 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

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.

Further reading

• mole on GitHub
• Cursor Agent docs
• MCP 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.