---

name: librarium description: "Runs evidence-aware, multi-provider research with the Librarium v2 CLI. Use for deep research, competitive research, answer-engine visibility checks, or questions needing grounded multi-source coverage." compatibility: Requires Node.js 22.12 or newer and the Librarium 2.x CLI.

Librarium -- Multi-Provider Deep Research

Run research queries through Librarium’s v2 public provider/profile catalog. There are 34 built-in providers and 41 implemented profiles. Preserve the profile and collection provenance when reporting results; do not turn source counts or agreement into a confidence claim.

Prerequisites

Before the first query in an orb, run librarium --version and require major version 2. The Librarium repository's .agents/setup installs its built v2 checkout globally. In other orbs, install the published v2 package when it is available:

npm install -g 'librarium@^2'

Do not silently fall back to Librarium 1.x or install a mutable Git branch. If npm has no v2 release yet, report that distribution blocker instead. Configure available API keys with librarium init --auto, then inspect the usable matrix offline with librarium doctor and librarium ls --json. This confirms only configuration and credential presence, not authentication or connectivity, and does not load configured custom provider code. Use librarium doctor --live only when the user explicitly wants live connectivity tests; it loads trusted custom providers, makes provider network requests, and may incur charges. Never print secret values.

7-Phase Research Workflow

Phase 1: Query Analysis

Analyze the user's research question. Determine:

• Is this a technical, business, or general knowledge query?
• Which built-in workflow is best suited? (quick for a curated low-latency set, deep for research-report profiles, visibility for an explicit nine-perspective comparison, all for catalog-derived coverage). Use custom:<name> for a user-authored group.
• What execution mode? (sync for quick queries, mixed for deep research)

Phase 2: Provider Selection

Select providers based on query type:

• Technical queries: Start with quick; add named durable profiles or deep only when the question warrants the latency and possible spend.
• Quick facts: Use quick group (AI-grounded only, fast)
• Competitive research: Use all only after confirming its configured, credentialed membership and cost exposure.
• Answer visibility: Use visibility only when you deliberately want six SearchAPI-collected consumer-surface observations compared with three first-party API baselines. Treat the six collection-vendor results as correlated evidence, not independent confirmation.
• Specific provider: Use --providers (canonical IDs or display names, e.g. -p "Exa Search,brave-search")

Phase 3: Dispatch

Run the query:

librarium run "your query here" --group <group> [--mode mixed]

Phase 4: Monitor Async Tasks

If a profile is background/durable and was submitted in async mode:

librarium status --wait

Phase 5: Retrieve Results

Once the provider is observed complete, retrieve the terminal result:

librarium status --retrieve

Phase 6: Analyze Output

Read the output files:

1. summary.md -- Overall research summary with statistics
2. sources.json -- Deduplicated citations ranked by frequency
3. Individual {provider}.md files for detailed per-provider results
4. run.json -- Machine-readable manifest

Phase 7: Synthesize

Combine findings from multiple providers into a coherent answer. Record source overlap and provenance, but do not convert a higher citation count into a confidence score: shared collectors and repeated sources can make that evidence correlated.

Key Commands

| Command | Purpose | |---------|---------| | librarium run <query> | Run research query | | librarium run <query> --group quick | Fast AI-grounded search | | librarium run <query> --group deep | Deep research (async) | | librarium run <query> --group visibility | Compare six collected consumer surfaces with three first-party API baselines | | librarium run <query> --group all | Catalog-derived selectable coverage | | librarium answer <query> | Fan out (default quick) and synthesize one grounded, cited answer to answer.md | | librarium run <query> --max-cost 0.50 | Stop launching providers once API-reported cost crosses the budget | | librarium run <query> --yes | Skip the deep-research pre-flight confirm (3+ deep providers) | | librarium status | Check async tasks | | librarium status --wait --retrieve | Wait and fetch Node CLI async results | | librarium live-validation --fixture /absolute/path/to/fixture.json | Replay a strict, network-free canonical fixture | | librarium usage [--days N] [--json] | Aggregate API-reported cost and tokens across past runs | | librarium run <query> --html --open | Run, then open an HTML report | | librarium run <query> --jsonl | Run, then write machine-readable results.jsonl | | librarium browse | Browse past runs interactively | | librarium html [run-dir] | Generate report.html for a run | | librarium jsonl [run-dir] | Generate results.jsonl for a run | | librarium refine <goal> | Tier-tuned query variants, no dispatch | | librarium ls | List providers and status | | librarium doctor | Check provider configuration and credential presence offline | | librarium doctor --live | Test connectivity with provider network requests; charges may apply | | librarium config | Show resolved config | | librarium cleanup [--days N] [--dry-run] | Delete run dirs older than N days (default 30) | | librarium clear [--dry-run] [-i] [--yes] | Delete all run dirs (alias for cleanup --all); -i to pick interactively |

MCP Server

Instead of shelling out to the CLI, agents can drive librarium over the Model Context Protocol with librarium mcp (stdio transport). Register it once with claude mcp add librarium -- librarium mcp, then call the tools: research, get_results, check_async, list_providers, list_groups. The research tool runs the same silent file-writing pipeline as librarium run and returns a compact structured result; fetch full provider markdown with get_results.

Provider Tiers

| Tier | Providers | Speed | Depth | |------|-----------|-------|-------| | background/durable | exa/research, openai-research/research, gemini-deep/research, perplexity-sonar-deep/research, perplexity-deep-research/research, you-research/research, parallel/research, and valyu/research | Minutes to longer | Persisted handles that can be polled and retrieved | | inline | Search, grounded, collected surface, and chat profiles | Usually seconds | Immediate response; no durable handle |

Visibility and privacy boundary

The six SearchAPI surface profiles observe consumer-facing ChatGPT, Gemini, Perplexity, Google AI Mode, Bing Copilot, and Google AI Overview output through one upstream collector. Treat agreement among them as correlated visibility evidence, not independent corroboration or parity with a particular logged-in user. zeroRetention is an account capability: if explicitly configured, Librarium fails closed when the account rejects it. It makes no broader retention or privacy guarantee. SerpBase may log search queries for billing, debugging, abuse prevention, and account logs; no zero-retention mode or fixed public retention period is documented.

Output Structure

./agents/librarium/{timestamp}-{slug}/
  prompt.md, run.json, summary.md, sources.json
  {provider}.md, {provider}.meta.json
  answer.md (when using `librarium answer`)