io.github.dir-ai/voyager

voyager

The verified-brief organ for coding agents.

An AI coding agent that reaches the open internet gets a raw, unsigned, possibly-poisoned blob and feeds it straight into its own prompt. voyager sits in front of that: it turns a query into a cited, confidence-scored, OSV-gated, injection-hardened brief — the only surface your model ever sees.

Every claim carries its provenance and a confidence signal. Package recommendations pass a fail-closed OSV vulnerability gate, surface build provenance (npm SLSA attestations) when present, and can be reproduced in a disposable twin — install + smoke-import run inside a hardened, rootless, network-isolated container (never on the host). That proves the package installs and its entrypoint loads; it is not a safety proof. All fetched text is stripped of instruction-shaped payloads (multilingual + base64 + markdown /HTML vectors) and framed as untrusted evidence the model must analyze, never obey.

• check — is this package safe to use? Registry facts + OSV gate (fail-closed)
  • provenance/license/age supply-chain signals + optional isolated twin. Exit codes: 0 ok · 1 rejected (unsafe) · 2 tool/usage error (no verdict).
• brief / retrieve — a cited brief combining package verification, GitHub discovery, canonical docs, and open-web search, each cross-referenced.
• security by construction — one egress allowlist, https-only, streamed size cap, injection-strip + evidence framing. Zero-network unless you query.

CLI, library, and MCP server.

Install

npm i @dir-ai/voyager
npx -y @dir-ai/voyager check express

CLI

voyager check <name> [--ecosystem npm|pypi] [--version V] [--twin]   # exit 1 if unsafe
voyager brief "<query>" [--package name] [--discover "<intent>"] [--search "<q>"] [--docs <lib>]
voyager discover "<intent>"     # GitHub repo discovery (Tier-A)
voyager search "<query>"        # open-web search (Tier-C, needs a key)
voyager docs <library>          # canonical docs (Tier-B)
voyager doctor                  # which source keys are configured

check is a natural CI gate: fail the build if an agent picked a vulnerable, deprecated, or non-existent dependency.

Library

import { checkPackage, voyagerRetrieve, setKeyResolver } from '@dir-ai/voyager'

const v = await checkPackage({ name: 'express', ecosystem: 'npm' })
// → { verdict: 'belief' | 'fact' | 'rejected', claim, steps }  (adversarial trace)

const brief = await voyagerRetrieve('a safe date library', {
  packages: [{ name: 'date-fns', ecosystem: 'npm' }],
  discover: 'date library',
})
brief.rendered   // the injection-hardened, framed text to feed a model
brief.claims     // structured, cited, confidence-scored

// Bring your own key store (default is env vars):
setKeyResolver((provider) => mySecrets.get(provider))

MCP server

// .mcp.json
{
  "mcpServers": {
    "voyager": { "command": "npx", "args": ["-y", "@dir-ai/voyager", "mcp"] }
  }
}

Tools: check_package, retrieve, discover_repos, fetch_docs.

Docker

docker run --rm ghcr.io/dir-ai/voyager check express
docker run -i --rm ghcr.io/dir-ai/voyager mcp   # stdio MCP

Tiers & trust

Tier	Source	Base trust
A	GitHub · npm · PyPI · OSV (structured facts)	high
B	canonical docs (official hosts only)	high
C	open-web search (Tavily / Exa / Apify)	low — cross-referenced before trusted
D	isolated twin (install + smoke in a container)	reproduction, not a safety proof

Keys are optional: the Tier-A core (npm/PyPI/OSV, and GitHub unauthenticated) is zero-key. Tier-C providers each no-op without their key. Set GITHUB_TOKEN, TAVILY_API_KEY, etc., or inject a resolver.

Security posture

One egress allowlist (a fixed set of public API hosts), https-only, redirect: error, a streamed byte cap that aborts an oversized body mid-download, and an injection-strip that removes role-hijacks / chat-template tokens / zero-width & bidi characters, decodes-and-rescans base64, neutralizes markdown images and HTML comments, and matches instruction payloads across several languages. The framing is the real defense — the strip keeps it from being trivially escaped. The twin runs the package's code only inside a hardened, network-isolated, read-only, non-root container; with no container runtime it refuses to run (returns unsupported) rather than execute on the host. See SECURITY.md.

Cache

Idempotent Tier-A facts (npm / PyPI / OSV) are cached in-process and on disk under ~/.voyager/cache (content-addressed, TTL'd) so repeated checks are fast, survive across runs, and lean less on the network. No secret is ever written (auth headers are never part of a cache key or value). VOYAGER_NO_CACHE=1 disables it; VOYAGER_CACHE_DIR relocates it.

Roadmap

deps.dev-backed multi-ecosystem facts (crates / Go / RubyGems / Packagist), typosquatting detection, PyPI/cargo twins. Contributions welcome.

License

MIT © dir-ai