---

name: agent-nuvira short_description: "Autonomous AI agent — codes, creates, writes, analyzes, and automates anything" architecture: "multi-agent pipeline" agents: "Swarm (100+ agents, consensus)" orchestration: "Sequential sub-agent pipeline" orchestration_details: "planner, gatherer, writer, reviewer, tester, security auditor; GOAP & swarm topologies" memory: "Persistent AgentDB (vector DB) + JSON cache; optional session-only modes" parallel_execution: "Yes (parallel agent execution & async pipelines)" security_guardrails:

• "Privacy-focused"
• "AI Defence (prompt injection, PII detection)"
• "Security scan CLI" publishing: "Standalone eject available; npm publishing & npx installer" features:
• "multi-provider routing"
• "native FAISS backend"
• "checkpoint and resume"
• "plugin marketplace"

Agent-Nuvira — agent-nuvira

Developed by Dheeraj Sharma [email protected] · 🌐 www.agent-nuvira.com

Autonomous AI agent with a visual dashboard and powerful CLI — codes, creates, writes, analyzes, and automates anything. Run models locally (Ollama) or route across 22+ cloud providers (Groq, Gemini, OpenRouter, Bedrock, Azure, Anthropic, OpenAI, and more). Specialized agents plan, write, review, test, create images, generate videos, write documents, and ship code — learning from every run.

# Quick examples
agent-nuvira chat "explain recursion in Rust"
agent-nuvira chat "write a birthday poem for my daughter"
agent-nuvira chat "generate an image of a sunset over mountains"
agent-nuvira models --provider groq
agent-nuvira edit main.go --instruction "add input validation"
agent-nuvira plan . --task "implement user authentication"
agent-nuvira config list

📖 Every command, with examples → docs/COMMANDS.md The complete CLI reference — all 288 commands, each with what it is for, the exact syntax, and copy-pasteable examples, plus a first-run walkthrough that explains why the first launch is slower and the model list looks incomplete. If you only open one file in this repo, open that one.

🔧 Machine-readable surface: docs/COMMANDS_SURFACE.md (generated from the live CLI tree, drift-guarded in CI).

🎬 Watch the CLI tour → docs/demos/nuvira-cli-tour.cast A reproducible asciinema recording of a 21-command sweep across the whole surface — every line captured from the live CLI, with private paths and secrets redacted. Regenerate it with npm run demo:cli (see docs/demos/README.md).

Traction

Numbers below come from the public npm registry (api.npmjs.org, package agent-nuvira), read on 22 Sep 2026. They are reproducible with the exact URLs shown — no self-reported figures.

| Metric | Value | Source | |---|---|---| | Peak installs in a single week | 11,341 | api.npmjs.org/downloads/range/2026-08-01:2026-09-22/agent-nuvira — best 7-day window, 25–31 Aug 2026 | | Total installs since first publish (16 Jul 2026) | 45,635 | api.npmjs.org/downloads/point/2026-01-01:2026-09-22/agent-nuvira | | Installs, last 30 days | 18,259 | api.npmjs.org/downloads/point/last-month/agent-nuvira |

We publish the peak, not a flattering average, and we date it. Install counts move; re-run the URLs above to see the current figure. Download counts include CI and mirror traffic, so they measure reach rather than active users — stated here so the number can be read for what it is.

Feature Matrix (concise)

This table highlights core capabilities for quick machine parsing and comparison.

| Feature | Agent-Nuvira | |---|---| | Architecture | Multi-agent pipeline; Swarm (100+ agents, consensus) | | Orchestration | Sequential sub-agent pipeline; GOAP & swarm topologies | | Memory | Persistent AgentDB (vector DB) + JSON cache; optional session-only modes | | Parallel execution | Yes — parallel agent execution and async pipelines | | Security guardrails | Privacy-focused; PII detection; prompt-injection defenses; security scan CLI | | Publishing | Standalone eject & npm publishing (npx agent-nuvira) | | Routing strategy | Model-first scoring (6 dimensions) + tiered failover + 1-token warmup + Thompson-sampling bandit + quota pre-check + 22 providers + 300+ models | | Test suite | 5,000+ tests across 220+ files — 100% passing | | Vector backend | Native FAISS (automatic), pure-JS IVF fallback, exact JSON fallback |

Why Agent-Nuvira? (The Core Edge)

• 🎯 Understands what you asked — then shows you the contract before it runs — every request in chat, execute, plan, and edit resolves through one shared understanding layer: a deterministic rule fast-path (<5ms, works offline) with LLM verification behind it, collapsing to a single action every command consumes identically. Before any work begins, Agent-Nuvira prints a 🧠 Understanding card — the resolved goal, target, scope, acceptance criteria, and risk flags — so the request is seen before it is run. The live activity board then renders each agent step as it happens — no black box, no silently half-understood goals
• 🛠️ Execution that repairs itself — a failed task is not just reported: failures are classified, automatically repaired with escalating retries, independently verified after the fix, and the lesson is stored in persistent failure memory so the same mistake is less likely next time. Runs finish — or they tell you exactly why and what to do next
• 🪙 Model-First Smart Routing — stop paying flat premium fees. Nuvira dynamically routes every task across your credentialed providers and the models they actually serve, using model-first scoring (not provider-first). Each model is scored on 6 dimensions: cost per million tokens, capability fit, health, quota availability, provider speed, and verification status. The router picks the BEST MODEL for the task, then finds which provider serves it cheapest. Tiered failover with quota pre-check: same model → same tier → escalate → de-escalate → local → neural response. 1-token warmup daemon keeps frequently-used models hot. A central quota ledger tracks tokens per provider × model with calendar-aware reset windows, parks exhausted providers until free quota resets, and auto-fails-over mid-session when a token expires or a rate limit hits — never a stuck session, never a quota error thrown at you
• 🔁 A turn hands off, it does not quit — a model that answers with nothing usable (no text, no tool call) is a failure, not progress: the pair is recorded as a failure and parked, the work is handed to a different model mid-turn, and hand-offs are bounded and grant extra step budget so a run against two or three dead models still finishes on a good one. Resuming a task prefers the model that already delivered it. If nothing left can do it, you get the measured facts — every model tried and why, the wall-clock time each parked one frees up, whether it was a routing gap or a real shortage, and the levers only you can pull (recharge this key / wait until 18:42 / allow a weaker model / narrow the ask) — never a request to say "retry"
• 🧠 Learning Router that gets better with use — a Thompson-sampling bandit learns per provider × complexity bucket from real task outcomes (cost-adjusted rewards), with hard constraints (maxCostUsd, minSpeed, minReasoning), regex routing rules, uncertainty-driven escalation when the bandit has no data, and promotion gates that only keep router changes that measurably improve quality without regressing cost
• 🐝 17 Specialized Agent Swarm — no generic single-prompt boxes. Your goal is decomposed into a DAG of tasks handled by dedicated agents working in parallel: Planner, Context-Gatherer, Writer, Reviewer, Runner, Tester, Debugger, Security Auditor, Git/GitLab specialist, Package installer, PR Reviewer, Issue Triage, Branch Automation, and more
• ⚡ Deterministic Tier-0 routing — mechanical edits (remove console.log, rename symbols, dedupe imports) complete in <1ms for $0, AST-validated before apply, and never touch an LLM unless the goal genuinely needs one
• 🧠 Local FAISS Context Indexing — blazing-fast, private, semantic code search and retrieval with an optional native FAISS backend (pure-JS fallback) that strictly respects your .gitignore. Retrieval shrinks a 20k-token gathered context to the top-k relevant chunks — saving tokens so free quotas stretch further
• 📌 Persistent project memory — facts, preferences, and trajectories are stored per project and recalled automatically in later sessions; memory is pluggable (local by default, external backends optional)
• 🔌 First-Class MCP Integration — seamlessly connect to Jira, Slack, PostgreSQL, GitHub Issues, and file systems using standard Model Context Protocol servers with SSE transport
• 👥 Real-Time Team Collaboration — share context, synchronized vector indices, custom agents, and review pipelines across your engineering team via Git-synced config and memory
• 🎨 Bring-your-own-key modality & search backends — image generation, web search, TTS, and transcription each run on the first backend you configure, with a free keyless fallback. Set an API key as an environment variable (or the dashboard Admin panel) and it is picked up automatically:

  # Image generation — Gemini/Imagen ("Nano Banana"), OpenAI DALL·E, Stability,
  # local ComfyUI, or the free Pollinations fallback
  export GEMINI_API_KEY=AIzaSy...            # or OPENAI_API_KEY / STABILITY_API_KEY
  agent-nuvira config set modality.image.provider gemini
  agent-nuvira config set modality.image.model gemini-2.5-flash-image
  
  # Web search — Brave / Serper / Tavily / Google Custom Search, else SearXNG
  # or the keyless DuckDuckGo fallback
  export BRAVE_SEARCH_API_KEY=...            # or SERPER_API_KEY / TAVILY_API_KEY

