voyagervygr
Source
AbstractRust · single static binaryMIT

Deep research that leaves a paper trail.

Voyager is a deep-research CLI built for agents. It chains eleven search providers (keyless DuckDuckGo and academic indexes out of the box, six more behind env keys), reduces pages to text, and runs a plan-search-synthesize loop with verified citations over your agent harness's model, a local Ollama, any OpenAI-compatible provider, or any command you point it at.

Install vygrGo to GitHub$cargo install vygr

MCP over stdio + HTTP · agent skill · --format json everywhere · evidence on disk

Fig. 1run artifacts · agents/voyager/<run>/
  • run.jsonrun manifest: parameters, status, cost
  • prompt.mdthe question + run parameters
  • plan.jsonsub-queries and chosen depth
  • reflections.jsondistilled notes per level
  • sources.jsonscored sources, with content
  • claims.jsonclaim-level evidence table
  • answer.mdreport with [n] citations
Every research run writes its full evidence trail to disk. Inspect it, diff it, cite it.
§ 1

Method

The loop

vygr research runs a real iterative loop: plan the sub-queries, then repeat search, fetch, score and reflect until the model has enough evidence to synthesize a cited report. Nothing is hidden; every stage leaves an artifact.

  1. 01--depth 2..4

    Plan

    An LLM turns the question into sub-queries and picks a depth within the range you allow. --mode presets (quick, standard, deep, exhaustive) set depth, breadth and fetch as starting points.

  2. 02--all

    Search

    Each level goes back to the web through the provider chain, with concurrent fan-out and URL dedup on request.

  3. 03vygr extract

    Fetch

    Top results are fetched over HTTP and reduced to structured, readable text; stubborn pages retry through a reader ladder, and PDFs get extracted.

  4. 04BM25

    Score

    BM25 ranks the collected evidence so only what matters enters the context window.

  5. 05reflections.json

    Reflect

    The LLM distills notes and follow-up queries from the gaps it finds, and flags disagreements between sources. Breadth halves every level.

  6. 06answer.md

    Synthesize

    A markdown report with numbered citations, each checked against the stored evidence; conflicting sources are reconciled explicitly, and every claim lands in claims.json.

§ 2

Materials

Search providers

Search is pluggable at the SearchProvider seam. DuckDuckGo and the academic indexes work with zero configuration; six more wake up when their environment key appears, and a self-hosted SearXNG slots into any chain. Any of them compose into chains, and every backend is rate-limited, retried, cached and circuit-broken behind the scenes.

Table 1provider registry
ProviderAccess
ddgskeyless
braveBRAVE_API_KEY
tavilyTAVILY_API_KEY
exaEXA_API_KEY
serperSERPER_API_KEY
jinaJINA_API_KEY
kagiKAGI_API_KEY
openalexkeyless
semanticscholarkeyless
arxivkeyless
searxngkeyless

Table 1 · provider registry, 11 backends

Fallback chain

default_provider = "ddgs,brave"

The first provider with a non-empty result set wins; failures degrade gracefully to the next link.

Concurrent fan-out

vygr search "q" --all

Searches every provider at once, merges and deduplicates by normalized URL, and records which provider returned each hit.

Cache and politeness

query-class TTLs

News, standard and reference queries get TTLs of 5 min, 1 h and 24 h. Rate limiting with retry and backoff, a per-provider circuit breaker, --no-cache to opt out.

§ 3

Results

Evidence you can audit

A report from a black box is a rumor. Voyager treats a research run like a lab notebook: the plan, the sources, the reflections and the synthesis are all written down, in plain files you can read.

Listing 1a research run
$ vygr research "state of WebAssembly GC in 2026"
--llm pi --depth 2..4--budget-usd 0.50
plan 3 sub-queries · depth 3
level 1 12 hits · 5 fetched · BM25 kept 4
level 2 breadth 2 · 2 follow-up queries
synthesize answer.md · 9 citations
verify 9 citations · 8 supported · 1 flagged
cost $0.213 of $0.50
→ artifacts in agents/voyager/20261002-0914-wasm-gc/
Illustrative trace. Diagnostics go to stderr; with --format json the same data arrives on stdout.
  1. i

    Artifacts on disk

    prompt.md, plan.json, reflections.json, sources.json, claims.json, answer.md and a run.json manifest under agents/voyager/<run>/. vygr runs list|show|resume re-synthesizes any run offline from its saved evidence.

  2. ii

    Verified citations

    After synthesis, every sentence carrying [n] is checked against the stored sources; weakly supported claims are flagged in the report itself and land in a claim-level claims.json evidence table. --output-schema keeps answers machine-parseable.

  3. iii

    Honest accounting

    Every LLM call is priced from the models.dev catalog, or reports the real cost billed by your harness, and is checked against --budget-usd before it runs. Reports carry the final cost_usd.

  4. iv

    Continuable and gradable

    vygr eval scores a finished run deterministically (citations, coverage, diversity) into eval.json; vygr followup continues an investigation from its saved evidence, hunting only what is missing, and vygr monitor re-runs it on a schedule.

