Monorepo for the Virage ecosystem — a Git-aware RAG pipeline that turns your codebase and docs into a searchable vector store. Pick your embedder and vector store, run one command, and keep the index in sync as code changes.

Package	Version	Description
@vivantel/virage		Rust CLI binary — primary install
@vivantel/virage-core		Pipeline orchestrator, interfaces, config loading
@vivantel/virage-dashboard		React web UI for pipeline monitoring

Package	Version	Description
@vivantel/virage-chunker-ce-ast		Shared AST walker used by all CE native chunkers
@vivantel/virage-chunker-ce-ts		TypeScript / JavaScript chunker (pure TS, no native binary)
@vivantel/virage-code-chunk-chunker		AST-aware code chunking for TS, JS, Python, Go, Java

Package	Version	Description
@vivantel/virage-embedder-openai		OpenAI-compatible embedder (OpenAI, Azure, GitHub Models, Ollama)
@vivantel/virage-embedder-fastembed		Fast local ONNX embeddings via FastEmbed
@vivantel/virage-embedder-transformers		Local embeddings via @huggingface/transformers

Package	Version	Description
@vivantel/virage-store-lancedb		LanceDB vector store (embedded, file-based)
@vivantel/virage-store-qdrant		Qdrant vector store (local and cloud)
@vivantel/virage-store-postgres		PostgreSQL + pgvector vector store
@vivantel/virage-store-chromadb		ChromaDB vector store (local or hosted)

Package	Version	Description
@vivantel/virage-reranker-cross-encoder		Local cross-encoder re-ranker (ONNX, no API key required)
@vivantel/virage-reranker-llm		LLM-based re-ranker using the Anthropic API

Package	Version	Description
@vivantel/virage-agent-core		Base interfaces and utilities for agent plugins
@vivantel/virage-agent-claude		Claude Code agent plugin
@vivantel/virage-agent-copilot		GitHub Copilot agent plugin
@vivantel/virage-agent-codex		OpenAI Codex agent plugin
@vivantel/virage-agent-antigravity		Google Antigravity agent plugin
@vivantel/virage-skills		AI agent skills for Claude Code, Copilot, and Codex

Package	Version	Description
@vivantel/virage-git-isomorphic		Pure-JS git source using isomorphic-git (no subprocess spawning)

Install the CLI globally (requires Node.js 20+).

On Unix / macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/vivantel/virage/master/scripts/install.sh | bash

On Windows (PowerShell):

irm https://raw.githubusercontent.com/vivantel/virage/master/scripts/install.ps1 | iex

Or directly with npm:

npm install -g @vivantel/virage

Set up a project (interactive wizard generates virage.config.json):

cd my-project
virage init

Index your codebase:

virage index

Query the index:

virage query "how does authentication work?"

Or start the MCP stdio server for AI assistant integration:

virage serve

Check health and diagnose configuration problems:

virage status          # quick health summary
virage doctor          # full diagnostic with fix hints

Generate shell completions:

virage completions bash >> ~/.bashrc   # or zsh / fish / powershell

All commands support --format human|json|quiet and --no-color.

All configuration lives in virage.config.json. Environment variables expand at runtime — use ${VAR} syntax for secrets (e.g. "apiKey": "${OPENAI_API_KEY}"). Example config:

{
  "providers": {
    "embedder": {
      "builtin": "onnx",
      "options": {
        "source": { "model": "Xenova/all-MiniLM-L6-v2", "cacheDir": ".virage/model-cache" },
        "dimensions": 384
      }
    },
    "vectorStore": {
      "builtin": "lancedb",
      "options": { "uri": ".virage/lancedb" }
    }
  },
  "fileSets": [
    {
      "name": "docs",
      "include": ["docs/**/*.md", "**/*.md"],
      "ignore": ["**/node_modules/**"],
      "chunkers": [{ "builtin": "md" }]
    },
    {
      "name": "code",
      "include": ["src/**/*.ts", "src/**/*.py", "src/**/*.go"],
      "chunkers": [{ "builtin": "lang" }]
    }
  ],
  "search": { "hybrid": true, "hybridAlpha": 0.6 },
  "pipeline": { "batchSize": 20 }
}

Run virage init to generate a config interactively. Run virage validate to check it. See docs/cli/config.md for the full config reference.