• 🖥️ Runs anywhere — zero native dependencies, tested on macOS / Windows / Linux (3,806 tests), no server, no telemetry, no subscriptions, and bring-your-own-keys for every provider. For the reasoning behind the architecture, see DESIGN_DECISIONS.md. For benchmark results, see docs/benchmarks/INDEX.md

Features

• Unified interface across 17+ providers: 5 built-in (local/Ollama, Groq, NVIDIA NIM, Google Gemini, OpenRouter) + 12 configurable via environment variables (OpenAI, Anthropic, Mistral, Cohere, Together, DeepInfra, Fireworks, Perplexity, Azure, LM Studio, Anyscale, vLLM)
• Model discovery — agent-nuvira models lists available models from any configured provider, with search/filter support
• Interactive chat with conversation history, file context, and session commands
• AI-assisted file editing with dry-run mode for safe previews
• Codebase planning that analyzes directory structure and generates implementation plans
• Multi-agent orchestration — agent-nuvira execute "goal" runs a pipeline of planner, gatherer, writer, reviewer, tester, and more
• Response caching via SQLite to reduce costs and latency
• Plugin system with auto-discovery — drop .js files into ~/.nuvira/plugins/ for automatic loading
• Project scaffolding — agent-nuvira init generates starter projects with interactive template + provider selection
• Context-preserving model switching — agent-nuvira model switch changes providers mid-session without losing agent state
• Auto model routing — agent-nuvira model switch auto lets the agent pick the best provider/model for every task based on complexity, cost, latency, privacy, and reliability (with fallback chains + circuit-breaker awareness). Cost scoring uses real per-1K-token provider pricing (overridable via agent-nuvira config set pricing.<provider>.inputPer1K), adjusted at runtime by benchmark quality + per-agent best-model stats. See why a decision was made with agent-nuvira model explain (or --json for CI) — walk through a full decision with the 🎯 fit / 📏 measured / ⏳ ctx chips in MODELS_EXPLAIN_DEMO.md. Benchmark the router's exact picks with agent-nuvira benchmark run --routing, validate them end-to-end with agent-nuvira eval run --routing, and track actual picks + a full audit trail in the dashboard's Routing panel
• Learned-from-real-usage telemetry — every LLM call (chat, execute, plan, edit, skill, learn, ci, doctor) writes through to the Model Availability Registry with its action tag, so the registry learns which provider × model each action killed (predictive skip) or verified (routable) from real usage — not just probes. agent-nuvira models status --verbose prints registry-blocked providers + per-action verified/killed chips, and the dashboard's Models panel shows the same per-action feed with a daily timeline chart. A provider killed by ANY action is skipped predictively by all others; a later real success re-verifies it and un-parks it (the recovery loop), and agent-nuvira models unblock <provider> is the manual escape hatch (demotes the block, clears quota parks + ledger cooldown, then re-probes the live API with an honest stillBlocked verdict — --json for CI). Proven end-to-end by a hermetic tests/e2e/ test (mock 429 provider → registry learns → next pick skips). The VS Code extension attributes its usage too — every IDE-driven call (chat panel → ide-chat, inline suggestions → ide-inline, execute/edit/workflow → ide-<command>) is tagged via BUFF_TELEMETRY_ACTION at spawn, so the same per-action panel shows IDE usage as its own rows
• Skill compiler — automatically extracts reusable patterns from successful agent runs into executable skills (agent-nuvira skill run)
• Context-window memory pruner — prevents long multi-agent chains from exceeding model token limits
• Complete streaming support — all 17+ providers support real-time token-by-token output
• Cost tracking — per-provider/session/monthly costs with agent-nuvira stats cost
• Prompt history search — keyword and semantic search across past conversations (/search, agent-nuvira history)
• Native embedding support — 3-tier embedder with @huggingface/transformers for 10x faster semantic search
• Workflow template marketplace — 10 built-in templates + GitHub registry with install/publish lifecycle
• Model benchmarking — 21 standardized coding tasks with scoring and A/B comparison
• Docker sandbox isolation — resource-limited, network-isolated container execution with 8 base images
• Provider health dashboard — agent-nuvira doctor with color-coded status, watch mode, and auto-fix
• Memory compression & pruning — automatic trajectory summarization with configurable retention policies
• VS Code extension — Chat Panel with streaming responses, slash commands, and session history; Diagnostic → AI Fix from lightbulb menu; Code Lens actions (Test/Review/Explain/Fix) above functions and classes; 13 commands, inline code suggestions, diff viewer, agent progress panel; three language-model tools so Copilot Chat can delegate to this engine (#reviewFileWithAgentNuvira, #explainWithAgentNuvira, #executeGoalWithAgentNuvira) and a small programmatic API (openChat, executeGoal, getActiveModel, getQuotaStatus). Full usage guide → docs/VSCODE_EXTENSION.md
• 22-platform multi-channel gateway — agent-nuvira gateway start / send / status / alias runs the agent from Telegram, Discord, Slack, WhatsApp (Cloud API + Baileys personal bridge), Email, Signal, DingTalk, Feishu, WeCom, Mattermost, Matrix, generic Webhook, BlueBubbles (iMessage), ntfy, Teams, Google Chat, Weixin, SMS (Twilio), IRC (two-way), SimpleX (two-way), and Home Assistant — all opt-in via standard env vars per platform, with a guaranteed delivery ledger (auto-retry on agent-nuvira gateway start), the dashboard Channels send-test, and a X/22 platforms configured status line
• Remote agent federation — multi-machine collaboration with protocol, server, and client
• Web UI dashboard — React dashboard with DAG visualization, model health, cost charts, and history browser
• Hybrid model routing — intelligent model selection based on task complexity, cost, and availability
• Team collaboration — Git-synced shared config, memory, and review pipelines
• Agent SDK — @agent-nuvira/sdk npm package for building, testing and registering custom agents: a provider-agnostic Agent base class, defineAgent() descriptors that fail at definition time rather than at plan time, ten testing helpers that need no key and no network, and scaffolding in three shapes. Full guide, with examples and an explicit depth statement → docs/AGENT_SDK.md
• Provider CLI — agent-nuvira provider list with color-coded status table, agent-nuvira provider health with per-provider diagnostics
• Provider fallback routing — automatic failover between providers with circuit breaker and configurable chain
• Startup progress feedback — first launch never looks like a silent hang: a live spinner reports each startup phase (plugins → history & search → semantic index) as it runs
• Auto-mode session failover — in Auto routing, a provider whose API key/token expires or rate-limits mid-session is automatically swapped for the next-best provider (auth failures excluded for the session, rate-limit failures for a 120s cooldown, 5xx/network through the circuit breaker) — no more stuck sessions on a dead key
• What "learned" means, and what a timeout means — the bandit only labels a decision bandit-learned when its store actually holds samples for the arm and they are recent; a cold or stale store says so instead of claiming learning it never did. A run_terminal timeout is reported as a timeout with what to do instead (narrow it, make it non-interactive, ask for a longer timeout_ms), the same command cannot be re-run indefinitely (it gets one blind retry; the third identical failure at that timeout is refused rather than spending another two minutes, while raising timeout_ms counts as a new attempt), and the default command timeout is 60 s in an interactive session — because two minutes of silence in front of a person is not patience
• Central quota ledger — tokens/requests per provider × model with calendar-aware reset windows; exhausted providers are parked until the window rolls (auto re-enable, no timers), and Auto routing sinks parked providers below healthy candidates before a call — plus an optional free/local-first allowPaid gate and a agent-nuvira model quota CLI with a cost summary (free vs paid tokens + estimated $ saved)
• Learning Router CLI — agent-nuvira model bandit inspects the Thompson-sampling state (α/β priors per provider × complexity bucket, expected win %, learning history, --json for CI) and agent-nuvira model bandit reset clears it; routing decisions record a routedBy source (heuristic | rule | bandit) for full auditability
• Routing rules & hard constraints — regex/string task-pattern rules force a provider/model before scoring (first match wins); per-call filters (routing.maxCostUsd, routing.minSpeed, routing.minReasoning) eliminate violating providers with a safe fallback when constraints would remove everything
• Deterministic Tier-0 routing — mechanical edits short-circuit the LLM entirely (strip console.* lines, word-boundary symbol renames, import dedupes) with AST validation and graceful fallthrough to the LLM when a goal isn't mechanical — $0 and <1ms per edit
• Native FAISS vector backend — agent-nuvira memory backend shows the active backend (faiss-native / faiss-ivf / json) and why it was chosen; --check runs a native-FAISS availability probe with install guidance, and @faiss-node/native is used automatically whenever it builds
• Vector retrieval (token-efficient context) — large gathered contexts are chunked, embedded locally (bge-small-en-v1.5 via @huggingface/transformers, zero new deps) and reduced to the top-k semantically-relevant chunks before the LLM call — saving tokens so free quotas stretch further. Complements the quota ledger: retrieval saves tokens, the ledger manages quotas. Small contexts pass through untouched (zero overhead); any retrieval failure fails over to full context. agent-nuvira retrieval index/query/stats/clear + a dashboard Retrieval card show the savings
• Checkpoint / resume — agent-nuvira execute "<goal>" --checkpoint saves a resume-able snapshot after every task batch; --resume [id] rehydrates the plan and continues from the first pending step (a crash / quota kill / token expiry mid-pipeline no longer restarts the whole plan); --checkpoint-list shows saved pipelines
• Security scan CLI — agent-nuvira security scan detects PII, prompt injections, and dangerous code patterns
• Feedback & rating system — agent-nuvira feedback record/list/stats/clear drives self-improvement scoring
• Marketplace unified CLI — agent-nuvira marketplace browse/search/install/info for workflow templates + plugins
• MCP (Model Context Protocol) integration — connect to databases, APIs, and file systems via MCP servers with SSE transport support
• AST-aware code editing — structural analysis engine understands functions, classes, methods across JS/TS/Python/Go/Rust
• Auto error-repair engine — automatic diagnosis and repair of test failures with configurable retry budgets
• Cross-platform dependency installer (Runner) — auto-detects 11 manifest types (npm/pnpm/yarn with lockfile-first priority, pip, bundler, cargo, go, composer, dart pub), installs missing project dependencies on failed commands, and bootstrap-installs missing package managers (npm, pip, bundler, cargo, go, composer, dart, Homebrew) via brew/apt/dnf/yum/winget/choco/rustup — no manual setup required
• A2A (Agent-to-Agent) Protocol — inter-agent communication standard for multi-machine collaboration
• CI/CD headless mode — agent-nuvira ci for automated pipelines with GitHub Actions integration
• npm publishing & one-line install — npx agent-nuvira and npx buff for zero-setup onboarding
• Marketing website — website/ directory with a full landing page, SEO meta tags, and Netlify-ready deployment config
• Branch Automation Hooks (Pillar A4) — agent-nuvira execute "install branch hooks" --auto-branch installs git post-checkout and pre-commit hooks for automated branch workflows; issue-driven branch creation (feat/PROJ-123-description), PR label-triggered updates, file-watch auto-commit with conventional commit messages, and CI failure detection with LLM diagnosis
• Declarative lifecycle hooks (no-code guardrails) — agent-nuvira hooks and the dashboard's Agent Management → Hooks page bind a JSON rule — never a script — to nuvira's four lifecycle seams (before_tool_call / after_tool_call / failed_tool_call / on_session_end), with a fixed native action set: deny, notify, scan-args. Block rm -rf, refuse a force-push, stop a secret-shaped value from ever reaching disk, or log every failed tool call. No third-party code can run, by construction; see docs/HOOKS.md for the cookbook
• A measured quality label, of your own — agent-nuvira rate good|bad (or the dashboard Trace 👍/👎) records whether a turn was what you wanted — the one signal the harness cannot derive, and the only source of the positive class. The label feeds a read-only P(accepted | features) fit shown by model explain; rate --stats/--export/--import/--merge and scripts/fit-acceptance.mjs inspect, ship, join and fit the corpus offline. Nothing routes on it. See docs/ACCEPTANCE.md
• Issue Triage Engine (Pillar A3) — Automated issue classification, prioritization, and labeling across GitHub and GitLab via agent-nuvira execute "triage issues" with LLM-powered analysis
• GitHub PR Review Agent (Pillar A2) — Automatic inline code review on open PRs; reads diffs, runs security/quality verification, and posts inline review comments via GitHub API
• GitLab API Integration (Pillar A1) — Full GitLab agent for merge request management, issue discovery, pipeline monitoring, and code review comments
• Chat Panel DAG Pipeline Visualization (Pillar B6) — Live multi-agent pipeline visualization inline in chat messages for slash commands, showing agent nodes with real-time status updates
• Real-Time Token Streaming in AgentPanel (Pillar B2) — Live typewriter-effect token streaming with blinking cursor and animated progress indicator in the agent progress panel
• Interactive development mode — agent-nuvira execute without a goal launches a guided interactive loop with session save/resume, follow-up suggestions, and failure analysis
• Session persistence — save and resume development sessions across CLI restarts with full history
• Failure analysis — automatic diagnosis of agent failures with specific recovery options per agent type
• Follow-up suggestions — LLM-powered contextual next-step recommendations after goal completion
• Configuration via JSON config file + environment variables
• No server dependency — no telemetry, no subscriptions, no outbound calls to a hosted backend

Quick Start

Prerequisites

• Node.js 20+ and npm
• Git — worktrees, diffs and every change-tracking mode
• TypeScript knowledge for development; none required to use the CLI

The agent also uses software npm cannot install — FFmpeg (video encode), Chromium via Playwright (browser automation and motion frames), Ollama (local models), a narrator for voice-over, Poppler for scanned PDFs. None of them is required to start: the feature that needs one reports itself as skipped, with the reason. The complete list, with the exact command for your OS and the caveats that bite (macOS needs ffmpeg-full, not ffmpeg, or burned captions fall back to a .srt), is in docs/DEPENDENCIES.md.

Check what you already have, and install the rest, at any time:

agent-nuvira doctor          # every tool, its status, and your OS's install command
agent-nuvira doctor --fix    # offers each missing one, installs it, then verifies it

Install

# Install globally
npm install -g agent-nuvira

# Or run it without installing anything globally
npx agent-nuvira chat

One-command setup for new users (recommended)

If you're setting up on a fresh machine (or just don't want to deal with installing Node.js, Git, build tools, etc. by hand), use the platform setup script. Each one checks for the required tools, installs anything missing for you, installs Agent-Nuvira, and then asks whether you want the optional performance upgrades (native FAISS + local embeddings) — with plain-English prompts the whole way.

