# ---
name: agent-nuvira
short_description: "Flexible AI inference CLI with multi-agent swarm, routing, and persistent memory"
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 <imdheeraj@gmail.com>**

**Multi-agent AI coding assistant** with a **visual dashboard** and **powerful CLI**. 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, and ship code — learning from every run.

```bash
# Quick examples
agent-nuvira chat "explain recursion in Rust"
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
```

---

## 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 **22 providers** and **300+ discovered models** 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
- **🧠 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
- **🎨 Adaptive Modality Routing** — intelligent routing for image/audio/video with failover across backends. **Data-driven providers** — add new providers via config, no code changes required. Image: ComfyUI (free) → Pollinations (free) → DALL-E (paid) → Stability (paid). TTS: OpenAI TTS (paid) → ElevenLabs (paid). Video: FAL (paid) → Runway (paid). Transcription: OpenAI Whisper (paid). Users can add custom providers:
  ```bash
  # Add Replicate for image generation
  nuvira config set modality.image.replicate.apiKey=r8_xxxxx
  nuvira config set modality.image.replicate.baseUrl=https://api.replicate.com/v1
  nuvira config set modality.image.replicate.models="stability-ai/sdxl"
  
  # Add Azure TTS
  nuvira config set modality.tts.azure.apiKey=xxxxx
  nuvira config set modality.tts.azure.region=eastus
  ```
- **🖥️ 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](DESIGN_DECISIONS.md). For benchmark results, see [docs/benchmarks/INDEX.md](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`](MODELS_EXPLAIN_DEMO.md). Benchmark the router's exact picks with `agent-nuvira benchmark --routing`, validate them end-to-end with `agent-nuvira eval --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; 9 commands, inline code suggestions, diff viewer, agent progress panel
- **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 custom agents with scaffolding CLI
- **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
- **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
- **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**
- **TypeScript** knowledge for development; none required to use the CLI

### Install

```bash
# Install globally
npm install -g agent-nuvira

# Or clone and build from source
git clone https://github.com/imdheerajKube/agent-nuvira.git buff
cd agent-nuvira
npm install
npm run build
npm link
```

### 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)
4. **Verifies** the install and prints next steps.

> 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:

```bash
# 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:

```bash
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:

```bash
agent-nuvira memory backend --check
```

### Verify

```bash
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](https://console.groq.com)** (free tier available)
2. Go to **API Keys** → **Create API Key**
3. Copy your key (starts with `gsk_`)

```bash
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](https://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-`)

```bash
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](https://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`)

```bash
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](https://openrouter.ai/keys)** (free credits on sign-up)
2. Click **Create Key**
3. Copy your key (starts with `sk-or-v1-`)

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

## 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.

```bash
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.