All commands have short aliases. Run virage --help to see the full list.

virage [options] [command]

Options:
  -v, --verbose   Increase verbosity (stackable: -v, -vv, -vvv…)
  --no-banner     Suppress the startup banner (also: VIRAGE_NO_BANNER=1)
  -h, --help      Display help

Commands:
  index     (i)     Run the indexing pipeline
  init              Generate virage.config.json interactively
  update    (up)    Update virage ecosystem packages and resync agent configs
  check     (c)     Validate embedder config matches the stored index
  validate  (val)   Validate config without running the pipeline
  dashboard (d)     Start the local monitoring dashboard
  query     (q)     Semantic search over the indexed knowledge base
  quality   (ql)    Quality system: self-assessment, retrieval eval, benchmarks
  report    (r)     Show observability report from pipeline runs
  chunks            Chunk analysis tools
  viz               Visualization tools
  store             Vector store diagnostics
  telemetry         Manage telemetry settings and data
  install-hooks (hooks)  Install git hooks for auto-indexing
  uninstall   (un)  Remove virage artefacts and optionally the global CLI

See docs/cli/ for per-command reference.

virage index flags:

Options:
  -c, --config <path>     Config file (default: virage.config.json)
  -f, --force             Force full rebuild
  --no-upload             Skip upload to vector store
  --dry-run               Show what would change without uploading
  --watch                 Re-run pipeline on file changes
  (Use VIRAGE_DIR env var to override the .virage/ directory path)

virage quality (ql) — 26-metric pipeline self-assessment, retrieval eval, and performance benchmarks. See docs/quality.md for the full command reference.

Chunkers split source files into embeddable chunks. PDF, Markdown, DOCX, LaTeX, and multi-language chunking are built into @vivantel/virage — no separate install needed. Configure chunkers per file set using the builtin: key:

{
  "fileSets": [
    {
      "name": "docs",
      "include": ["**/*.md"],
      "chunkers": [{ "builtin": "md" }]
    },
    {
      "name": "code",
      "include": ["src/**/*.ts", "src/**/*.py"],
      "chunkers": [{ "builtin": "lang" }]
    }
  ]
}

Plugin-based chunkers extend the built-in set:

The embedder model and dimensions are tracked in the index. Changing either value automatically invalidates the cache and triggers a full re-embed on the next run.

Optional post-retrieval re-rankers re-score results for higher precision. Configured under providers.reranker in virage.config.json. When set, virage query applies reranking automatically — no extra flag needed.

Fine-tune indexing performance via the pipeline block in virage.config.json:

Local embedder models are cached in ~/.virage/models (overridable with VIRAGE_GLOBAL_DIR).

Use --force to discard the incremental cache and re-index everything from scratch.
Use -v / -vv / -vvv with virage index to increase log verbosity for debugging.

Agent plugins configure your coding assistant to use Virage for semantic search and context retrieval. Select one or more agents during virage init — the plugin is installed and configured automatically.

Run virage update to resync agent configs after upgrading plugin packages.

Launch the web monitoring UI to inspect chunk distribution, embedding anomalies, pipeline status, search, and experiments:

virage dashboard        # start on port 3000
virage dashboard --port 8080 --verbose  # custom port + request logging

See docs/USE_CASES.md for detailed scenarios:

• Onboarding new engineers with instant codebase search
• AI code review with full codebase context, not just the diff
• Keeping docs in sync with code via post-commit hooks
• Zero-cost local RAG for private or air-gapped codebases
• Multi-strategy indexing for mixed-content monorepos
• Measuring retrieval quality before and after config changes
• Cost-bounded CI indexing — only changed files are re-embedded
• Sharing project knowledge across Claude Code, Copilot, and Codex simultaneously

Planned features:

• Cross-file import graph indexing — so agents can follow call chains across files, not just within them
• Cost estimator (virage estimate) — projected token count and API cost before any embedding call
• PR diff mode — index only the files changed in a pull request, in an isolated namespace
• Semantic deduplication — skip near-duplicate chunks before embedding to reduce index bloat
• GitHub Actions integration — official vivantel/virage-action composite action for CI-driven indexing

See CONTRIBUTING.md for setup instructions, commit conventions, and how to open a PR.

MIT