# mole

> A deep-research CLI agent in Go that decomposes questions, searches sources, verifies claims with verbatim quotes, enforces a hard cost budget, and exposes results over MCP.

Mole is an open-source deep-research agent written in Go, built by lajosdeme and released under the Apache-2.0 license. It runs as a static binary on your machine, uses your own API keys, and exposes its capabilities over the Model Context Protocol (MCP) so coding agents can drive it programmatically. The project reached its first stable release (v0.1.0) in August 2026.

## What It Is

Mole is a command-line research agent that takes a question, decomposes it into sub-questions, searches the web and academic databases, fetches and reads sources, extracts claims, checks each claim's quote verbatim against the page it came from, looks for contradictions between claims, and writes a cited answer. It is designed for situations where you need verifiable, grounded research output rather than a chat-style summary — and where you want a hard ceiling on what the run can spend.

## How the Budget and Claim Integrity Work

Three design properties distinguish mole from a chat interface with web search, according to the project README:

- **Enforced budget**: Every model call is reserved against a ledger before it is made and settled after. The schema enforces non-negative constraints at the database level. The README states measured overshoot across the test corpus is 0%.
- **Verified quotes**: A claim whose verbatim quote does not appear in the page it was mined from is discarded at extraction, before it can reach an answer. The README reports 100% citation accuracy across stored claims.
- **Local data privacy**: CSV files or folders can be registered with `mole connect add`; the model never sees a raw row and never writes SQL — it picks a template and column names, mole renders the SQL, and only aggregates (counts, means, test results, buckets covering at least five records) are allowed back. `mole crossings` shows exactly what left the machine.

## Architecture and Toolkit Mode

The core pipeline runs: planner → executor → actor (search/fetch/extract/mine) → verifier (pair claims, adjudicate, build graph) → output synthesiser. Three actor types feed the same claim graph: **web** (search and page fetch), **academic** (Crossref, OpenAlex, arXiv, PubMed with DOI deduplication), and **local_compute** (deterministic SQL over registered data).

Toolkit mode (`mole serve --toolkit`) inverts the ownership model: the agent's own model does the reasoning while mole contributes the deterministic half — quote checking, pair retrieval, merging, SQL rendering. This is designed for users already inside Claude Code, Qwen Code, or similar subscription-based coding agents where model tokens are already paid for. Toolkit mode exposes 14 named tools (`mole.<tool>`) alongside the standard `research.*` tools.

## MCP Integration and Deployment

Mole ships two static binaries — `mole` and `mole-mcp` — with no runtime dependencies (`CGO_ENABLED=0`). The MCP server listens on a Unix socket (mode 0600) in a private directory and refuses connections from other users. Credentials are held by the daemon, not in the `.mcp.json` client config file. Any OpenAI-compatible endpoint works as the model provider, including DeepSeek, Ollama, llama.cpp, vLLM, or a local proxy; a localhost model is priced at zero and still counted in tokens.

## Setup Path

Mole supports multiple install paths:
- **Install script** (Linux/macOS, amd64/arm64): `curl -fsSL .../install.sh | sh`
- **Homebrew**: `brew install lajosdeme/mole/mole`
- **Arch Linux AUR**: `yay -S mole-research-bin` or `yay -S mole-research`
- **Debian/Ubuntu**: `.deb` from the releases page
- **From source**: requires Go 1.25+

Configuration is stored in `~/.config/mole/config.json` (mode 0600). Supported search providers are Tavily and Brave; supported LLM providers are Anthropic and any OpenAI-compatible endpoint.

## Update: v0.1.0

The first stable release, v0.1.0, was published on 2026-08-13. The repository was created on 2026-08-01 and last pushed on 2026-08-13, indicating active early development. The project self-reports grounding rate at 80% and contradiction precision at 70% with the confirm pass, and publishes these metrics openly via `mole eval`.

## Features
- Enforced cost budget with 0% measured overshoot
- Verbatim quote verification for every extracted claim
- Local data privacy boundary — only aggregates leave the machine
- Web, academic (Crossref, OpenAlex, arXiv, PubMed), and local_compute actor types
- MCP server mode for coding agent integration
- Toolkit mode for agent-driven reasoning with mole as deterministic backend
- Dataset mode with fuzzy row merging across sources
- Follow-up questions answered from existing session claims
- Per-session cost and timing trace
- OpenAI-compatible endpoint support (DeepSeek, Ollama, llama.cpp, vLLM)
- Self-grading eval scorecard via `mole eval`
- Static binary with no runtime dependencies

## Integrations
Anthropic Claude, OpenAI-compatible APIs, DeepSeek, Ollama, llama.cpp, vLLM, Tavily Search, Brave Search, Crossref, OpenAlex, arXiv, PubMed, Claude Code, Qwen Code, MCP clients

## Platforms
MACOS, LINUX, API, CLI

## Pricing
Open Source

## Version
v0.1.0

## Links
- Website: https://github.com/lajosdeme/mole
- Documentation: https://github.com/lajosdeme/mole
- Repository: https://github.com/lajosdeme/mole
- EveryDev.ai: https://www.everydev.ai/tools/mole-research-agent