```json
{
  "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.

```json
{
  "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.

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

```bash
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'

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

```bash
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'

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

```bash
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](https://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:

```bash
# 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

```json
{
  "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](https://console.groq.com) |
| `NVIDIA_NIM_API_KEY` | NVIDIA NIM | Yes, unless using local | [build.nvidia.com](https://build.nvidia.com) |
| `GEMINI_API_KEY` | Google Gemini | Yes, unless using local | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) |
| `OPENROUTER_API_KEY` | OpenRouter | Yes, unless using local | [openrouter.ai/keys](https://openrouter.ai/keys) |

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

```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 Providers (Image/Audio/Video)

Agent-Nuvira routes image generation, TTS, video, and transcription to the best available backend. Built-in providers are automatically detected from environment variables. You can add custom providers via config:

```bash
# Add Replicate for image generation
agent-nuvira config set modality.image.replicate.apiKey=r8_xxxxx
agent-nuvira config set modality.image.replicate.baseUrl=https://api.replicate.com/v1
agent-nuvira config set modality.image.replicate.models='["stability-ai/sdxl", "black-forest-labs/flux-schnell"]'
agent-nuvira config set modality.image.replicate.costPerUnit=0.003
agent-nuvira config set modality.image.replicate.quality=0.9

# Add Azure TTS
agent-nuvira config set modality.tts.azure.apiKey=xxxxx
agent-nuvira config set modality.tts.azure.baseUrl=https://eastus.tts.speech.microsoft.com
agent-nuvira config set modality.tts.azure.endpoint='/cognitiveservices/v1'
agent-nuvira config set modality.tts.azure.models='["en-US-AriaNeural", "en-US-JennyNeural"]'

# Add custom video provider
agent-nuvira config set modality.video.myprovider.apiKey=xxxxx
agent-nuvira config set modality.video.myprovider.baseUrl=https://api.myprovider.com/v1
agent-nuvira config set modality.video.myprovider.models='["model-1"]'
```

**Built-in providers (auto-detected from env vars):**

| Modality | Provider | Env Var | Cost | Quality |
|----------|----------|---------|------|----------|
| Image | Pollinations.ai | None (free) | Free | 0.7 |
| Image | DALL-E 3 | `OPENAI_API_KEY` | $0.04/image | 0.95 |
| Image | Stability AI | `STABILITY_API_KEY` | $0.002/gen | 0.85 |
| Image | ComfyUI (local) | `BUFF_IMAGE_API_URL` | Free | 0.9 |
| TTS | OpenAI TTS | `OPENAI_API_KEY` | $15/1M chars | 0.9 |
| TTS | ElevenLabs | `ELEVENLABS_API_KEY` | $30/1M chars | 0.95 |
| Video | FAL AI | `FAL_KEY` | $0.05/video | 0.85 |
| Video | Runway ML | `RUNWAY_API_KEY` | $0.10/video | 0.95 |
| Transcription | OpenAI Whisper | `OPENAI_API_KEY` | $0.006/min | 0.95 |

**How routing works:**

1. Score all available providers by: cost (35%), quality (30%), speed (20%), availability (15%)
2. Try best provider first
3. On failure, automatically failover to next best provider
4. Continue until success or all providers exhausted

---

## 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.

```bash
# 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:**

```bash
# 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:

```bash
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):

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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

```bash
# 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.

```bash
# 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.

```bash
# 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 --routing

# Evaluate the Auto router's picks end-to-end (full multi-agent pipeline + hidden tests)
agent-nuvira eval --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.

```bash
# 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
```

#### How the routing engine works (v1.51.0)

**5 scoring dimensions:** Every provider has a static capability profile (0–1) for reasoning, speed, cost, privacy, reliability. The cost dimension is computed from **real per-1K-token pricing** (free tiers = $0) — configurable via `agent-nuvira config set pricing.<provider>.inputPer1K`.

**5 complexity levels:** The task description is analyzed for keywords to determine complexity (trivial → critical). Each level has a distinct weight matrix that shifts dominance:
- **Trivial/simple:** cost + speed dominate (fast small model)
- **Moderate:** balanced
- **Complex/critical:** reasoning + reliability dominate (deep reasoning with larger model)

**4 preference modes:** `balanced`, `performance-first`, `cost-first`, `privacy-first` — each applies additive weight adjustments that shift the routing decision predictably.

**1. Thompson-sampling bandit** — Each provider keeps a **Beta(α, β) prior per complexity bucket** so learning is task-type-local. Final score = `deterministicScore × θ` where `θ ~ Beta(α, β)`. Cold start `Beta(1,1)` behaves like the plain heuristic router until outcomes accumulate. The orchestrator **records every auto-routed task's outcome** (success/failure) into the bandit. Success rewards are **cost-adjusted** — a cheap provider's success is worth the most. State persists to `~/.nuvira/memory/router-bandit.json`.

**2. Uncertainty-driven escalation** — When the bandit's winner has no learned data (α+β < default 8 samples), routing escalates to the next-ranked provider that HAS learned data with a ≥55% win-rate floor. This prevents a cold-start winner from committing to a coin flip.

**3. Per-modelId learning** — Both provider-level and model-level Beta priors track which concrete model won (e.g., `llama-3.3-70b-versatile` ≠ `openai/gpt-oss-20b` on the same provider). Cold start keeps the configured pin; learned models prefer the best Thompson-sampled one.

**4. Promotion gate A/B** — Every auto-routed task records both the deterministic heuristic pick and the bandit pick for the same task. The `agent-nuvira model bandit` command evaluates 3 criteria (quality improvement >2%, cost regression ≤1%, p95 latency regression ≤5%) before promoting the bandit over the heuristic.

**5. Routing rules** — Regex/string task-pattern rules force a specific provider/model before scoring (first match wins). Rules also note the forced provider for correct bandit outcome attribution.

**6. Hard constraints** — `routing.maxCostUsd`, `routing.minSpeed`, `routing.minReasoning` eliminate violating providers with graceful fallback when constraints would remove everything.

**7. Credential-aware filtering** — Auto routing never picks a provider without configured credentials. The ModelRegistry fast path verifies usable models; explicit `allowedProviders` always win.

**8. Quota-ledger integration** — Exhausted providers sink below healthy ones like circuit-breaker cooldown, only picked when every candidate is parked.

**9. Runtime stats blending** — Benchmark quality scores (30%) + per-agent best-model stats adjust provider capability scores in real time.

**10. Verification-aware escalation** — Verification-heavy tasks (deploy, security audit) boost reasoning+reliability weights and reorder candidates so the strongest provider for verification is tried first.

**11. Free/local-first gate** — `routing.allowPaid: false` keeps paid providers out of trivial/simple/moderate tasks; complex/critical tasks may still use high-capacity models.

Inspect and manage the bandit from the CLI:

```bash
# Show the bandit state (α/β priors + expected win % per provider × complexity bucket)
agent-nuvira model bandit

# Machine-readable snapshot (priors, expected win rates, learning history)
agent-nuvira model bandit --json

# Reset all Beta priors back to Beta(1,1)
agent-nuvira model bandit reset
```

The dashboard's 🤖 **Routing** panel shows the same bandit live — an α/β heatmap plus a learning-history timeline (enable `routing.bandit` and run auto-routed tasks to populate it). It also renders a live **🎖️ Promotion Gate** card: an A/B verdict on whether the bandit is actually **better than the deterministic heuristic**, judged on real trajectories (`router-promotion.jsonl`) — quality must improve >2% while cost and latency don't regress.

**Routing rules** — force a specific provider/model for task patterns (regex/string, evaluated before scoring, first match wins):

```jsonc
// ~/.nuvira/nuvirarc.json
{
  "routing": {
    "bandit": true,
    "maxCostUsd": 0.005,
    "rules": [
      { "name": "marketing → groq", "pattern": "email|sales|copy", "provider": "groq" },
      { "name": "refactor → local", "pattern": "refactor", "provider": "local" }
    ]
  }
}
```

Every decision records a `routedBy` source (`heuristic` | `rule` | `bandit`) in the dashboard's routing audit trail so you can see exactly how each pick was produced. The `routedBy` field is also exposed in the `AutoRouteResult` for programmatic access.

#### Auto-mode session failover — providers that die mid-session get swapped automatically

A provider can look healthy at pick time and still fail mid-session: Gemini's
`token limit exceeded`, OpenRouter 401s, quota exhaustion, or a rate limit on a
free tier. In Auto mode, `chat` now **remembers failed providers for the session**
and routes around them instead of getting stuck:

| Failure kind | Handling |
|---|---|
| **Auth** (expired/invalid key, 401) | Provider excluded from Auto routing for the **whole session** — re-picked routes skip it entirely |
| **Rate limit** (429, quota exceeded, `token limit`, `insufficient_quota`, `resource has been exhausted`) | Provider parked for a **120s cooldown** (aligned with the circuit breaker), then automatically re-admitted |
| **5xx / network** | Flows through the shared **circuit breaker** (3 failures in 60s → 120s cooldown); never session-excluded |

On failure the chat loop prints `⚠️ <provider> failed — automatically switching to
<provider> (<model>)` and transparently re-routes to the next-best candidate.
In-cooldown providers are deprioritized by router scoring (via circuit-breaker
state), the final fallback always prefers a provider that hasn't failed this
session, and the failover path is crash-proof — a throwing re-route can't kill
the interactive loop. Works for both streaming and non-streaming responses.

#### Deterministic Tier-0 routing — mechanical edits without an LLM

Simple mechanical edits never touch an LLM (ruflo's `enhanced-model-router` Tier-1 codemod idea, built on agent-nuvira's editing engine):

| Goal pattern | Deterministic transform | Cost |
|---|---|---|
| `remove all console.log statements` / `clean up debug logging` | Strips standalone `console.*` lines | **$0 · <1ms** |
| `rename foo to bar` (symbol present in context) | Word-boundary rename across all references | **$0 · <1ms** |
| `remove duplicate imports` | Deduplicates same-module import lines | **$0 · <1ms** |

- Runs **before** the LLM in the edit pipeline; every transformed file is **AST-validated** first, so tier-0 never emits broken code.
- If the goal isn't mechanical (or validation fails), the pipeline **falls through to the LLM** unchanged.
- Tier-0 results flow through the same safe-apply pipeline (dry-run, sandbox, review bundles) and emit `edit:written` events tagged `via: tier0`.
- Disable per call with `useTier0: false` in the EditModule API.

#### Central quota ledger — free/local-first routing with reset windows

Every Auto-routed call is write-through recorded into a **central quota ledger** (tokens/requests per provider × model). The ledger powers four things:

1. **Calendar-aware reset windows** — daily/hourly free-tier limits with automatic re-enable exactly when the window rolls (no arbitrary timers).
2. **Predictive parking** — a provider that exhausts its window is **parked** and sinks below healthy candidates **before** the next call, not after a reactive failure.
3. **Free/local-first gate** — `routing.allowPaid: false` keeps paid providers out of trivial/simple/moderate tasks; complex/critical tasks may still use paid high-capacity models.
4. **Cost transparency** — `agent-nuvira model quota` shows free vs paid tokens and an **estimated $ saved** figure (what the free-tier usage would have cost at a typical paid rate).

```bash
# Set per-provider quota limits (requests per reset window)
agent-nuvira config set routing.quota.gemini.requestsPerWindow 1500
agent-nuvira config set routing.quota.groq.requestsPerWindow 14400
agent-nuvira config set routing.quota.groq.tokensPerWindow 1000000
agent-nuvira config set routing.quota.groq.windowMs 86400000   # 24h reset window

# Free/local-only unless complexity demands paid (assessment-gap gate)
agent-nuvira config set routing.allowPaid false

# Inspect the ledger (tokens/requests per provider × model, resets in, parked state)
# and the cost summary (free vs paid tokens + estimated $ saved)
agent-nuvira model quota

# Same data machine-readable (costSummary field) for scripting/CI
agent-nuvira model quota --json

# Clear all ledger entries
agent-nuvira model quota reset
```

The dashboard's 📒 **Quota Ledger** card shows the same data live — per-entry status plus a free/local-first cost split (free tokens = savings, paid tokens = actual spend) with an estimated $ saved badge.

**Failover timeline (transparency: when failover occurred).** Every park, window-reset re-enable, manual release, and mid-session failover is appended to `~/.nuvira/memory/quota-events.jsonl` (capped at 200). The dashboard's Quota card renders it as a **Failover Timeline**, and `agent-nuvira model quota` prints the last 20 events:

```bash
agent-nuvira model quota
#   ── Failover Timeline (last 20) ──
#    ⚡ failover    gemini        (rate-limit)  8/2/2026, 5:10:02 PM
#    ⏸ parked      gemini        (rate-limit)  8/2/2026, 5:10:02 PM
#    🔁 re-enabled  groq          (window reset) 8/2/2026, 5:09:00 PM
```

The timeline is also **live**: the dashboard watches `quota-events.jsonl` /
`quota-ledger.json` on disk and pushes a `quota` SSE event the moment a failover
or park lands — so the card updates in real time, no page refresh or 10s wait.
(The watcher arms while a dashboard is connected and disarms when the last one
disconnects.) To keep it armed from server start — so the timeline is already
current the moment a dashboard connects, even after the server sat idle between
viewing sessions — enable always-on mode:

```bash
# Keep the quota watcher armed from server start (never disarms on client count)
agent-nuvira config set routing.alwaysWatchQuota true
```

Always-on trades a tiny idle fs watch for instant-up-to-date quota state.

#### Vector retrieval — token-efficient context (saves tokens, complements the quota ledger)

Agent-Nuvira can **vectorize large context** with a local embedding model + the
pure-JS vector store — no FAISS/native deps, no server. The retrieval layer
saves tokens (stretching free quotas), while the quota ledger manages limits:

| Piece | What it does |
|---|---|
| **Chunking** | Large files split into ~512-token chunks (64-token overlap, paragraph-aware) |
| **Embedding** | `bge-small-en-v1.5` (384-dim) via @huggingface/transformers — local, free, offline, cached |
| **Vector store** | Pure-JS cosine-similarity index in `~/.nuvira/memory/vectors-repo.json` (honors `BUFF_MEMORY_DIR`), isolated from memory/history vectors |
| **Retrieval** | Goal/subtask embedded → top-k chunks (default 5) → reduced context |
| **Router policy** | Context ≤ threshold (12k tokens) → **direct call, zero overhead**; larger → embed + retrieve; any failure → **failover to full context** (never breaks the LLM call) |
| **Transparency** | `🧠 Retrieved 5 chunks — reduced context 20k → 3k tokens` + `agent-nuvira retrieval stats` + dashboard Retrieval card |

```bash
# Pre-index a repo so Auto runs are instant (first run downloads the ~130MB
# model once, then cached locally)
agent-nuvira retrieval index .

# Semantic search over the indexed repo
agent-nuvira retrieval query "how does login with JWT work?"

# Token-savings transparency
agent-nuvira retrieval stats

# Wipe index + stats
agent-nuvira retrieval clear
```

Where retrieval applies (honest split):
- **`agent-nuvira chat --file <large-file>`** — the file is chunked, embedded, and
  reduced to the top-k relevant chunks before the LLM call (big token savings).
- **`agent-nuvira execute` pipelines** — after the context-gatherer collects files, the
  orchestrator indexes them and produces a **semantic file ranking** for the
  writer (relevance over size when selecting which files fit the token budget),
  and records the retrieval into the token-savings stats.

**Config** (`routing.retrieval`):

```bash
# Master switch (default true)
agent-nuvira config set routing.retrieval.enabled false

# Top-k chunks (default 5), chunk size (default 512 tokens), vectorize threshold (default 12000 tokens)
agent-nuvira config set routing.retrieval.topK 8
agent-nuvira config set routing.retrieval.chunkTokens 640
agent-nuvira config set routing.retrieval.thresholdTokens 20000
```

**Vector search backend** (`memory.vectorBackend`):

```bash
# Show which backend is active
agent-nuvira memory stats        # ... Backend: faiss-ivf (FAISS-style IVF-flat ANN)

# Choose the backend explicitly
agent-nuvira config set memory.vectorBackend auto   # default: native FAISS when built, else pure-JS IVF
agent-nuvira config set memory.vectorBackend faiss  # prefer FAISS-style; JSON fallback on native failure
agent-nuvira config set memory.vectorBackend json   # exact flat cosine (the original behavior)
```

- **`auto` (default)** — uses the **FAISS-style backend**: real `@faiss-node/native`
  bindings when the user has installed AND built them (smoke-tested at load),
  otherwise a **pure-JS IVF-flat ANN** — a faithful TypeScript port of FAISS's
  `IndexIVFFlat` (nlist inverted lists via deterministic k-means++, nprobe
  probe lists, cosine = inner product of L2-normalized vectors). Small indexes
  (≤ 512 entries) use an EXACT scan so results are identical to the JSON
  backend; large indexes get sub-linear approximate search with filter-aware
  probe expansion. Any native failure falls back gracefully — semantic search
  never breaks.
- **Why native FAISS is not the hard default (decision):** `@faiss-node/native`
  ships no prebuilt binaries and requires compiling FAISS from source
  (cmake + OpenBLAS + libomp) at install time — verified to fail on a stock
  macOS dev box. Making it a required dependency would break zero-setup
  `npx agent-nuvira`. The pure-JS IVF-flat backend provides the same
  FAISS-style approximate-NN behavior with zero native deps; users who build
  the native package automatically get the real thing.

**Roadmap (Step 6 — future enhancements):**
1. **Hybrid retrieval** — combine embeddings with keyword/BM25 scoring for
   exact-match-sensitive queries.
2. **Embedding caching** — the embedder already caches in-memory; a persistent
   on-disk embedding cache would skip re-embedding unchanged chunks across
   sessions.
3. **Multi-vector routing** — different embedding models for code vs natural
   language (the store already supports namespaced indexes, so this is a
   config-level addition).

**Opt-in failover confirmation.** By default Auto mode fails over silently
(never get stuck). If you'd rather approve each mid-session swap, enable:

```bash
# Ask before Auto mode switches providers mid-session
agent-nuvira config set routing.promptOnFailover true
```

With this on, a failed provider shows the next-ranked candidate and lets you
choose "switch (recommended)" or "pick a provider myself" — so every swap is
an informed decision, not a silent surprise.

This also applies to **single-shot Auto prompts** (`agent-nuvira chat "ask something"`
with `-m auto`): before Auto mode silently hops to the next candidate, the CLI
asks; picking "manual" surfaces the original provider error instead of
switching behind your back.

#### Checkpoint / resume — crash-proof multi-agent pipelines

Long `agent-nuvira execute` pipelines can be killed by a crash, quota exhaustion, or a token expiry mid-run. Checkpoints serialize the pipeline state so work is never lost:

```bash
# Save a resume-able checkpoint after every task batch (in ~/.nuvira/memory/checkpoints/)
agent-nuvira execute "build the API" --checkpoint

# Resume the latest checkpoint for this goal + cwd (skips completed steps + the planner)
agent-nuvira execute "build the API" --resume

# Resume a specific checkpoint
agent-nuvira execute "build the API" --resume cp-3f9a2c1d0b7e

# List saved checkpoints (goal, progress %, saved-at)
agent-nuvira execute --checkpoint-list
```

How it works:
- After **every task batch** the orchestrator saves a snapshot of the task plan (per-step statuses), artifacts, file changes, and metadata.
- `--resume` rehydrates the vault, **skips completed steps and the planner**, and continues from the first pending step — on whatever provider/model is now available.
- `--checkpoint` alone always starts **fresh** (it never silently resumes a stale checkpoint); only an explicit `--resume` loads.
- State persists across sessions, so a provider that died mid-pipeline can resume on the next-best provider with zero rework (assessment item #6: continuity across models).

---

### `agent-nuvira execute --auto-branch` — Branch Automation

Automate your entire git workflow with trigger-based hooks. Install once, then let the agent handle branch creation, commits, and PR updates automatically.

```bash
# Step 1: Install branch automation hooks
agent-nuvira execute "install branch hooks" --auto-branch

# Step 2: Check automation status
agent-nuvira execute "check branch status" --auto-branch

# Step 3: Auto-create a branch from an issue
agent-nuvira execute "auto-create branch from issue PROJ-123" --auto-branch

# Step 4: Auto-commit changes with a conventional message
agent-nuvira execute "auto-commit changes" --auto-branch

# Step 5: Start file-watch mode (auto-commits on file changes)
agent-nuvira execute "start file watch" --auto-branch

# Step 6: Diagnose CI failures
agent-nuvira execute "check CI for PR #42" --auto-branch
```

**Trigger Sources:**

| Trigger | Action | Description |
|---------|--------|-------------|
| **Issue → Branch** | `feat/PROJ-123-description` | Auto-creates branches with conventional naming when issues are assigned |
| **PR Label → Update** | `git push origin <branch>` | Commits and pushes changes when labels like `wip` or `needs-work` are detected |
| **File Watch → Commit** | `git commit -m "feat(scope): ..."` | Background polling detects file changes and auto-commits with conventional messages |
| **CI Status → Fix** | LLM diagnosis + fix plan | Analyzes CI failures from recent commits and suggests targeted fixes |

**Conventional Commit Format:**

```
<type>(<scope>): <description>

Types: feat, fix, refactor, docs, style, test, chore, perf
Scope: module/area affected (auto-detected from changed files)
```

**Installed Hooks:**

| Hook | Purpose |
|------|---------|
| `post-checkout` | Detects issue-based branches on checkout and loads context |
| `pre-commit` | Enforces conventional commit format with auto-detection |
| `file-watch.sh` | Background script that polls for changes and triggers auto-commits |

---

### `agent-nuvira skill` — Skill Compiler System

Automatically convert successful agent execution trajectories into reusable, parameterized skill scripts. Skills are extracted by an LLM from high-scoring runs, saved to `~/.nuvira/skills/`, and invoked directly via the orchestrator.

```bash
# List all compiled skills
agent-nuvira skill list

# Show a skill's definition and steps
agent-nuvira skill show "Add CLI Command"

# Run a skill with parameters (invokes the orchestrator)
agent-nuvira skill run "Add CLI Command" --params commandName=deploy --params description="Deploy to production"

# Manually trigger skill compilation from recent trajectories
agent-nuvira skill compile

# Search skills by keyword
agent-nuvira skill search "cli"

# Show skill quality scores
agent-nuvira skill quality

# Garbage-collect old/low-quality skills
agent-nuvira skill gc
```

**How it works:** Every 8 successful orchestration runs, the Self-Improver automatically feeds the top-5 trajectories to the Skill Compiler. The LLM identifies reusable patterns and parameterizes them with `{{paramName}}` placeholders. Skills act as pre-built task plans that the orchestrator can execute on demand.

---

### `agent-nuvira skills` — Community Skills Marketplace

Search, install, update, and manage community skills from the multi-source registry. Distinct from `agent-nuvira skill` (singular), which manages internal trajectory-compiled skills.

```bash
# Search the registry for skills matching a query
agent-nuvira skills search "deploy"
agent-nuvira skills search "security audit"

# Install a skill from the registry (into <project>/.agents/skills/)
agent-nuvira skills install code-assessment
agent-nuvira skills install website-deploy

# Install from a specific source kind
agent-nuvira skills install my-skill --source git-repo
agent-nuvira skills install my-skill --source local-dir

# List installed skills with provenance
agent-nuvira skills list
agent-nuvira skills list --origin registry
agent-nuvira skills list --origin local

# Update installed skills to newer versions
agent-nuvira skills update

# Uninstall a skill
agent-nuvira skills uninstall code-assessment

# Create a cross-skill bundle (Hermes parity)
agent-nuvira skills bundle backend-dev --create --name "Backend Dev" --description "Full workflow" --skills code-assessment,test-strategy

# List bundles
agent-nuvira skills bundle --list

# Show bundle contents
agent-nuvira skills bundle backend-dev --show
```

### Skill Execution — Language-Agnostic Marketplace Skills

Execute skills from the marketplace in any language (Python, Node.js, Shell, TypeScript) without the agent needing to understand the language.

```bash
# Execute a Python skill (e.g., image generation)
agent-nuvira skill execute image-gen --prompt "A sunset over mountains"

# Execute a Node.js skill (e.g., API call)
agent-nuvira skill execute api-call --endpoint /users --method GET

# Execute a Shell skill (e.g., system check)
agent-nuvira skill execute system-check --check disk

# The skill tool also supports execution via the agent
# Agent calls: skill tool → execute: { skill: "image-gen", args: { prompt: "..." } }
```

**How it works:**
1. Skill declares `runtime: python` (or node/shell/auto) in frontmatter
2. Executor auto-detects language from frontmatter, file extension, or shebang
3. API keys are injected via environment variables (provider credentials blocked for security)
4. Script is executed in a subprocess with timeout and output capture
5. Returns structured result (stdout, stderr, exit code, duration)

**Security:** Provider credentials (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.) are automatically blocked from skill execution. Only skill-declared `required_environment_variables` are injected.

**50 bundled first-party skills** ship with the product:

| Skill | Description |
|---|---|
| `website-deploy` | Deploy to Cloudflare Pages, Netlify, Vercel, GitHub Pages, AWS S3, Azure, Firebase |
| `code-assessment` | Structured codebase evaluation across 5 dimensions |
| `technical-roadmap` | Current state → target state → phased roadmap |
| `plan-create-track` | Multi-step job planning with visible progress |
| `test-strategy` | Deep test pass with matrix selection |
| `docx` | Create, read, edit Word documents |
| `security-audit` | Scan for vulnerabilities, classify, fix plan |
| `api-design` | REST API design → OpenAPI → implement → test |
| `db-migration` | Schema analysis → backward-compatible migration |
| `perf-profile` | Profile hotspots → optimize → verify |
| `doc-gen` | Generate documentation from code |
| `ci-cd-setup` | CI/CD pipeline setup for GitHub/GitLab |
| `docker-config` | Multi-stage Dockerfile + docker-compose |
| `dep-update` | Safe dependency updates with test verification |
| `code-refactor` | Safe refactoring with test verification |
| `env-setup` | Development environment bootstrap |
| `data-analysis` | Analyze datasets, generate insights and visualizations |
| `api-testing` | Automated API testing (REST/GraphQL) |
| `perf-test` | Load testing and performance benchmarking |
| `a11y-audit` | WCAG 2.1 accessibility auditing and fixes |
| `search-setup` | Full-text search (Algolia, Meilisearch, Elasticsearch) |
| `email-setup` | Transactional email templates and delivery |
| `payment-setup` | Stripe checkout, subscriptions, webhooks |
| `auth-setup` | OAuth2, JWT, RBAC authentication |
| `monitoring-setup` | Logging, metrics, alerting, health checks |
| `backup-recovery` | Backup strategy, disaster recovery runbooks |
| `schema-design` | Database schema design, ER diagrams, normalization |
| `i18n-setup` | Internationalization and localization |
| `graphql-api` | GraphQL API design, resolvers, subscriptions |
| `git-release` | Changelog, semver, tagging, publishing |
| `design-system` | Component library, tokens, Storybook |
| `legal-compliance` | GDPR/CCPA, privacy policy, cookie consent |
| `cron-setup` | Scheduled tasks and cron jobs |
| `image-optimize` | Image compression, format conversion, responsive images |
| `pdf-generate` | PDF generation from HTML/markdown with templates |
| `cache-setup` | Redis/Memcached caching layers |
| `queue-setup` | Message queue (RabbitMQ, SQS, Bull) setup |
| `rate-limit` | API rate limiting and throttling |
| `cors-setup` | CORS policy configuration |
| `error-tracking` | Error monitoring (Sentry, Bugsnag) |
| `feature-flags` | Feature flag system (LaunchDarkly, Unleash) |
| `webhook-setup` | Webhook endpoints and verification |
| `form-builder` | Form validation and submission handling |
| `data-sync` | Data synchronization across systems |
| `state-machine` | Finite state machine implementation |
| `websocket-setup` | WebSocket real-time communication |
| `api-versioning` | API versioning strategies (URL, header, query) |
| `multi-tenancy` | Multi-tenant architecture patterns |
| `blob-storage` | Blob storage (S3, GCS, Azure Blob) |
| `notification-setup` | Push notification infrastructure |

**Trust & safety:** sandboxed install names (`^[a-z0-9-]+$`), SHA-256 provenance, quarantine on mismatch, frontmatter cross-check.

---

### `agent-nuvira marketplace` — Unified Marketplace

Browse, search, and install workflow templates and plugins from the unified marketplace.

```bash
# Browse all available items
agent-nuvira marketplace browse

# Browse only workflows or plugins
agent-nuvira marketplace browse --type workflows
agent-nuvira marketplace browse --type plugins

# Search across all sources
agent-nuvira marketplace search "deploy"

# Install a workflow template
agent-nuvira marketplace install security-audit

# Show details for a marketplace item
agent-nuvira marketplace info quick-fix
```

---

### `agent-nuvira init` — Project Scaffolding

Scaffold new projects from built-in templates with interactive prompts and provider selection. Supports custom template directories.

```bash
# Interactive: name, template, and provider prompts
agent-nuvira init

# Name from CLI, interactive for template and provider
agent-nuvira init my-app

# Fully non-interactive
agent-nuvira init my-app --template node-api

# List all available templates
agent-nuvira init --list

# Use a custom template from a local directory
agent-nuvira init my-app --template custom --template-dir ~/my-templates
```

**Built-in templates:**

| Template | Description |
|---|---|
| `node-cli` | Node.js CLI app with Commander + TypeScript |
| `ts-library` | TypeScript library with Vitest |
| `node-api` | Express REST API with TypeScript |
| `python-cli` | Python CLI app with Click + Poetry |
| `minimal` | Minimal TypeScript project (1 file) |

The command also generates a `.nuvirarc.json` with your chosen provider and model, ready to use immediately.

---

## Docker Compose (5-Minute Onboarding)

Get the full Agent-Nuvira dashboard and CLI running with a single command — no Node.js or TypeScript setup required.

```bash
# Clone and go
cp .env.example .env       # Fill in your API keys
docker compose up           # Build & launch at http://localhost:3030
```

### What you get

- **Dashboard UI** at `http://localhost:3030` — provider health, cost tracking, model benchmarks, memory browser
- **CLI** accessible via `docker compose run --rm agent-nuvira <command>`
- **Persistent data** — config, memory, cache, and history stored in a named volume
- **Health checks** — automatic dashboard status verification

### Examples

```bash
# Quick one-shot commands via Docker
docker compose run --rm agent-nuvira chat "explain recursion in Rust"
docker compose run --rm agent-nuvira models --provider groq
docker compose run --rm agent-nuvira execute "add a health check endpoint"

# With local inference (requires Ollama on host)
docker compose --profile ollama up
```

### Docker Compose Structure

| Feature | Details |
|---|---|
| **Base image** | `node:22-alpine` — slim, secure |
| **Stages** | 3-stage build: TypeScript compile → Vite dashboard → runtime |
| **Layer caching** | Dependency manifests copied before source for cache reuse |
| **Ollama profile** | `--profile ollama` adds an Ollama container; defaults to `host.docker.internal` |
| **Volume** | `agent-nuvira-data` at `/root/.buff` preserves all data |
| **Port** | `3030` mapped to dashboard server |
| **Health** | Node `fetch()` verifies dashboard API every 30s |

### Configuration via Docker

Set API keys in `.env` (see `.env.example`) or pass them as environment variables:

```bash
docker compose run --rm -e GROQ_API_KEY=gsk_xxx agent-nuvira chat "hello"
```

---

## Provider Details

### Local (Ollama)

Uses the **Ollama HTTP API** running at `http://localhost:11434`.

```bash
# Ensure Ollama is running
ollama serve

# Pull a model
ollama pull llama2

# Use with the CLI
agent-nuvira chat --provider local --model llama2
```

**Runners:**

| Runner | Description | Requirements |
|---|---|---|
| `ollama` (default) | Ollama HTTP API | [Ollama](https://ollama.ai) installed and running |
| `huggingface` | HuggingFace Transformers via Python | Python 3, `pip install transformers torch` |
| `ggml` | GGML/GGUF models via llama.cpp | `llama-cli` binary, model file |

Configure the runner:

```bash
agent-nuvira config set providers.local.runner huggingface
agent-nuvira config set providers.local.model "microsoft/phi-2"
```

### Groq

Connects to **Groq** — the fastest inference API for open-source models, running on custom LPU hardware.

```bash
# Set your API key
export GROQ_API_KEY="gsk_..."

# List available models (Llama, Mixtral, Gemma, DeepSeek, and more)
agent-nuvira models --provider groq

# Chat with any model
agent-nuvira chat --provider groq --model llama-3.3-70b-versatile
agent-nuvira chat --provider groq --model deepseek-ai/deepseek-v4-flash

# Edit with Groq's fast inference
agent-nuvira edit src/server.ts --provider groq --model llama-3.3-70b-versatile
```

The Groq adapter uses `https://api.groq.com/openai/v1` by default.

**Get a free API key:** [console.groq.com](https://console.groq.com)

### NVIDIA NIM

Connects to the **NVIDIA NIM** OpenAI-compatible API at `https://integrate.api.nvidia.com/v1`.

```bash
# Set your API key
export NVIDIA_NIM_API_KEY="nvapi-..."

# List available models (121 models)
agent-nuvira models --provider nim

# Chat with any model
agent-nuvira chat --provider nim --model meta/llama-3.1-8b-instruct
agent-nuvira chat --provider nim --model deepseek-ai/deepseek-v4-flash
```

The NIM adapter uses `https://integrate.api.nvidia.com/v1` by default. You can override the base URL for self-hosted NIM deployments:

```bash
agent-nuvira config set providers.nim.baseUrl "http://your-nim-host:8000/v1"
```

### Google Gemini

Connects to the **Google Gemini API** free tier.

```bash
# Set your API key
export GEMINI_API_KEY="AIzaSy..."

# Use it (supports 8K+ token context)
agent-nuvira chat --provider gemini --model gemini-2.0-flash-exp
```

### OpenRouter

Routes through **OpenRouter** for access to 200+ models from multiple providers.

```bash
# Set your API key
export OPENROUTER_API_KEY="sk-or-v1-..."

# List available models
agent-nuvira models --provider openrouter

# Use a specific model
agent-nuvira chat --provider openrouter --model openai/gpt-4o
agent-nuvira chat --provider openrouter --model anthropic/claude-3-haiku
```

---

## Multi-Agent Orchestration (`agent-nuvira execute`)

The `execute` command runs an autonomous multi-agent pipeline that can plan, gather context, write code, review changes, run tests, and publish — all from a single goal.

```bash
# Execute a multi-agent pipeline
agent-nuvira execute "add JWT authentication to the Express app"

# With verbose logging to see each agent's work
agent-nuvira execute "add a health check endpoint" --verbose

# Use a specific provider for all agents
agent-nuvira execute "refactor the database layer" --provider groq

# Dry-run mode (shows what would change without writing)
agent-nuvira execute "add rate limiting" --dry-run

# Configure models per agent type
agent-nuvira execute "add tests" --agent-model planner=gemini --agent-model writer=groq

# Use persistent memory across sessions
agent-nuvira execute "fix the login bug" --memory

# Set a custom context window limit (default: 128,000 tokens)
agent-nuvira execute "refactor large codebase" --context-limit 256000

# Adjust pruning aggressiveness for long chains
agent-nuvira execute "build entire microservice" --context-prune medium
agent-nuvira execute "migrate database schema" --context-prune aggressive
```

**Context pruning flags:**

| Flag | Purpose | Default |
|---|---|---|
| `--context-limit <tokens>` | Max tokens before automatic pruning activates | 128000 |
| `--context-prune <mode>` | Prune aggressiveness: `soft` \| `medium` \| `aggressive` | `soft` |

The pruner automatically compresses the shared agent context between pipeline steps using 5 strategies: metadata stripping, file change collapsing, conversation truncation, artifact summarization, and aggressive fallback.


The pipeline runs these agents in dependency-aware order with parallelization:

| # | Agent | Type | Description |
|---|-------|------|-------------|
| 1 | **Planner** | Core | Analyzes the goal, creates a dependency-aware task plan |
| 2 | **Context Gatherer** | Core | Scans the codebase for relevant files and artifacts |
| 3 | **Security Scanner** | Safety | Scans for PII, prompt injection, and dangerous patterns |
| 4 | **Writer** | Core | Implements the code changes based on plan and context |
| 5 | **Reviewer** | Quality | Validates changes for bugs, security, and code style |
| 6 | **Tester** | Testing | Runs tests in a sandboxed temp directory or Docker container |
| 7 | **Debugger** | Testing | Iteratively diagnoses and fixes test failures via LLM |
| 8 | **Runner** | Execution | Executes shell commands to verify the program works |
| 9 | **MCP Agent** | Integration | Invokes external tools from connected MCP servers |
| 10 | **Skill Runner** | Learning | Executes compiled skill scripts as pre-built task plans |
| 11 | **Git Agent** | Publishing | Creates branches, commits with LLM-generated messages |
| 12 | **PR Description** | Publishing | Generates PR descriptions from git diff via LLM |
| 13 | **Package Agent** | Publishing | Bumps versions, builds, publishes to npm |
| 14 | **GitHub Release** | Publishing | Creates tags, release notes, and GitHub releases |

**Parallel execution:** Independent agents (e.g., Reviewer + Tester) run concurrently via `Promise.all()`. Exclusive agents (Runner, Debugger) get dedicated access. Results are merged with conflict resolution.

**Interactive development mode:** `agent-nuvira execute` without a goal launches an interactive loop with:
- **Model picker** — Choose your provider/model interactively
- **Session tracking** — Full history of goals executed in the session
- **Failure analysis** — Per-agent-type diagnosis with recovery actions
- **Follow-up suggestions** — LLM-powered contextual next steps
- **/fix** — Retry the last failed goal with failure context
- **/save / /resume** — Save and restore sessions across restarts
- **/suggest** — Search past trajectories for similar goals

---

## Architecture

```
CLI Commands (chat, edit, plan, models, config, cache, execute)
         │
         ▼
   Inference Layer (InferenceProvider interface)
         │
  ┌──────┼──────┬──────────┬─────────────┐
  │      │      │          │             │
  ▼      ▼      ▼          ▼             ▼
 Groq   NIM   Gemini    OpenRouter     Local
Adapter Adapter Adapter   Adapter      Adapter
  │      │      │          │             │
  ▼      ▼      ▼          ▼             ▼
 Groq  NVIDIA Google      OpenRouter  Ollama / HF /
 LPU   NIM   Gemini (free) APIs       GGML Models

         ┌──────────────────────────────┐
         │       Core Pipeline          │
         │  ┌────────────────────────┐  │
         │  │   Orchestrator         │  │
         │         │  │  ├─ Planner             │  │
         │  │  ├─ ContextGatherer    │  │
         │  │  ├─ Writer             │  │
         │  │  ├─ Reviewer           │  │
         │  │  ├─ Tester             │  │
         │  │  ├─ Runner             │  │
         │  │  ├─ Debugger           │  │
         │  │  ├─ GitAgent           │  │
         │  │  ├─ PackageAgent       │  │
         │  │  ├─ GitHubReleaseAgent │  │
         │  │  ├─ SecurityAgent      │  │
         │  │  ├─ SkillRunner        │  │
         │  │  ├─ MCPAgent           │  │
         │  │  └─ PRDescriptionAgent │  │
         │  └────────────────────────┘  │
         │                              │
         │  ┌────────────────────────┐  │
         │  │   Memory System        │  │
         │  │  ├─ Vector Store       │  │
         │  │  ├─ Trajectory/Store   │  │
         │  │  └─ Embedder           │  │
         │  └────────────────────────┘  │
         │                              │
         │  ┌────────────────────────┐  │
         │  │   Self-Learning        │  │
         │  │  ├─ Model Router       │  │
         │  │  ├─ Pattern Extractor  │  │
         │  │  ├─ Scorer             │  │
         │  │  └─ Skill Compiler     │  │
         │  └────────────────────────┘  │
         │                              │
         │  ┌────────────────────────┐  │
         │  │   Context Mgmt         │  │
         │  │  ├─ ContextPruner      │  │
         │  │  ├─ SQLite Cache       │  │
         │  │  ├─ Multi-file Parser  │  │
         │  │  └─ Token Chunking     │  │
         │  └────────────────────────┘  │
         │                              │
         │  ┌────────────────────────┐  │
         │  │   CLI Layer            │  │
         │  │  ├─ agent-nuvira init       │  │
         │  │  ├─ agent-nuvira model         │  │
         │  │  └─ agent-nuvira skill         │  │
         │  └────────────────────────┘  │
         │                              │
         │  ┌────────────────────────┐  │
         │  │   Docker Deployment    │  │
         │  │  └─ docker-compose.yml  │  │
         │  └────────────────────────┘  │
         └──────────────────────────────┘
```

### Website (Marketing Site)

The `website/` directory contains a complete static landing page for Agent-Nuvira (`agent-nuvira.com`):

| File | Purpose |
|---|---|
| `index.html` | Full marketing landing page with hero, features, pipeline visualization, provider cards, quickstart guide, extensions, and comparison table |
| `styles.css` | Complete styling with gradient text, animated particles, responsive grid, and dark theme |
| `script.js` | Interactive elements: scroll animations, copy-to-clipboard, mobile nav toggle, particle system |
| `_redirects` | Netlify/Cloudflare Page redirect rules |
| `_headers` | Custom HTTP security and cache headers |
| `assets/` | Hero images, screenshots, and OG meta assets |

The site is pre-configured for Netlify deployment with zero-configuration.

### Key Modules

| Module | Path | Purpose |
|---|---|---|
| **CLI Router** | `src/cli/router.ts` | Registers commands and resolves providers |
| **Config Manager** | `src/config/manager.ts` | Loads/saves config, merges env vars |
| **Inference Interface** | `src/inference/interface.ts` | `InferenceProvider` contract (`generate`, `isAvailable`, `getInfo`, `listModels`) |
| **Provider Factory** | `src/inference/factory.ts` | Instantiates the right adapter |
| **Adapters** | `src/inference/*-adapter.ts` | One per provider (Groq, NIM, Gemini, OpenRouter, Local) |
| **Model Discovery** | `src/cli/models.ts` | Lists and searches models from all providers |
| **Model Switch** | `src/cli/model.ts` | Context-preserving provider/model switching |
| **Project Scaffold** | `src/cli/init.ts` | Interactive project scaffolding with templates |
| **Skill Commands** | `src/cli/skill.ts` | List, compile, search, and run skill scripts |
| **Orchestrator** | `src/agents/orchestrator.ts` | Multi-agent pipeline coordinator (with context pruning) |
| **Context Cache** | `src/context/cache.ts` | SQLite-backed response caching |
| **Context Parser** | `src/context/parser.ts` | Multi-file reading, chunking, prioritization |
| **Context Pruner** | `src/learning/context-pruner.ts` | Token-aware context compression for long agent chains |
| **Skill Compiler** | `src/learning/skill-compiler.ts` | LLM-powered extraction of reusable patterns from trajectories |
| **Skill Store** | `src/learning/skill-store.ts` | Persistent skill storage with decay scoring |
| **Skill Runner Agent** | `src/agents/agents/skill-runner.ts` | Injects skill steps into the execution plan |
| **Plugin Registry** | `src/plugins/registry.ts` | Pluggable third-party provider system |
| **Logger** | `src/utils/logger.ts` | Colored, level-based logging |

---

## Workflow Examples

### Discover and Chat with a Model

```bash
# Step 1: See what's available on Groq
agent-nuvira models --provider groq

# Step 2: Narrow down by keyword
agent-nuvira models --search deepseek

# Step 3: Chat with a found model
agent-nuvira chat --provider groq --model deepseek-ai/deepseek-v4-flash
```

### Hybrid Provider Usage

Use different providers for different tasks:

```bash
# Use local models for quick, small edits
agent-nuvira edit README.md --instruction "fix typos" --provider local

# Use Groq for fast code generation
agent-nuvira edit src/routes.ts --instruction "add validation" --provider groq

# Use cloud models for complex planning
agent-nuvira plan . --task "design the database schema" --provider gemini

# Use OpenRouter for diverse model selection
agent-nuvira chat --provider openrouter --model openai/gpt-4o
```

### Multi-Agent Pipeline

```bash
# Let the multi-agent system handle everything
agent-nuvira execute "add input validation for all API routes"

# With verbose logging to see each step
agent-nuvira execute "create a health check endpoint" --verbose

# Use Groq for fast agent execution
agent-nuvira execute "refactor login logic" --provider groq
```

---

## Plugin System: Adding a New Provider

The plugin system allows you to add custom inference providers without modifying the CLI's core code.

### Step 1: Implement `InferenceProvider`

Create a class that implements the `InferenceProvider` interface:

```typescript
import { InferenceProvider } from 'agent-nuvira';
import { InferenceOptions, ProviderConfig } from 'agent-nuvira';

export class AnthropicAdapter implements InferenceProvider {
  readonly name = 'Anthropic';
  private config: ProviderConfig;

  constructor(config: ProviderConfig) {
    this.config = config;
  }

  async generate(prompt: string, options?: InferenceOptions): Promise<string> {
    const apiKey = this.config.apiKey;
    if (!apiKey) {
      throw new Error('Anthropic API key not configured');
    }

    const response = await fetch('https://api.anthropic.com/v1/messages', {
      method: 'POST',
      headers: {
        'x-api-key': apiKey,
        'anthropic-version': '2023-06-01',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: options?.model || 'claude-3-haiku-20240307',
        max_tokens: options?.maxTokens || 1024,
        messages: [{ role: 'user', content: prompt }],
      }),
    });

    const data = await response.json();
    return data.content[0].text;
  }

  async isAvailable(): Promise<boolean> {
    return !!this.config.apiKey;
  }

  getInfo(): string {
    return `Provider: Anthropic Claude\nModel: ${this.config.model || 'default'}\nStatus: ${this.config.apiKey ? '✅' : '❌'}`;
  }

  async listModels(): Promise<Array<{ id: string; name: string; provider: string; owner?: string; description?: string }>> {
    if (!this.config.apiKey) return [];
    // Fetch models from Anthropic API
    return [{ id: 'claude-3-haiku-20240307', name: 'claude-3-haiku-20240307', provider: 'Anthropic' }];
  }
}
```

### Step 2: Create a Plugin Wrapper

```typescript
import { ProviderPlugin, ProviderConfig, PluginMetadata } from 'agent-nuvira';
import { AnthropicAdapter } from './anthropic-adapter';

export const AnthropicPlugin: ProviderPlugin = {
  metadata: {
    name: 'Anthropic Claude',
    version: '1.0.0',
    description: 'Anthropic Claude API integration',
    author: 'You',
  },

  getProviderType(): string {
    return 'anthropic';
  },

  createProvider(config: ProviderConfig): AnthropicAdapter {
    return new AnthropicAdapter(config);
  },
};
```

### Step 3: Register the Plugin

At your application's entry point:

```typescript
import { getPluginRegistry } from 'agent-nuvira';
import { AnthropicPlugin } from './anthropic-plugin';

const registry = getPluginRegistry();
registry.register(AnthropicPlugin);
```

### Step 4: Configure and Use

Add the provider to your `nuvirarc.json`:

```json
{
  "defaultProvider": "anthropic",
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-...",
      "model": "claude-3-haiku-20240307",
      "temperature": 0.7,
      "maxTokens": 4096
    }
  }
}
```

Then use it:

```bash
agent-nuvira chat --provider anthropic
```

> **Note:** Plugins placed in `~/.nuvira/plugins/` are **auto-discovered** at CLI startup — no manual registration required. Programmatic registration via the Plugin Registry API is also supported for advanced use cases.

---

## Development

### Setup

```bash
git clone https://github.com/imdheerajKube/agent-nuvira.git
cd agent-nuvira
npm install
```

### Build

```bash
npm run build          # Compile TypeScript to dist/
npm run dev            # Build and run with tsx (fast)
```

### Project Structure

```
src/
├── index.ts              # Entry point & public exports
├── cli/
│   ├── router.ts         # Command registration & provider resolution
│   ├── commands.ts       # Base command class
│   ├── chat.ts           # Interactive chat
│   ├── edit.ts           # File editing
│   ├── models.ts         # Model discovery (list/search models)
│   ├── model.ts          # Context-preserving model switching
│   ├── skill.ts          # Skill compilation & execution
│   ├── init.ts           # Project scaffolding
│   ├── plan.ts           # Implementation plans
│   ├── config.ts         # Configuration management
│   ├── execute.ts        # Multi-agent orchestration (with context pruning)
│   └── cache.ts          # Cache management
├── agents/
│   ├── agent.ts          # Abstract Agent + types
│   ├── orchestrator.ts   # Multi-agent pipeline coordinator
│   ├── context-vault.ts  # Shared context bus
│   └── agents/
│       ├── planner.ts       # PlannerAgent
│       ├── context-gatherer.ts
│       ├── writer.ts        # WriterAgent
│       ├── reviewer.ts      # ReviewerAgent
│       ├── runner.ts        # RunnerAgent
│       ├── tester.ts        # TesterAgent
│       ├── debugger.ts      # DebuggerAgent
│       ├── skill-runner.ts  # SkillRunnerAgent (injects skill steps)
│       ├── git-agent.ts
│       ├── package-agent.ts
│       ├── github-release-agent.ts
│       └── security-agent.ts
├── config/
│   ├── types.ts          # TypeScript types
│   └── manager.ts        # Config load/save/env merging
├── inference/
│   ├── interface.ts      # InferenceProvider contract
│   ├── factory.ts        # Provider instantiation
│   ├── sse.ts            # Server-sent events streaming
│   ├── groq-adapter.ts   # Groq LPU
│   ├── nim-adapter.ts    # NVIDIA NIM
│   ├── gemini-adapter.ts # Google Gemini
│   ├── openrouter-adapter.ts # OpenRouter
│   └── local-adapter.ts  # Ollama / HuggingFace / GGML
├── context/
│   ├── cache.ts          # SQLite response cache
│   ├── parser.ts         # Multi-file context parsing
│   └── history.ts        # Chat history persistence
├── plugins/
│   └── registry.ts       # Plugin registration system
├── learning/
│   ├── skill-compiler.ts # LLM-powered skill extraction from trajectories
│   ├── skill-store.ts    # Persistent skill storage with decay scoring
│   ├── skill-types.ts    # Skill type definitions
│   ├── context-pruner.ts # Token-aware context compression
│   ├── model-router.ts   # Adaptive model routing
│   ├── scorer.ts         # Trajectory scoring
│   ├── pattern-extractor.ts
│   ├── agent-stats.ts
│   └── self-improver.ts
├── memory/
│   ├── embedder.ts       # LLM-based embeddings
│   ├── vector-store.ts   # Cosine similarity search
│   ├── trajectory-store.ts
│   └── memory-integration.ts
├── security/
│   └── scanner.ts        # Prompt injection / secret scanner
└── utils/
    ├── env.ts            # Environment variable loader
    └── logger.ts         # Colored logging
```

### Testing

```bash
# Run all tests (3,002 tests across 98 test files)
# Plus 6 dashboard component tests (src/web-dashboard)
npm test

# Watch mode
npm run test:watch

# With coverage
npm run test:coverage

# Type-check without emitting files
npx tsc --noEmit
```

---

## Roadmap

**Phases 1–11 are complete** — from Foundation (Phase 0) through TS Compiler API-Aware Structural Editing (Phase 11). See [UPGRADE_ROADMAP.md](./UPGRADE_ROADMAP.md) for the full implementation journey.

> 📊 **Architecture, strategy & contribution materials:** [ARCHITECTURE.md](./ARCHITECTURE.md) — Modular execution engine design with 7 module specifications, extensibility/observability systems, and phased migration plan. [ARCHITECTURE_DIAGRAMS.md](./ARCHITECTURE_DIAGRAMS.md) — Mermaid-rendered versions of all architecture diagrams (Module Architecture, Extensibility, Safe Execution, Data Flow, Observability Bus). [PRODUCT_STRATEGY.md](./PRODUCT_STRATEGY.md) — Competitive landscape, positioning map, OKR framework, and risk register. [PITCH_DECK.md](./PITCH_DECK.md) — 10-slide investor presentation outline with talking points and data. [CONTRIBUTING.md](./CONTRIBUTING.md) — Quick-reference contributor guide with docs map, dev setup, and contribution workflow. [GATEWAY.md](./docs/GATEWAY.md) — Complete user guide for the 22-platform multi-channel gateway: what it offers, CLI + dashboard setup for every platform, channel aliases, guaranteed delivery, natural-language task dispatch, security, and troubleshooting.

| Phase | Feature | Status |
|---|---|---|
| **Phase 1: Quick Wins** | | |
| 1.1 | Auto-discovery plugin loader — drop `.js` into `~/.nuvira/plugins/` | ✅ Complete |
| 1.2 | Complete streaming support — all 17+ providers | ✅ Complete |
| 1.3 | Cost tracking — per-provider/session/monthly | ✅ Complete |
| 1.4 | `agent-nuvira init` — interactive project scaffolding | ✅ Complete |
| 1.5 | Prompt history search — keyword + semantic | ✅ Complete |
| 1.6 | Skill compiler — auto-extract reusable patterns from trajectories | ✅ Complete |
| 1.7 | Context-window memory pruner — prevent OOM in long chains | ✅ Complete |
| 1.8 | Context-preserving model switching — mid-session provider changes | ✅ Complete |
| **Phase 2: Structural Changes** | | |
| 2.1 | Native embedding support — 3-tier embedder (Xenova/Python/LLM) | ✅ Complete |
| 2.2 | Workflow template marketplace — 10 templates + registry | ✅ Complete |
| 2.3 | Model benchmarking — 21 tasks, scoring, A/B comparison | ✅ Complete |
| 2.4 | Docker sandbox isolation — resource limits, network isolation, 8 images | ✅ Complete |
| 2.5 | Provider health dashboard — `agent-nuvira doctor` | ✅ Complete |
| 2.6 | Memory compression & pruning — trajectory summarization | ✅ Complete |
| **Phase 3: Major Upgrades** | | |
| 3.1 | VS Code extension — 9 commands, inline suggestions, diff viewer, agent progress panel | ✅ Complete |
| 3.2 | **B1: Chat Panel** — Multi-turn chat with streaming, 6 slash commands, session history, file context | ✅ Complete (v1.33.0) |
| 3.3 | **B3: Diagnostic → AI Fix** — "Fix with Agent-Nuvira" in lightbulb menu on red squiggles | ✅ Complete (v1.33.0) |
| 3.4 | **B5: Code Lens Actions** — Test/Review/Explain/Fix actions above functions and classes | ✅ Complete (v1.34.0) |
| 3.5 | Remote agent federation — multi-machine collaboration | ✅ Complete |
| 3.3 | Web UI dashboard — React + Recharts + DAG visualization | ✅ Complete |
| 3.4 | Hybrid model routing — complexity-based model selection | ✅ Complete |
| 3.5 | Team collaboration — shared config, memory, and review pipelines | ✅ Complete |
| 3.6 | Agent SDK — `@agent-nuvira/sdk` npm package + scaffolding | ✅ Complete |
| 3.7 | Provider CLI (`agent-nuvira provider list/health`) | ✅ Complete |
| 3.8 | Provider fallback routing — auto-failover with circuit breaker | ✅ Complete |
| 3.9 | Security scan CLI (`agent-nuvira security scan`) | ✅ Complete |
| 3.10 | Feedback & rating system (`agent-nuvira feedback`) | ✅ Complete |
| 3.11 | Marketplace unified CLI (`agent-nuvira marketplace browse/search/install`) | ✅ Complete |
| **Phase 4: Industry Standards** | | |
| 4.1 | MCP (Model Context Protocol) — client/manager/CLI with SSE transport + Firecrawl | ✅ Complete |
| 4.2 | AST-aware code editing — structural analysis engine (JS/TS/Python/Go/Rust) | ✅ Complete |
| 4.3 | Auto error-repair engine — diagnosis & retry budgets for test failures | ✅ Complete |
| 4.4 | A2A (Agent-to-Agent) Protocol — inter-agent communication standard | ✅ Complete |
| 4.5 | CI/CD headless mode — `agent-nuvira ci` with GitHub Actions integration | ✅ Complete |
| 4.6 | npm publishing & one-line install — `npx agent-nuvira` / `npx buff` | ✅ Complete |
| **Phase 5: Interactive UX** | | |
| 5.1 | Interactive dev mode — guided loop with model picker, session save/resume | ✅ Complete |
| 5.2 | Failure analysis — per-agent-type diagnosis with recovery actions | ✅ Complete |
| 5.3 | Follow-up suggestions — LLM-powered contextual next-step recommendations | ✅ Complete |
| 5.4 | /fix command — retry last failed goal with failure context | ✅ Complete |
| 5.5 | Test coverage — 3,002 tests across 98 test files (+6 dashboard component tests) | ✅ Complete |
| **Phase 6: Architecture Migration** | | |
| 6.1 | RecoverModule — extracted from ErrorRepairEngine with RepairBudget | ✅ Complete (v1.18.0) |
| 6.2 | ModuleRegistry — plugin-based agent loading replacing createAgent() | ✅ Complete (v1.18.0) |
| 6.3 | EventBus — structured observability with 37+ typed events | ✅ Complete (v1.19.0) |
| 6.4 | ReportModule — 4 output formats (text/JSON/MD/GHA) | ✅ Complete (v1.20.0) |
| 6.5 | InspectModule — keyword + LLM codebase scanning | ✅ Complete (v1.20.0) |
| 6.6 | VerifyModule — security scan + explicit verification pipeline | ✅ Complete (v1.21.0) |
| 6.7 | PlanModule + EditModule — goal decomposition + file change generation | ✅ Complete (v1.22.0) |
| 6.8 | ExecuteModule + TestModule — command execution + sandboxed testing | ✅ Complete (v1.23.0) |
| **Phase 9: Safe Execution Layer** | | |
| 9.1 | SafeExecutionLayer — file validation, Docker sandbox, safe LLM calls, EventBus integration | ✅ Complete (v1.26.0) |
| 9.2 | VerifyModule EventBus tests — 9 emission tests for SAFE_EXEC_* events | ✅ Complete (v1.26.0) |
| **Phase 10: Autonomous Publish** | | |
| 10.1 | CredentialStore — interactive Git/npm credential collection, GIT_ASKPASS, SSH agent, .npmrc injection | ✅ Complete (v1.29.0) |
| 10.2 | PhaseExecutionEngine — multi-goal project scopes with save/resume across restarts | ✅ Complete (v1.29.0) |
| 10.3 | `agent-nuvira publish` — 5-phase pipeline: tests → version → git → npm → GitHub release | ✅ Complete (v1.29.0) |
| 10.4 | `agent-nuvira phase` — create/execute/resume/status/list scopes with credential management | ✅ Complete (v1.29.0) |
| **Phase 11: TS Compiler API-Aware Structural Editing** | | |
| 11.1 | TS Compiler API Wrapper (`ts-adapter.ts`) — parse, find nodes, validate syntax via real TS parser | ✅ Complete (v1.31.0) |
| 11.2 | Structural Transformations (`transform.ts`) — rename, extract, inline, add param, change signature | ✅ Complete (v1.31.0) |
| 11.3 | Two-Tier Editing Engine (`edit.ts` rewrite) — TS API-first, regex fallback for all 7 operations | ✅ Complete (v1.31.0) |
| 11.4 | Phase 11 Tests — 66 tests (40 ts-adapter + 26 transform), all passing | ✅ Complete (v1.31.0) |

---

## Version History

| Version | Date | Key Changes |
|---------|------|-------------|
| **v1.76.1** | Aug 2026 | **Model Discovery Timeline** — new `/models/timeline` panel shows every model's freshness status, last-seen times, error rate, staleness classification; `/api/model-timeline` endpoint; auto-refreshes every 30s |
| **v1.76.0** | Aug 2026 | **Improved folder browser + Telegram auto-learning + Getting Started wizards** — Browse button redesigned with drive roots, breadcrumbs, search/filter, auto-refresh; Telegram contacts auto-learn real chat IDs; Platforms page with 22-platform grid; `agent-nuvira gateway setup [platform]` interactive wizard |
| **v1.75.3** | Aug 2026 | **Project picker fix + Telegram setup docs + CLI interactive mode** — removed broken "current dir" button, renamed label to "Select Project Folder", dashboard Channels tab shows 📖 Docs links and setup hints for every platform, `agent-nuvira gateway start` shows platform-specific setup instructions, CLI chat no longer exits after the initial task |
| **v1.75.2** | Aug 2026 | **Chat resolve loop fix + tool-loop step limit** — dashboard "No — ask the agent" button no longer loops back to the same command card, auto-routing shows a clear hint when falling back to local models, tool-loop step limit increased from 8 to 16 for complex tasks |
| **v1.75.0** | Aug 2026 | **Session resume + project-aware chat** — `--cwd` option for `agent-nuvira dashboard`, attached project scopes the agent's working directory (`toolContext.cwd`), 🗂️ folder browser for project attach, session resume auto-restores project context, project mismatch banner, sidebar shows project name per conversation; 4,864 root + 263 dashboard tests |
| **v1.74.2** | Aug 2026 | **Dashboard-first — chat is the front door (Phases 1–8 delivered)** — token-streaming typewriter, spec-complete markdown + syntax highlight, artifact cards (diff per-file accept/reject + commit-accepted, result, deploy — copy buttons + keyboard nav), inline command-run execution cards, project attach with code-map context, persisted sessions with smart-rail resume/search/rename/delete, composer attachments (file/paste/drag), /learn skill authoring + marketplace install, streaming cancel + retry; 4,864 root + 263 dashboard tests; CLI engine unchanged |
| **v1.63.0** | Aug 2026 | **Messaging campaign — 22-platform multi-channel gateway** — the full gateway surface with env-var-compatible credentials: DingTalk, Feishu, WeCom, Mattermost, Matrix, generic Webhook, BlueBubbles, ntfy, Teams, Google Chat, Weixin (iLink bot API), SMS (Twilio), IRC (RFC 1459 net/tls, two-way), SimpleX (daemon WS, two-way), Home Assistant (REST) on top of Telegram/Discord/Slack/WhatsApp — service-native `TWILIO_*`/`IRC_*`/`SIMPLEX_*`/`HASS_*` creds, zero new SDK deps; WhatsApp Baileys personal bridge (`agent-nuvira whatsapp pair`); guaranteed delivery ledger with auto-retry; dashboard Channels send-test; `agent-nuvira gateway status` platform-count line; SimpleX inbound (auto-accept + allowlists + reconnect); IRC inbound (addressing + allowlist + PING/PONG + reconnect); 4,280 tests |
| **v1.0.0** | Apr 2026 | Initial release — Core CLI with chat, 5 built-in providers (expandable to 17+ via plugins), config, models |
| **v1.1.0** | Apr 2026 | Model discovery with search/filter |
| **v1.2.0** | Apr 2026 | AI-assisted file editing (edit command) |
| **v1.3.0** | May 2026 | Implementation plans (plan command) |
| **v1.4.0** | May 2026 | Multi-agent pipeline (execute command) with Planner, Writer, ContextGatherer |
| **v1.5.0** | May 2026 | Additional agents — Tester, Runner, Debugger |
| **v1.6.0** | Jun 2026 | Agent retry logic, format validation, git integration |
| **v1.7.0** | Jun 2026 | Phase 1 features — plugin system, cost tracking, logging |
| **v1.8.0** | Jun 2026 | Native embeddings, vector store, trajectory memory |
| **v1.9.0** | Jul 2026 | Workflow templates, model benchmarking |
| **v1.10.0** | Jul 2026 | Docker sandbox, provider health dashboard |
| **v1.11.0** | Jul 2026 | Skill compiler, context pruner, model switching |
| **v1.12.0** | Jul 2026 | VS Code extension, web dashboard, agent federation |
| **v1.13.0** | Jul 2026 | Hybrid model routing, team collaboration, Agent SDK |
| **v1.14.0** | Jul 2026 | Provider fallback, security scan, feedback system, marketplace CLI |
| **v1.14.6** | Jul 2026 | Skill compiler system, context-window pruner, Docker Compose onboarding |
| **v1.15.0** | Aug 2026 | npm publishing — `npx buff` / `npx agent-nuvira` live on npm (1.3 MB) |
| **v1.15.1** | Aug 2026 | Interactive dev mode — model picker, session tracking, /save / /resume, /suggest |
| **v1.15.2** | Aug 2026 | Windows compatibility fixes |
| **v1.15.3** | Aug 2026 | Accessibility fix — `window.open` → native `<a>` tags |
| **v1.15.4** | Aug 2026 | Search/filter bar, column count toggle, speech provider section |
| **v1.15.5** | Aug 2026 | SSE header support for MCP |
| **v1.15.6** | Aug 2026 | Firecrawl integration for web search |
| **v1.16.0** | Aug 2026 | Comprehensive MCP README docs, SSE header support |
| **v1.16.1** | Aug 2026 | Interactive dev mode enhancements — failure analysis, follow-up suggestions, /fix command, 35 new unit tests |
| **v1.26.0** | Aug 2026 | Phase 9 — SafeExecutionLayer module (file validation, Docker sandbox, safe LLM calls) + 32 new tests (23 SafeExec + 9 Verify Bus) |
| **v1.27.0** | Aug 2026 | Website + SVG — Phase 9 SafeExecutionLayer, phase progress 9/9, 2,207 tests |
| **v1.29.0** | Sep 2026 | Phase 10 — Autonomous publish + phase-wise execution (CredentialStore, PhaseEngine, `agent-nuvira publish`, `agent-nuvira phase`, git push, npm auth) + 86 new tests |
| **v1.30.0** | Sep 2026 | Phase 10 tests + docs — 80 unit tests (CredentialStore + PhaseExecutionEngine), README/Product_Guide/website updated with Phase 10 progress |
| **v1.31.0** | Sep 2026 | Phase 11 — TS Compiler API-Aware Structural Editing (ts-adapter.ts, transform.ts, edit.ts rewrite, 66 new tests), proper parser-level accuracy for TS/JS edits |
| **v1.32.0** | Oct 2026 | Pillar A — GitLab Agent (MRs, issues, pipelines) + PR Review Agent (inline review, security scans) + website Git & PR section |
| **v1.33.0** | Oct 2026 | Pillar B1+B3 — VS Code Chat Panel with streaming, slash commands, session history + Diagnostic → AI Fix from lightbulb menu |
| **v1.34.0** | Oct 2026 | Pillar B5 — VS Code Code Lens actions (Test/Review/Explain/Fix) via quick pick menu above functions and classes |
| **v1.42.0** | Aug 2026 | Learning-router escalation + per-model bandit priors + Promotion Gate (ruflo ADR-149/150 mirrors) |
| **v1.43.0** | Aug 2026 | Startup progress feedback + Auto-mode session failover on token expiry |
| **v1.44.0** | Aug 2026 | Central quota ledger, per-subtask complexity labels, free/local-first gate |
| **v1.45.0** | Aug 2026 | Checkpoint/resume pipelines + quota cost-transparency card |
| **v1.45.5** | Aug 2026 | Opt-in Auto failover confirmation (interactive + one-shot) |
| **v1.46.0** | Aug 2026 | Always-on dashboard quota watcher |
| **v1.47.0** | Aug 2026 | Vector retrieval — token-efficient context via local embeddings + pure-JS vector store |
| **v1.48.0** | Aug 2026 | FAISS-style vector search backend — pluggable `VectorStore` (pure-JS IVF-flat ANN + optional native tier) |
| **v1.49.0** | Aug 2026 | Hermetic memory tests, IVF-vs-exact recall/latency benchmark, cross-session backend transparency |
| **v1.49.1** | Aug 2026 | Native FAISS tier actually activates — rewritten for the real `@faiss-node/native` v0.1.11 API; `agent-nuvira memory backend --check` |
| **v1.50.0** | Aug 2026 | `agent-nuvira memory backend --check` diagnostics — active backend, why it was chosen, native-FAISS availability probe + install guidance |
| **v1.51.0** | Aug 2026 | Routing strategy super-enhancement — Thompson-sampling bandit, uncertainty escalation, per-model learning, promotion gate A/B, routing rules, hard constraints, credential-aware filtering, quota-ledger integration, runtime stats blending, verification escalation, free/local-first gate; 2,934 tests |
| **v1.51.1** | Aug 2026 | Docs patch — completed the published README version-history table (added v1.50.0 + v1.51.0 rows) |
| **v1.52.0** | Aug 2026 | Predictive model-availability routing (registry drives every pick — dead/unkeyed providers skipped before scoring, no more wasted first calls); web dashboard: scrubbable pipeline phase timeline + narrated "why did the router pick this?" walkthrough; 2,990 tests |
| **v1.53.0** | Aug 2026 | Per-action "learned from real usage" telemetry everywhere (chat/execute/plan/edit/skill/learn/ci/doctor all write the registry; dashboard panel + `models status --verbose` show who killed/verified what); daily timeline chart in the dashboard; recovery loop (a later real success un-parks + re-verifies a recovered provider); hermetic E2E failover test (`tests/e2e/`) proving "registry learns the block, next pick skips it"; 2,996 tests |
| **v1.54.0** | Aug 2026 | VS Code extension telemetry attribution — the extension tags every IDE-driven LLM call with `BUFF_TELEMETRY_ACTION` (`ide-chat` / `ide-inline` / `ide-<command>`) so IDE usage gets its own rows in the per-action "learned from real usage" registry log + dashboard panel; 3,002 tests |
| **v1.55.0** | Aug 2026 | `agent-nuvira models unblock <provider>` escape hatch — manually release a registry-blocked provider (demote unavailable→unverified, clear quota parks + ledger cooldown, live re-probe with honest `stillBlocked`); also fixed the pre-existing `models status --json` / `refresh --json` flag-shadowing bug; 3,011 tests |
| **v1.60.0** | Aug 2026 | **No hardcoded model defaults — fully dynamic selection** — `defaultProvider` is now `'auto'`, resolved at runtime to the best *available* provider for your keys + learned registry (verified → configured-with-key → zero-config local); every provider's model pin is the `'default'` sentinel, resolved at call time to a registry-verified working model (explicit pins still win, health-checked). New `src/learning/model-selection.ts` is the single selection authority (`rankAvailableProviders` / `resolveDefaultProvider` / `requireAdapterModel`); fallback chains are built from what you actually configured — never a fixed list; `'auto'` can never reach an adapter factory (onboarding guidance instead); 3,395 tests |
| **v1.60.1** | Aug 2026 | **Live per-model context windows feed the router's context preflight** — the model probe records each provider-advertised context window into the Model Availability Registry (Ollama `/api/tags` `general.context_length`, OpenRouter `/models` `context_length`); `resolveContextWindow` precedence: user override → **live registry descriptor** → provider-level estimate → generous default; `ModelDescriptor`/`ModelRegistryEntry` gain `contextWindowTokens`; 3,398 tests |
| **v1.60.2** | Aug 2026 | **Live context windows for every provider that exposes one** — Ollama multi-source parsing (`details.context_length` on 0.32.x, `general`/`llama`/family-keyed `model_info`) + bounded `/api/show` fallback (max 8 lookups — live-verified `gemma4:e4b` → 131,072); Gemini `inputTokenLimit` (gated on `generateContent`); NIM `max_model_len` (vLLM-backed); Groq documented as not exposing one; 3,404 tests |
| **v1.60.3** | Aug 2026 | **Reasoning traces + failure-lesson memory + goal-fidelity planning** — P0 per-step reasoning-trace capture (`agent-nuvira trace list/show/replay/clear` + dashboard 🔍 Reasoning Traces panel: agent × model × prompt digest × tokens × latency × routing snapshot); P1 self-improver distills negative trajectories into episodic failure-lesson memory injected into future planning prompts; **planner goal-fidelity guard** rejects off-topic / few-shot-regurgitated plans (the NVDA-addon failure mode) with an actionable error; **planner-repair model escalation** re-routes a failed planner through the Auto router at the next complexity level; 3,447 tests |
| **v1.60.4** | Aug 2026 | **Per-task repair model escalation for ALL agents** — the stronger-model escalation that fixed planner failures now applies to writer/debugger/security/tester/reviewer: a failing task's repair is handed a re-routed LLM at the next complexity level, climbing from the ROUTED complexity (latched per task id) so repair is always strictly above the tier that failed; `createEscalatedLLM` is the single shared escalation primitive; 3,452 tests |
| **v1.61.0** | Aug 2026 | **Routing + config-hygiene program (Issues 001–004)** — (1) **ALL 17+ configured providers join routing** via a dynamic `provider-catalog.ts` single source of truth (21 providers: env var, base URL, OpenAI-compat, keyless, capabilities, pricing, context window) + a generic `OpenAICompatAdapter`; nothing is hardcoded — whatever the user keys up is what the router scores; (2) **the router now leverages the data it already gathers** — registry pre-filters degrade dead providers (0 verified + ≥3 unavailable), the Thompson-sampling bandit is ON by default, context-window sources are transparent, and decision explanations cite the registry counts that excluded a provider; (3) **router tech fires at ALL action points** — `agent-nuvira plan` / `eval --routing` / `benchmark` / `model explain` / `edit --auto-route` now resolve through the shared `buildAutoResolveOptions()` full feature set (bandit, quota-ledger, runtime stats, cost/speed/reasoning floors, escalation, paid gate, context preflight) instead of degraded paths; (4) **invalid API keys are auto-cleared + stale local models purged** — a provider with 3 consecutive 401/403s has its dead key removed from config (or told which env var to fix) with a clear error, and `agent-nuvira models refresh` prunes local models that were deleted (`ollama rm`) — verified entries are demoted (telemetry preserved) rather than hard-deleted; 3,510 tests |
| **v1.59.4** | Aug 2026 | P6 M6.6 Software Bill of Materials: `agent-nuvira sbom` (CycloneDX 1.5 from lockfile, `--reproducible` pins), `sbom verify` (drift/tamper), `sbom licenses` (copyleft/unknown audit), `doctor --enterprise` Supply Chain check; 3,313 tests |
| **v1.59.5** | Aug 2026 | Dashboard surfaces mid-stream flakiness end-to-end: violet `⏸ flaky N%` chips on registry rows (mirroring the CLI's `model explain` chip), `⏸ N flaky` provider badges, and a **Flaky mid-stream** stats card — the exact signal `routing.partialFlakiness` uses to deprioritize providers; 3,313 root tests |
| **v1.59.9** | Aug 2026 | **Config-path consistency** — `BUFF_CONFIG_DIR` is now honored by the config manager, dashboard server readers, and vector-store backend picker via one shared resolver (explicit dir > `$BUFF_CONFIG_DIR` > `~/.buff`); hermetic/alternate-config runs can never leak into the real `~/.nuvira/nuvirarc.json`; 3,367 root tests |
| **v1.59.8** | Aug 2026 | P6 M6.4 **Nuvira Gateway (minimal slice)** — federation handshake becomes token-verified (`--auth oidc` + `JwtOidcAdapter`, dependency-free RS256 JWT check; PEM path persists for daemon restart) + dashboard **RBAC identity card** (whoami mirror) + **secrets hardening** (`doctor --enterprise` flags plaintext `apiKeys` arrays) + admin guard-coverage parity test; 3,363 root tests |
| **v1.59.7** | Aug 2026 | P6 M6.1 **RBAC** — `agent-nuvira admin role add/remove/list` + `whoami` (admin/operator/viewer permission matrix over the admin surface; OIDC adapter interface; legacy single-user stays permissive until roles assigned) + dashboard **governance policy card** (live `routing.governance.*`) + CLI **flakiness trend tags** (`healing`/`worsening` in `models status`); 3,348 root tests |
| **v1.59.6** | Aug 2026 | P6 M6.5 **Admin governance API** (`agent-nuvira admin policy/allow/deny/allow-model/deny-model/max-cost/pii-min/unblock/clear` over the M2.4 policy) + dashboard **flakiness healing sparklines** (per-entry `partialHistory` trajectory, never hard-wiped) + Requests panel `⏸ N` partial chips (partials excluded from error rate); 3,328 root tests |
| **v1.59.3** | Aug 2026 | `config set routing.<gate>` now accepts the boolean soft-signal keys (`capabilityFit`, `contextFit`, `partialFlakiness`); 3,286 tests |
| **v1.59.2** | Aug 2026 | P4 M4.4 partial flakiness now feeds the ROUTER: registry `partialRate` EMA (bumped by mid-stream interruptions, healed by clean successes, never flips status) → reliability penalty (capped 40%) gated by `routing.partialFlakiness` (default ON) + transparent `⏸ flaky` chip in `models explain`; 3,284 tests |
| **v1.59.1** | Aug 2026 | Dashboard: P4 M4.4 partial mid-stream interruption chips surface end-to-end (violet `⏸` timeline segment, day chips with streamed-chunk tooltip, per-action Partial section + stat); 3,276 tests |
| **v1.59.0** | Aug 2026 | P6 Enterprise Hardening begins: M6.2 secret-redaction scrubber (every log + audit line scrubbed; `BUFF_NO_REDACT` debug escape) + M6.3 tamper-evident SHA-256 hash-chained audit (`agent-nuvira audit verify/export`, sidecar head state, legacy-compat) — `doctor --enterprise` audit checks now detect tampering with the exact line; 3,275 tests |
| **v1.58.9** | Aug 2026 | P7 M7.4 opt-in gateway telemetry/usage-health flags (`routing.gatewayTelemetry.enabled` + `healthFlags`, OFF by default, privacy-safe — aggregates only, never prompt content) surfaced via `doctor --enterprise`; 3,232 tests |
| **v1.58.8** | Aug 2026 | **Permanent fix for the persistent dashboard "server unreachable / Failed to fetch" issue** — server now binds BOTH IPv4 + IPv6 loopback (macOS resolves `localhost` → ::1 first), CLI opens deterministic 127.0.0.1 |
| **v1.58.7** | Aug 2026 | M4.4 conservative compression (lossless-for-code, off by default) + `partial` mid-stream telemetry + `agent-nuvira doctor --enterprise` self-check (gateway, secrets, audit, RBAC) + upgrade guide (P7 M7.2) |
| **v1.58.6** | Aug 2026 | Fixed `routing.*` config never surviving a reload — `loadConfig` now merges the routing section (bandit/quota/governance/contextWindows/nuviraSidecar), so `agent-nuvira config set routing.*` persists across restarts (regression test) |
| **v1.58.5** | Aug 2026 | P5 config-key support — `agent-nuvira config set routing.nuviraSidecar.enabled\|image` (additive M5.4 keys; 2 new config tests) |
| **v1.58.4** | Aug 2026 | Nuvira-Router **P5 sidecar** (docker-compose.nuvira.yml profile + `agent-nuvira doctor --nuvira` probe; nuvira joins the auto-router provider universe with a neutral profile; keyless gateways supported) + **P4 resilience core** (mid-stream continuation retry — buffered tokens + bounded continue-note on chat auto-failover, reasoning-replay cache with SSE `reasoning_content` capture, context-relay summaries); 3,300+ tests |
| **v1.58.3** | Aug 2026 | Nuvira-Router P3: dashboard **Requests panel** (per provider×model×action request stats — failures, avg/p50/p95/p99 latency, measured spend from the cost ledger) + **`models explain --since <ref>` decision diff** (before→after candidate score changes, winner changes); 3,161+ tests + 54 dashboard component tests |
| **v1.58.2** | Aug 2026 | Models dashboard "Failed to fetch" repeat fix — the panel fetch is now resilient: per-fetch timeouts, independent health/registry fetches (one failing never hides the other), auto-retry with backoff on transient network failures, and fast self-healing re-poll after a failure (no more stuck error banner); 3,161 tests + 48 dashboard component tests |
| **v1.58.1** | Aug 2026 | Dashboard mirrors the CLI `model explain` guarantees — the Auto Router panel renders the M2.x chips (🎯 fit / 📏 measured·📐 estimated / ⏳ ctx) on every provider row, served by `/api/routing` + `/api/all`; docs sync (`MODELS_EXPLAIN_DEMO.md` dashboard section); 3,161 tests + 45 dashboard component tests |
| **v1.58.0** | Aug 2026 | Nuvira-Router P2: capability-aware scoring (`routing.capabilityFit` gate), wire-token measured-cost inputs (real `usage` tokens beat the 2,000/500 estimate; `models explain` shows 📏 measured vs 📐 estimated), multi-account key rotation (multiple `apiKeys` per provider, dead accounts parked + skipped, `tests/e2e/key-rotation`), governance constraints (`routing.governance` — provider/model allow-allow & deny lists, admin per-call max-cost cap, PII-domain block; hard policy violations refuse to serve with `PIIPolicyError`/`GovernancePolicyError`), context-length preflight (`routing.contextFit` — nominal window vs estimated payload, `⏳ ctx N%` chip in `models explain`); also ships the dashboard `--force` + `--port` fixes previously staged as v1.57.0 (never published); 3,159 tests + 42 dashboard component tests |
| **v1.57.0** | Aug 2026 | `agent-nuvira dashboard --force` — detect a STALE dashboard on the port (API/SSE mismatch: /api/model-registry answers SPA HTML instead of JSON) and offer to restart it: probe classifies port state (current dashboards and non-dashboard processes are never touched), confirms, finds the PID, kills it, waits for the port to free, and re-binds a fresh server; also fixed the pre-existing `--port` bug — the server bound the import-time 3030 default, now it resolves the bind at call time from explicit overrides; 3,032 tests + 42 dashboard component tests |
| **v1.56.1** | Aug 2026 | Dashboard Models-panel crash fix — "Failed to execute 'json' on 'Response': Unexpected token '<'" when a stale dashboard server returns SPA HTML for an unknown /api/* route: unknown /api/* now returns a JSON 404, all /api/* responses parse through a shared defensive helper (Content-Type check + try/catch, optional sections degrade to hidden), and `agent-nuvira dashboard` logs a clear EADDRINUSE message instead of crashing; 3,011 tests + 42 dashboard component tests |
| **v1.56.0** | Aug 2026 | Dashboard per-action telemetry timeline is now scrubbable — drag across days, click a day, or use the range slider to see that day's exact verified/killed chips (which provider × model each action killed or verified), with ▶ play/pause day-by-day sweep; timeline day buckets carry deduped raw events end-to-end; 3,011 tests + 39 dashboard component tests |

---

## Phase-Wise Feature Summary

### Phase 0: Foundation — Core CLI & Provider Layer
| Feature | Description |
|---------|-------------|
| **17+ Inference Providers** | 5 built-in (Groq, NVIDIA NIM, Google Gemini, OpenRouter, Local) + 12 configurable via env vars (OpenAI, Anthropic, Mistral, Cohere, Together, DeepInfra, Fireworks, Perplexity, Azure, LM Studio, Anyscale, vLLM) |
| **Unified CLI** | 25+ commands via Commander.js with shared options |
| **Config System** | JSON config file + env vars + CLI flags priority chain |
| **Streaming** | Real-time token-by-token output for all 17+ providers |
| **Response Caching** | SQLite-backed cache with configurable TTL |
| **Chat Interface** | Interactive chat with conversation history and `/` commands |
| **File Editing** | AI-assisted file editing with dry-run mode |
| **Implementation Plans** | Codebase-aware plan generation with architecture impact analysis |

### Phase 1: Quick Wins — Developer Experience
| Feature | Description |
|---------|-------------|
| **Plugin System** | Programmatic API + auto-discovery from `~/.nuvira/plugins/` |
| **Project Scaffolding** | `agent-nuvira init` with 5 built-in templates + interactive provider wizard |
| **Model Discovery** | `agent-nuvira models` with search/filter across all providers |
| **Model Switching** | Context-preserving provider/model switch mid-session |
| **Cost Tracking** | Per-provider, per-session, and monthly cost dashboards |
| **History Search** | Keyword + semantic search across past conversations |
| **Skill Compiler** | Auto-extracts reusable patterns from trajectories into runnable skills |
| **Context Pruner** | 5-strategy token compression for long agent chains |

### Phase 2: Structural Changes — Memory & Infrastructure
| Feature | Description |
|---------|-------------|
| **Vector Store** | Cosine similarity search over embedded trajectories |
| **Trajectory Store** | Few-shot example storage with quality scoring |
| **3-Tier Embedder** | Xenova (fast) → Python (medium) → LLM (fallback) |
| **Workflow Marketplace** | 10 built-in templates + GitHub registry with install/publish |
| **Model Benchmarking** | 21 standardized coding tasks with scoring and A/B comparison |
| **Docker Sandbox** | 8 base images, resource limits, network-isolated execution |
| **Provider Health** | `agent-nuvira doctor` with color-coded status, watch mode, auto-fix |
| **Memory Compression** | Automatic trajectory summarization with configurable retention |

### Phase 3: Major Upgrades — Advanced Agent Systems
| Feature | Description |
|---------|-------------|
| **VS Code Extension** | Chat Panel (streaming, slash commands), Diagnostic→AI Fix, Code Lens actions, 9 commands, inline suggestions, diff viewer, agent progress panel |
| **Agent Federation** | Multi-machine collaboration via A2A protocol, server, and client |
| **Web Dashboard** | React + Recharts + DAG visualization, model health, cost charts |
| **Hybrid Model Routing** | Complexity-based model selection with cost optimization |
| **Team Collaboration** | Git-synced shared config, memory, and review pipelines |
| **Agent SDK** | `@agent-nuvira/sdk` npm package with scaffolding CLI |
| **Provider CLI** | `agent-nuvira provider list/health` with per-provider diagnostics |
| **Provider Fallback** | Auto-failover with circuit breaker and configurable chain |
| **Security Scanner** | Detects PII, prompt injections, and dangerous code patterns |
| **Feedback System** | `agent-nuvira feedback record/list/stats/clear` drives self-improvement |
| **Marketplace CLI** | Unified `agent-nuvira marketplace browse/search/install/info` |

### Phase 4: Industry Standards — Protocol & Integration
| Feature | Description |
|---------|-------------|
| **MCP Protocol** | Model Context Protocol client/manager with stdio + SSE transport |
| **AST Editing Engine** | Structural code analysis for JS/TS/Python/Go/Rust |
| **Auto Error-Repair** | Automatic diagnosis and repair with configurable retry budgets |
| **A2A Protocol** | Agent-to-Agent communication standard for federation |
| **CI/CD Headless** | `agent-nuvira ci` for automated pipelines with GitHub Actions |
| **npm Publishing** | `npx agent-nuvira` / `npx buff` for zero-setup onboarding |

### Phase 5: Interactive UX — Developer Experience
| Feature | Description |
|---------|-------------|
| **Interactive Dev Mode** | Guided loop with model picker, session management, and goal tracking |
| **Session Save/Resume** | Save and restore development sessions with full history |
| **Failure Analysis** | Per-agent-type diagnosis with specific recovery actions |
| **Follow-up Suggestions** | LLM-powered contextual next-step recommendations |
| **/fix Command** | Retry last failed goal with failure context |
| **Graceful Error Recovery** | Rate-limit handling, auth failures, and network error recovery |

### Phase 6: Architecture Migration — Modular Plugin Architecture
| Feature | Description |
|---------|-------------|
| **RecoverModule (Phase 1)** | Extracted from ErrorRepairEngine — discriminated union strategies + RepairBudget (3 attempts with exponential backoff) |
| **ModuleRegistry (Phase 2)** | Plugin-based agent loading — 14 built-in agent modules, `register()` / `load()` / `unload()` lifecycle, EventBus integration |
| **EventBus (Phase 3)** | Structured observability — 37+ typed events, 4 built-in consumers (Logger, Metrics, Audit, MetricsBuffer), typed event schema |
| **ReportModule (Phase 4)** | 4 output formats (markdown, JSON, summary, verbose) — extractable from buildResult() |
| **InspectModule (Phase 5)** | Keyword scanning + LLM-based file classification — ContextGatherer wrapper with depth-limited walk, .nuviraignore support |
| **VerifyModule (Phase 6)** | 4 check types (security, goal-alignment, tests, code-quality) — configurable strictness (low/medium/high), pass/fail scoring |
| **PlanModule (Phase 7)** | Goal decomposition — 3 JSON parsing strategies, step normalization, fallback plan, EventBus events |
| **EditModule (Phase 7)** | File change generation — AST syntax validation, token-budget-aware file selection, 2-attempt retry loop, model-switch support |
| **ExecuteModule (Phase 8)** | Command execution — 5-strategy command inference (backtick, Run prefix, npm patterns, file extension), npm test validation |
| **TestModule (Phase 8)** | Sandboxed test execution — temp directory, multi-framework output parsing (vitest, jest, generic), EventBus events |
| **SafeExecutionLayer (Phase 9)** | 3-domain safety system — file validation (size, gitignore, syntax, security scan), Docker sandbox (resource limits, container lifecycle), safe LLM calls (injection guardrail, prompt/response truncation, exponential backoff with circuit breaker) |
| **CredentialStore (Phase 10)** | Interactive Git/npm credential collection — auto-detection from env vars (GITHUB_TOKEN, GH_TOKEN, NPM_TOKEN), GIT_ASKPASS setup for HTTPS auth, SSH agent integration with passphrase support, .npmrc token injection |
| **PhaseExecutionEngine (Phase 10)** | Multi-goal project scope execution — sequential phase execution with save/resume across restarts, credential management, progress tracking |
| **`agent-nuvira publish` (Phase 10)** | Autonomous 5-phase publish pipeline — test verification → version bump → git commit/tag/push → npm build/publish → GitHub release |
| **`agent-nuvira phase` (Phase 10)** | Phase-wise project execution CLI — create/execute/resume/status/list/delete scopes with interactive pauses and credential collection |
| **TS Compiler API Wrapper (Phase 11)** | Proper TypeScript Compiler API integration — parser-level accuracy with parseSourceFile, findStructuralNodes, validateTSSyntax, replaceNodeText, and insertAt |
| **Structural Transformations (Phase 11)** | Real code transformations — renameSymbol, extractFunction, inlineFunction, addParameter, changeSignature with NLP-based detection |
| **Two-Tier Editing Engine (Phase 11)** | All 7 edit operations try TS Compiler API first (for TS/JS), fall back to regex (for Python/Go/Rust) — AST-aware `tryFindNodeTS()` helper |

### Agent Catalog — 15 Agent Roles & Management
| Agent/Component | Type | Description |
|-----------------|------|-------------|
| **PlannerAgent** | Core | Analyzes goals, creates dependency-aware task plans |
| **ContextGathererAgent** | Core | Scans codebase, identifies relevant files and artifacts |
| **WriterAgent** | Core | Implements code changes based on plan and gathered context |
| **ReviewerAgent** | Core | Validates changes for bugs, security, and style |
| **RunnerAgent** | Execution | Executes shell commands and captures output |
| **TesterAgent** | Testing | Runs tests in sandboxed temp directory or Docker container |
| **DebuggerAgent** | Testing | Iteratively diagnoses and fixes test failures via LLM |
| **GitAgent** | Publishing | Creates branches, commits with LLM messages, generates PR descriptions |
| **PackageAgent** | Publishing | Bumps version, builds, publishes to npm, generates changelogs |
| **GitHubReleaseAgent** | Publishing | Creates tags, release notes, and GitHub releases via `gh` CLI or API |
| **SecurityAgent** | Safety | Scans for PII, prompt injection, and dangerous code patterns |
| **SkillRunnerAgent** | Learning | Executes compiled skill scripts as pre-built task plans |
| **MCPAgent** | Integration | Invokes MCP tools from connected servers via stdio or SSE transport |
| **Orchestrator** | Management | Coordinates all agents with dependency-aware scheduling, parallel execution, context pruning, and interactive recovery |

## License

MIT