§ 4

Apparatus

The command surface

Seventeen subcommands, one contract. Everything a human reads in a terminal, an agent can read as JSON, so the same tool serves both.

Table 2command surface
vygr search <q>Provider-chain search: --all fan-out, --extract-top N, --format jsonl, time ranges, domain filters, --safe-search, cache control
vygr extract <urls>Fetch pages and reduce them to plain, structured text
vygr research <q>The full loop: plan, levels, reflections, synthesis with citation verification; --mode presets, --events NDJSON stream, artifacts under agents/voyager/<run>/
vygr plan <q>Offline preflight of a research run
vygr providersSearch providers, their env keys and readiness
vygr models [provider]Browse the models.dev catalog and pricing
vygr schemaMachine-readable self-description derived from the CLI itself: every flag, default and choice
vygr configEffective configuration and file paths
vygr init --agent piInstall the agent skill and its references into your harness; --detect probes the environment, --mcp registers the MCP server
vygr doctorEnvironment self-check: providers, LLM backend, dirs, skill freshness
vygr cache dir|clearInspect or clear the search cache
vygr serveMCP server: stdio by default, Streamable HTTP with --http; search, extract, research, get_artifact, list_runs, get_run
vygr updateSelf-update from crates.io; --check only reports
vygr runs list|show|resumeInspect past runs; re-synthesize one offline from saved evidence; show --export report.docx|report.pdf
vygr followup <run> <q>Continue a finished investigation from its saved evidence: only hunts what is missing, emphasizes what changed
vygr monitor add|list|runRecurring research: each check continues from the previous run (trend snapshots)
vygr eval <run>Deterministic quality scorecard for a run: citations, coverage, diversity, written to eval.json
§ 5

Backends

Bring your own model

The loop is model-agnostic: everything pluggable hangs off a singleLlmClient seam, and the same run reads the same whether the brains are in the cloud, on your laptop, or inside your coding agent.

--llm pi--llm claude--llm codex

Reuse the harness

vygr shells out to the agent harness in print mode and pipes the prompt through stdin, reusing the model and credentials you already have configured. Structured output envelopes report the real cost of every call. No MCP pass-through.

--llm ollama:qwen3:8b

Local and cheap

A native Ollama client with thinking control handled for you. Reasoning models that answer through <think> blocks are stripped back to the answer, and --budget-usd caps what a run may spend.

--llm openrouter:deepseek/deepseek-chat

Any provider, priced

Any OpenAI-compatible provider from the models.dev catalog. vygr models browses models and pricing; the catalog (cached 24 h) also feeds the cost accounting of every run.

--llm cmd:<template>

Any command

Shell out to anything: vygr pipes the prompt to a command of your choice through sh -c and reads the completion from stdout. gemini-cli, aider, or your own wrapper script; the template knows its own pricing.

MCP server included

vygr serve exposes search, extract, research, get_artifact, list_runs and get_run over stdio, with run artifacts as MCP resources, packaged research prompts, token-safe paged reads and progress notifications that keep long runs visible. The same surface serves as Streamable HTTP with --http and bearer-token auth. Register it, install the bundled skill, or pull it from the skills registry:

$ pi mcp add voyager -- vygr serve
$ vygr serve --http 127.0.0.1:8080
$ vygr init --agent pi|claude-code|codex|cursor|omp|opencode|gemini-cli|generic
$ npx skills add jaltez/voyager
§ 6

Distribution

Install

One Rust workspace, one static binary. Nothing below the CLI knows that clap exists, and nothing above it needs to know Rust.

crates.io

cargo install vygr

The released binary. Installs the vygr command; workspace crates come along.

GitHub releases

./install.sh

Prebuilt tarballs for linux (glibc and static musl) and macOS, x64 and arm64. Falls back to cargo when no binary matches.

From a checkout

cargo install --path crates/cli --bin vygr

Build from source against your own toolchain.

already installed? vygr update self-updates from crates.io · workspace crates: vygr-core · vygr-providers · vygr-llm · vygr-research