| OS | Run this | |---|---| | macOS | bash <(curl -fsSL https://raw.githubusercontent.com/imdheerajKube/agent-nuvira/main/scripts/setup/install-macos.sh) | | Linux (Ubuntu/Debian/Fedora/RHEL/Arch/Alpine) | bash <(curl -fsSL https://raw.githubusercontent.com/imdheerajKube/agent-nuvira/main/scripts/setup/install-linux.sh) | | Windows (PowerShell) | Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force; irm https://raw.githubusercontent.com/imdheerajKube/agent-nuvira/main/scripts/setup/install-windows.ps1 | iex |

What each script does:

1. Detects what's missing — Node.js, npm, Git, build tools (and Homebrew on macOS / winget on Windows), and installs them automatically (with your confirmation) using the right installer for your OS.
2. Installs Agent-Nuvira — npm install -g agent-nuvira (with npm 11's install-script security gate handled automatically so native components build).
3. Asks about optional upgrades (recommended, each a yes/no):
   • Native FAISS → faster semantic search / memory recall
   • Local embeddings → free, offline, private embeddings (no cloud call)
   • Runtime tools → FFmpeg, a Chromium bundle for Playwright, a narrator (edge-tts), Poppler for scanned PDFs, Ollama for local models. Each one is asked for separately and skipped cleanly if you decline — see docs/DEPENDENCIES.md for what each unlocks.
4. Verifies the install and prints next steps — including agent-nuvira doctor for the full list of what is (and is not) installed.

The scripts are safe to re-run — they skip tools that are already present. Manual install instructions for every step are below for those who prefer full control.

Native FAISS acceleration (optional, recommended)

Agent-Nuvira includes an optional native FAISS backend for faster semantic retrieval. The runtime prefers this backend automatically when the native addon can build successfully; if that path is unavailable, it falls back to the pure-JS IVF implementation and then the exact JSON backend so your workflow stays reliable.

How the auto-selection works: At load time, createFaissBackend() attempts to import @faiss-node/native and run a 1-vector smoke test. If the native addon exists and passes the smoke test, the backend is faiss-native. If the import fails (not installed, build error, or wrong API), it falls back to the pure-JS IVF-flat ANN (faiss-ivf). If that also fails to initialize, the exact JSON backend (json) is used as the final safety net — semantic search NEVER breaks.

For npm-installed users, the setup is:

# 1) Install the CLI
npm install -g agent-nuvira

# 2) Install the native build prerequisites (macOS example)
brew install faiss libomp openblas

# 3) Rebuild the optional native addon
npm rebuild @faiss-node/native

# 4) Enable the FAISS-style backend (or leave it on 'auto' to prefer it automatically)
#    'auto' (default) — tries native FAISS first, then pure-JS IVF, then JSON
#    'faiss'         — prefer FAISS-style (native or pure-JS IVF); JSON fallback
#    'json'          — exact flat cosine (the original behavior, no FAISS at all)
agent-nuvira config set memory.vectorBackend auto
# or force it explicitly:
# agent-nuvira config set memory.vectorBackend faiss

If you want to confirm the backend in use:

agent-nuvira memory stats                    # Shows active backend
agent-nuvira memory backend                  # Active backend name + why it was chosen
agent-nuvira memory backend --check          # Same + native availability probe + install guidance

Understanding the FAISS tiers

| Tier | Backend name | When it's used | Performance | |---|---|---|---| | 1 — Native FAISS | faiss-native | @faiss-node/native installed AND built successfully | Fastest — real FAISS C++ bindings | | 2 — Pure-JS IVF | faiss-ivf | Native not available; runs TypeScript port of FAISS IndexIVFFlat | Approximate ANN; sub-linear search for large indexes | | 3 — Exact JSON | json | Both FAISS paths unavailable; flat cosine scan | Exact results; O(n) linear scan |

The pure-JS IVF tier uses deterministic k-means++ clustering (nlist=sqrt(n)), inner product of L2-normalized vectors (= cosine similarity), and nprobe probe lists. For small indexes (≤ 512 entries) it runs an exact scan so results are identical to the JSON backend. Filter-aware probe expansion ensures that metadata filters don't miss results.

If the native addon cannot be built on your machine, Agent-Nuvira will continue to work using the pure-JS fallback path.

Local embeddings (optional, recommended)

Semantic search and memory recall use embeddings. Agent-Nuvira's embedder has a 3-tier strategy and always prefers the local tier when it works:

| Tier | Engine | Notes | |---|---|---| | 1 — Local | @huggingface/transformers (onnxruntime-node) | Free, offline, private — Xenova/all-MiniLM-L6-v2 (384-dim). Default when available | | 2 — Python | sentence-transformers via subprocess | Used when Tier 1 is unavailable and Python is present | | 3 — LLM | Any configured inference provider | Last-resort fallback; costs tokens |

With @huggingface/transformers installed and its native binary present, no configuration is needed — local embeddings are used automatically, offline, with zero API cost. The one-command setup scripts above enable this for you. To verify which tier is active, run:

agent-nuvira memory backend --check

Verify

agent-nuvira --help

You should see:

Usage: agent-nuvira [options] [command]

Flexible AI inference CLI tool — local models & cloud APIs

Options:
  -V, --version  output the version number
  -d, --debug    enable debug logging
  -h, --help     display help for command

Commands:
  chat [options] [prompt]       Start an interactive chat session with AI
  edit [options] <file>         Edit a file using AI assistance
  models [options]              List available models from inference providers
  plan [options] [target]       Generate an implementation plan for a codebase task
  execute [options] <goal>      Execute a multi-agent pipeline for a goal
  model                         Switch providers and manage active models
  skill                         List, compile, and run reusable skill scripts
  init [name]                   Scaffold a new project from a template
  history                       Search and manage chat history
  doctor                        Provider health dashboard
  benchmark                     Run model benchmarks
  workflow                      Workflow template marketplace
  federation                    Remote agent federation
  team                          Team collaboration
  dashboard                     Launch web UI dashboard
  dashboard stop                Gracefully stop a running dashboard server
  memory                        Memory compression and stats
  provider                      Provider list and health diagnostics
  security                      Security scan for PII, injections, and dangerous code
  feedback                      Feedback and rating system
  marketplace                   Browse, search, and install plugins and workflows
  mcp                           Model Context Protocol — connect to MCP servers
  plugins                       Manage auto-discovered plugins
  sandbox                       Docker sandbox management
  sdk                           Agent SDK scaffolding
  config                        Manage Buff configuration
  cache                         Manage inference cache

Getting API Keys

Each cloud provider requires an API key. Sign up and get your key from the links below.

🔷 Groq (Fast — LPU Cloud Inference)

Groq runs open-source models at blazing speeds on their custom LPU hardware.

1. Sign up at console.groq.com (free tier available)
2. Go to API Keys → Create API Key
3. Copy your key (starts with gsk_)

export GROQ_API_KEY="gsk_xxxxxxxxxxxxxxxx"

🔶 NVIDIA NIM

NVIDIA NIM provides hosted API access to a wide catalog of models (121+ models).

1. Sign up at build.nvidia.com (free tier with rate limits)
2. Generate an API key from the Get API Key button
3. Copy your key (starts with nvapi-)

export NVIDIA_NIM_API_KEY="nvapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

🔷 Google Gemini

Google's Gemini API has a generous free tier with competitive models.

1. Visit aistudio.google.com/apikey and click Create API Key
2. Select your Google Cloud project or create one
3. Copy your key (starts with AIzaSy)

export GEMINI_API_KEY="AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

🟣 OpenRouter

OpenRouter gives you access to 200+ models from OpenAI, Anthropic, Google, Meta, and more — all through one API.

1. Sign up at openrouter.ai/keys (free credits on sign-up)
2. Click Create Key
3. Copy your key (starts with sk-or-v1-)

export OPENROUTER_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Not every provider needs a key from you. A local runner (Ollama) and an optional local gateway (OmniRoute, which holds the upstream keys itself) are configured without an API key on this side — see Provider Details → OmniRoute.

MCP (Model Context Protocol) Configuration

MCP servers extend your agent's capabilities by connecting to external tools and data sources — databases, APIs, file systems, search engines, code repositories, and more. Agent-Nuvira supports the MCP standard for discovering and invoking tools from connected servers.

Configuration Files

MCP server configs are JSON files placed in '~/.nuvira/mcp/'. Each file defines one server connection. Files are auto-discovered at startup.

mkdir -p ~/.nuvira/mcp

Configuration Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Unique name for this server connection | | transport | "stdio" or "sse" | Yes | Transport protocol (stdio for local subprocess, sse for remote HTTP) | | command | string | For stdio | The command to run (e.g., npx, node, a binary path) | | args | string[] | For stdio | Command arguments | | url | string | For sse | The SSE endpoint URL (e.g., https://example.com/mcp) | | headers | object | Optional | Custom HTTP headers for SSE transport (e.g., Authorization) | | env | object | Optional | Environment variables for the stdio subprocess | | enabled | boolean | Yes | Set to false to temporarily disable the server |

Transport Types

stdio (Local Subprocess)

Spawns a local process (Node.js, Python, Go binary, etc.) and communicates via stdin/stdout using JSON-RPC 2.0.

{
  "name": "filesystem",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
  "enabled": true
}

sse (Remote HTTP)

Connects to a remote HTTP endpoint using Server-Sent Events (SSE). Supports custom headers for authentication.

{
  "name": "exa",
  "transport": "sse",
  "url": "https://websetsmcp.exa.ai/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_EXA_API_KEY"
  },
  "enabled": true
}

Examples

1. Filesystem Server

Read/write files and directories on your local machine.

{
  "name": "filesystem",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/project"],
  "enabled": true
}

agent-nuvira mcp connect filesystem
agent-nuvira mcp call read_file --server filesystem --args '{"path":"/path/to/file.txt"}'

2. GitHub Server

Search repositories, issues, PRs, and code on GitHub. Requires a GitHub Personal Access Token.

Setup:

1. Build the binary: git clone https://github.com/github/github-mcp-server.git && cd github-mcp-server && go build -o github-mcp-server ./cmd/github-mcp-server/
2. Move it to your PATH: mv github-mcp-server /usr/local/bin/
3. Create a GitHub PAT at https://github.com/settings/tokens
4. Add the config below to '~/.nuvira/mcp/github.json'

{
  "name": "github",
  "transport": "stdio",
  "command": "/usr/local/bin/github-mcp-server",
  "args": ["stdio"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_xxxxxxxxxxxx"
  },
  "enabled": true
}

agent-nuvira mcp connect github
agent-nuvira mcp list
# Tools include: search_repositories, search_issues, search_code, search_pull_requests, etc.
agent-nuvira mcp call search_repositories --server github --args '{"query":"react","limit":5}'

3. Exa WebSets Server (SSE with Bearer Auth)

Search and enrich web entities (companies, people, research papers) using Exa's AI-powered search API. Uses SSE transport with Bearer token authentication.

Setup:

1. Get your Exa API key at https://dashboard.exa.ai
2. Add the config below to '~/.nuvira/mcp/exa.json'

{
  "name": "exa",
  "transport": "sse",
  "url": "https://websetsmcp.exa.ai/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_EXA_API_KEY"
  },
  "enabled": true
}

agent-nuvira mcp connect exa
agent-nuvira mcp list
# Tools include: create_webset, create_search, create_enrichment, list_websets, etc.

CLI Commands

| Command | Description | |---------|-------------| | agent-nuvira mcp list | List all discovered MCP servers and their tools | | agent-nuvira mcp connect <name> | Connect to a specific MCP server | | agent-nuvira mcp connect --all | Connect to all discovered MCP servers | | agent-nuvira mcp call <tool> --server <name> --args '{"key":"val"}' | Call a tool on a connected server | | agent-nuvira mcp info <name> | Show detailed information for an MCP server | | agent-nuvira mcp refresh | Re-discover and reconnect to all MCP servers |

Auto-Discovery with the Orchestrator

When you run agent-nuvira execute, the orchestrator automatically:

1. Scans '~/.nuvira/mcp/' for JSON config files
2. Connects to all enabled MCP servers
3. Injects tool descriptions into the agent's context
4. The planner can schedule MCP tool calls as pipeline steps

Finding More MCP Servers

Browse the official MCP server directory at modelcontextprotocol.io/servers. Popular servers include:

• Filesystem — Read/write local files
• GitHub — Repository, issue, PR, and code search
• PostgreSQL — Query databases
• SQLite — Query SQLite databases
• Brave Search — Web search
• Docker — Container management
• Puppeteer — Browser automation
• Slack — Channel and message access

Configuration

Config File

Configuration lives at ~/.nuvira/nuvirarc.json. It is created with sensible defaults on first use.

You can inspect and modify it through the CLI:

# Show full configuration
agent-nuvira config

# Set the default provider
agent-nuvira config set defaultProvider gemini

# Set a provider's model
agent-nuvira config set providers.nim.model "meta/llama-3.1-8b-instruct"

# List all providers with their status
agent-nuvira config list

Default Configuration

{
  "defaultProvider": "local",
  "providers": {
    "nim": {
      "model": "meta/llama-3.1-8b-instruct",
      "temperature": 0.7,
      "maxTokens": 4096
    },
    "gemini": {
      "model": "gemini-2.0-flash-exp",
      "temperature": 0.7,
      "maxTokens": 8192
    },
    "openrouter": {
      "model": "mistralai/mistral-7b-instruct",
      "temperature": 0.7,
      "maxTokens": 4096
    },
    "groq": {
      "model": "llama-3.3-70b-versatile",
      "temperature": 0.7,
      "maxTokens": 4096
    },
    "local": {
      "runner": "ollama",
      "model": "llama2",
      "temperature": 0.7,
      "maxTokens": 4096
    }
  }
}

Environment Variables

API keys can be set via environment variables instead of the config file. They take priority over the config file.

| Variable | Provider | Required? | Get Your Key | |---|---|---|---| | GROQ_API_KEY | Groq | Yes, unless using local | console.groq.com | | NVIDIA_NIM_API_KEY | NVIDIA NIM | Yes, unless using local | build.nvidia.com | | GEMINI_API_KEY | Google Gemini | Yes, unless using local | aistudio.google.com/apikey | | OPENROUTER_API_KEY | OpenRouter | Yes, unless using local | openrouter.ai/keys |

You can place a .env file in the project root or at ~/.nuvira/.env:

# ~/.nuvira/.env
GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
NVIDIA_NIM_API_KEY=nvapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GEMINI_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Modality & Search Providers (bring your own key)

Image generation, web search, TTS, transcription, and vision each use optional backends. A backend is selected from the API keys / endpoints you configure; when nothing is configured the free keyless default runs. Keys may be set as environment variables (shell, <config dir>/.env, or the dashboard Admin panel).

Image generation

generate_image runs the first AVAILABLE backend in this order — a configured API key wins over the free fallback, and modality.image.provider pins one explicitly:

| # | Provider | Env var | Notes | |---|----------|---------|-------| | 1 | Google Gemini / Imagen ("Nano Banana") | GEMINI_API_KEY (or GOOGLE_API_KEY) | modality.image.model (default gemini-2.5-flash-image); an imagen-* id uses the :predict endpoint | | 2 | OpenAI (DALL·E / gpt-image) | OPENAI_API_KEY | default model gpt-image-1 | | 3 | Stability AI | STABILITY_API_KEY | Stable Image Core | | 4 | Local ComfyUI / Stable Diffusion | BUFF_IMAGE_API_URL | POST {prompt,width,height} → image bytes | | 5 | Pollinations.ai | — | free, keyless; always the fallback |

# Use a hosted backend (its API key must be set in the environment)
export GEMINI_API_KEY=AIzaSy...              # or OPENAI_API_KEY / STABILITY_API_KEY
agent-nuvira config set modality.image.provider gemini
agent-nuvira config set modality.image.model gemini-2.5-flash-image

# Or point at a local ComfyUI / Stable Diffusion server
export BUFF_IMAGE_API_URL=http://localhost:7860/sdapi/v1/txt2img

A backend that is configured but fails at request time falls back to the free Pollinations endpoint, so an image request still succeeds.

Web search

web_search runs the first AVAILABLE backend: an explicit tools.toolsets.web.provider (config file), else the first provider whose key is set, else a self-hosted SearXNG, else the keyless DuckDuckGo HTML fallback.

| Provider | Env var | |----------|---------| | Brave Search | BRAVE_SEARCH_API_KEY | | Serper.dev | SERPER_API_KEY | | Tavily | TAVILY_API_KEY | | Google Custom Search | GOOGLE_CSE_API_KEY + GOOGLE_CSE_ID | | SearXNG (self-hosted) | SEARXNG_URL | | DuckDuckGo (keyless fallback) | — |

Other modalities

| Modality | Provider | Requirement | |----------|----------|-------------| | TTS | edge-tts or Piper (local, free) | binary on PATH | | TTS (streaming) | OpenAI / ElevenLabs | OPENAI_API_KEY / ELEVENLABS_API_KEY | | Transcription | whisper.cpp / whisper-cli (local, free) | binary on PATH | | Vision (describe_image) | Ollama llava/llama3.2-vision, or Gemini | local Ollama, or GEMINI_API_KEY | | Video | FAL AI | FAL_KEY |

Motion (animated video from code)

motion_render renders an animated video — an explainer, an animated chart of your own numbers, a kinetic title, a code walkthrough — from code rather than from a video model, so the labels are spelled correctly, your data is your data, and the same source always renders the same file. It needs two binaries and no API key:

| Requirement | Install | |---|---| | chromium (playwright) | npx playwright install chromium | | ffmpeg | brew install ffmpeg (macOS) / sudo apt-get install -y ffmpeg (Debian/Ubuntu) | | narration (optional) | pip install edge-tts, or Piper on PATH | | captions burned into the frames (optional) | an ffmpeg built with libass — macOS brew install ffmpeg-full. Without it the .srt is still written and the render says the burn was skipped |

# A ready-made scene animating your own data (JSON inline, or a CSV/JSON file)
nuvira execute "animate quarterly-revenue.csv as a bar race, 12s, title 'Q3 revenue'"

# Or a hand-written animation: a SEEKABLE page (window.__motion = { seek(tMs) })
nuvira execute "turn README.md into a 20s motion explainer with captions, 9:16"

The animation must be seekable — window.__motion = { seek(tMs) }, or CSS/Web Animations, or a requestAnimationFrame loop, all stepped by the renderer — because frames are captured from the timeline instead of recorded in real time; that is what makes a re-edit (revise the stored render) reproducible. Presets: title-card, bar-race, line-reveal, code-walkthrough. Output goes to .nuvira/artifacts/motion/ and plays inline on the dashboard's Motion page (/motion). A missing chromium or ffmpeg is reported by name with the command that installs it, and narration that could not be synthesized is reported as skipped rather than silently dropped.

From the command line — no model needed

A preset plus your data is a deterministic render, so it does not need a provider, a prompt or token spend:

nuvira motion                 # what has been rendered in this workspace (the default action)
nuvira motion presets         # the four scenes, and which ones need a data file
nuvira motion render --preset bar-race --data quarterly-revenue.csv --aspect 9:16 --duration 12000
nuvira motion render --preset title-card --title "Q3 revenue" --subtitle "by region" --narration "…"
nuvira motion render --html ./my-animation.html --out quarterly --format mp4
nuvira motion doctor          # chromium + ffmpeg check, with this OS's install command
nuvira motion open [id]       # play a render in the system viewer (latest when omitted)

nuvira motion doctor is the answer to "why did nothing render": the renderer needs chromium for frames and ffmpeg to encode, and the command reports whichever is missing rather than failing later.

nuvira doctor lists every optional tool with its status and the command for your OS; nuvira doctor --fix installs the missing ones. The full list is in docs/DEPENDENCIES.md.

Messaging Gateway — Permissions, Sending, and Reading Traces Honestly

This section exists because two different ideas get conflated and it causes real confusion. Read it before you let anyone else message your bot.

1. Two separate permissions (they are NOT the same thing)

| Permission | Where it lives | What it controls | |---|---|---| | Who may trigger the agent | gateway.policies.<platform>.allowedUsers (Agent Hub → Channels → Permissions, or agent-nuvira config gateway allow …) | Who can talk to the bot at all | | Who may send to others | gateway.policies.<platform>.outboundSenders (Agent Hub → Permissions → Send authority, Contacts page, or config gateway send-authority …) | Who can tell the bot to deliver a message to a third party |

A third concept, a contact's approval status, only gates sending to that person — it does not make that person a trusted sender.

Open by default — know this. If you never set outboundSenders, a platform is OPEN: every sender who is allowed to trigger the agent can also direct it to send to anyone. This is the legacy behaviour so nothing silently breaks. To restrict it, set an explicit list:

# Only YOU may direct the bot to message other people on WhatsApp
agent-nuvira config gateway send-authority add whatsapp +919876543210
# The list is now RESTRICTED to that number. Everyone else is refused.

agent-nuvira config gateway send-authority list whatsapp      # show current state
agent-nuvira config gateway send-authority remove whatsapp +91… # drop one
agent-nuvira config gateway send-authority reset whatsapp      # back to OPEN
agent-nuvira config gateway send-authority require-target whatsapp on  # recipients must be approved contacts

Or do the same visually: Dashboard → Contacts → “🔐 Send authority” (a platform card per channel, with add/remove, an open/restricted badge, and “Require approved recipients”), or Agent Hub → Channels → Permissions → Send authority.

The list follows the same rules as allowedUsers: specific ids restrict it, an empty list means nobody, and the Allow-All wildcard means anyone. A sender can always reply inside their own conversation; send authority only governs messages to other targets.

A CLI/dashboard chat turn (you typing at the keyboard) is trusted and never blocked by this gate — it only applies to remote senders arriving through a messaging platform.

2. Who appears where (Contacts vs Agent Hub)

• Contacts tab — the directory of people the bot can message. Telegram users are auto-registered here on their first message with status ⏳ pending until you approve them. WhatsApp senders are not auto-registered.
• Agent Hub → Permissions → “Send authority” — who may command sends to others.
• Tick Require approved recipients if you want every outbound target to be an approved contact (an explicit platform:+number target is otherwise allowed).

What “pending” means — and what it does not

| Label | Where | Meaning | |---|---|---| | ⏳ pending | Contacts tab | A real approval state — the person messaged the bot and is awaiting your decision | | · unsaved | Agent Hub → Permissions | Not a state at all — a local edit you have not saved yet. Reloading the page discards it. Press 💾 Save permissions before leaving. |

These used to share the word “pending”, which made unsaved edits look like they had vanished. Agent Hub now says unsaved so the two can never be confused.

3. Reading traces honestly

A trace's success flag means “a reply was generated” — it does not mean an action happened. A model can write {"tool":"gateway_send", …} as plain text (the loop now recovers that into a real call) or skip tools entirely and simply say “I have sent it”.

Every chat trace therefore also carries an outcome badge, visible in Dashboard → Traces:

| Badge | Meaning | |---|---| | 💬 answered — no action taken | A text reply only; no tool ran | | 🔧 acted — N tool(s) | One or more tools actually executed | | ✅ action performed — message sent | gateway_send ran and reported success | | ⚠️ unverified claim | The answer asserted a delivery that no tool performed — treat it as NOT done | | ❌ / ⏹ | Generation failed / you cancelled the turn |

If a gateway answer claims a send that never happened, the agent now appends a correction (“I could not confirm that message was actually sent…”) instead of leaving a false confirmation standing.

To be sure a message really went out: look for the ✅ outcome badge on the trace, or a ✅ sent to … line in the tool result — never trust the model's prose alone.

CLI Commands

agent-nuvira models — Model Discovery (New in v1.1.0)

List available models from any configured provider. Query each provider's model catalog without leaving the terminal.

# List models from the default provider
agent-nuvira models

# List models from a specific provider
agent-nuvira models --provider nim
agent-nuvira models --provider groq
agent-nuvira models --provider openrouter

# Search for models by keyword
agent-nuvira models --search deepseek
agent-nuvira models --search llama

# Show all providers (even unconfigured ones)
agent-nuvira models --all

Examples:

# See all models on Groq
agent-nuvira models --provider groq

# Find DeepSeek models across all configured providers
agent-nuvira models --search deepseek

# Output:
# ════════════════════════════════════════════
# 📋 Available Models (3)
# ════════════════════════════════════════════
#
# Groq:
# ----------------------------------------
#   deepseek-ai/deepseek-v4-pro [deepseek]
#   deepseek-ai/deepseek-v4-flash [deepseek]
#   deepseek-ai/deepseek-coder-6.7b-instruct [deepseek]
#
# ════════════════════════════════════════════

Use a discovered model immediately:

agent-nuvira chat --provider groq --model deepseek-ai/deepseek-v4-flash
agent-nuvira edit src/server.ts --provider openrouter --model openai/gpt-4o

Model Availability Registry — the registry is the sub-ms FAISS/JSON store routing reads on every pick. models status shows verified / unavailable / quota-parked models; --verbose adds the two things routing learned from real usage: which providers are registry-blocked (skipped predictively — with the learned reason for each blocked model) and the per-action telemetry (which action verified/killed which provider × model):

# Show the registry (verified / unavailable / quota-parked)
agent-nuvira models status

# Same + registry-blocked providers (why routing skips them) + per-action
# "learned from real usage" telemetry (chat/execute/plan/edit verified/killed)
agent-nuvira models status --verbose

# The dashboard's Models panel charts the same feed per action — scrub across
# days (drag / click / range slider / ▶ play) to see each day's exact
# verified vs killed provider × model chips
agent-nuvira dashboard

# Probe + spot-check now (proactive health, not reactive)
agent-nuvira models refresh
# Background maintenance daemon
agent-nuvira models watch

# Escape hatch: manually release a registry-blocked provider (demotes
# unavailable → unverified, clears quota parks + ledger cooldown, then
# re-probes the live API to re-learn the truth — honest stillBlocked output)
agent-nuvira models unblock gemini
# Same, but skip the live re-probe (demote + un-park only)
agent-nuvira models unblock nim --no-spot-check
# Machine-readable for CI
agent-nuvira models unblock groq --json

agent-nuvira chat — Interactive Chat

Start a terminal-based chat session with any provider.

# Interactive mode (default provider)
agent-nuvira chat

# One-shot prompt
agent-nuvira chat "what is the difference between TCP and UDP?"

# Specify provider and model
agent-nuvira chat --provider gemini --model gemini-2.0-flash-exp

# Include a file as context
agent-nuvira chat --file ./src/main.ts "explain this code"

# Disable caching
agent-nuvira chat --no-cache

Interactive commands within a chat session:

| Command | Action | |---|---| | /exit or /quit | End the session | | /clear | Clear conversation history | | /info | Show current provider details | | /help | Show available commands |

agent-nuvira edit — AI-Assisted File Editing

Edit a file using natural language instructions. The AI reads the file, applies your instruction, and writes the result back.

# Edit with default instruction ("Review and improve this code")
agent-nuvira edit src/server.ts

# Provide a specific instruction
agent-nuvira edit src/server.ts --instruction "add rate limiting middleware"

# Use a specific provider
agent-nuvira edit src/server.ts --provider openrouter --model openai/gpt-4o

# Preview changes without modifying the file
agent-nuvira edit src/server.ts --instruction "add error handling" --dry-run

agent-nuvira plan — Implementation Plans

Analyze a directory or file and generate a structured implementation plan.

# Plan for the current directory
agent-nuvira plan

# Plan for a specific target with a task description
agent-nuvira plan ./src --task "add user authentication with JWT"

# Use a cloud provider for complex planning
agent-nuvira plan . --task "refactor to microservices" --provider gemini

# Verbose mode shows the full context sent to the model
agent-nuvira plan -v

The plan includes:

1. Summary — high-level overview
2. Files to Modify — specific files and changes
3. Architecture Changes — structural modifications
4. Implementation Steps — ordered guide
5. Potential Risks — edge cases and breaking changes
6. Testing Strategy — verification approach

agent-nuvira config — Configuration Management

# Show full config
agent-nuvira config

# Set a value
agent-nuvira config set defaultProvider openrouter

# Get a specific value
agent-nuvira config get providers.nim.model

# List all providers with their status
agent-nuvira config list

# Initialize (show defaults)
agent-nuvira config init

agent-nuvira cache — Cache Management

Inference responses are cached in a local SQLite database (~/.nuvira/cache.db) with a default TTL of 1 hour.

# Show cache statistics
agent-nuvira cache stats

# Clear all cached responses
agent-nuvira cache clear

agent-nuvira model — Context-Preserving Model Switching

Switch inference providers and models on the fly without losing conversation history, agent state, or session continuity. The active model persists across CLI restarts.

# Show current active model + prompt to switch
agent-nuvira model

# List all providers with their status
agent-nuvira model list

# Interactive categorized model picker
# (choose "Browse by provider" to drill into ONE provider's full model list,
#  e.g. OpenRouter's 100+ models, and pick a specific one)
agent-nuvira model switch

# Switch to a provider with its default model
agent-nuvira model switch groq

# Switch to a specific provider/model pair
agent-nuvira model switch groq/llama-3.3-70b-versatile

# Auto routing — agent decides the best provider/model per task
# (fast cheap models for simple work, stronger models for complex tasks,
#  local models for private tasks)
agent-nuvira model switch auto

# Show detailed active configuration
agent-nuvira model info

# Get model routing recommendations
agent-nuvira model recommend

# Explain why Auto routing picks a model for a task (transparency/debugging)
agent-nuvira model explain "implement JWT auth with refresh tokens"
agent-nuvira model explain                  # walks 5 sample complexities
agent-nuvira model explain --agent writer "your task"
agent-nuvira model explain "your task" --json  # machine-readable (scripting/CI)

# Walk through a narrated decision (the 🎯 fit / 📏 measured / ⏳ ctx chips)
# → see MODELS_EXPLAIN_DEMO.md for a full annotated example

# Benchmark the exact provider/model pairs the Auto router picks
agent-nuvira benchmark run --routing

# Evaluate the Auto router's picks end-to-end (full multi-agent pipeline + hidden tests)
agent-nuvira eval run --routing

# Every explain snapshot + routing-mode pick is recorded to the dashboard's audit trail
# (Routing panel → 'Audit Trail — routing decision timeline')

# Quick health check for the active provider
agent-nuvira model health

Priority chain: CLI --provider/--model flags → agent-nuvira model switch active state → default config file — the most specific wins.

Learning Router — Thompson-sampling bandit + hard constraints (v1.51.0 Enhanced)

Auto routing can learn from real outcomes (ruflo-inspired model-router math, generalized to all providers). The routing engine scores providers across 5 weighted dimensions (reasoning, speed, cost, privacy, reliability) with per-complexity weight matrices for all 5 levels.

# Enable bandit learning — each provider's score is multiplied by a Beta draw
# learned per complexity bucket from actual task successes/failures
agent-nuvira config set routing.bandit true

# Hard per-call budget (USD) — providers whose typical call exceeds this are
# eliminated, not just scored lower
agent-nuvira config set routing.maxCostUsd 0.005

# Minimum capability floors for auto-routed tasks (0–1)
agent-nuvira config set routing.minSpeed 0.5
agent-nuvira config set routing.minReasoning 0.6

# Weak-model consent (agentic/software tasks). ASK-FIRST by default: if a
# software task can only run on a weak model, the agent asks ONCE for the
# session (approve the weak model, or wait for a strong one) — never a silent
# downgrade. This value governs only the surfaces that CANNOT ask (gateway
# channels, headless/CI):
#   ask (default) — never silently use a weak model: fail over or abort honestly
#   auto-allow    — proceed on the weak model (records the verdict)
#   deny          — never use a weak model
agent-nuvira config set routing.weakModelPolicy ask

# Outbound PROMPT budget (chars). When the assembled prompt exceeds maxTotal,
# optional context is dropped lowest-value-first (skill hint → recall → …); the
# identity/tool contract is never trimmed. Set on the config file:
#   "routing": { "promptBudget": { "warnTotal": 40000, "maxTotal": 48000 } }

Plan gate (E2). A workspace-directing turn that tries to edit FILES before it has declared a plan is stopped once: the first file mutation is refused and the model is told to call plan_todo first. Terminal commands (builds, tests) are nudged but never blocked — a command is a step a plan is meant to reach, not a change to gate. The block is bounded: the second attempt runs even without a plan, so it guides rather than walls. A turn that declares a plan in the same step is never blocked.

Turn report (E). Every turn derives a plan → track → verify rep