V.I.S.O.R.

Your AI coding assistant wastes time reading the wrong files. V.I.S.O.R. fixes that.

Visual Intelligence System for Orchestrated Reasoning

V.I.S.O.R. is a smart helper for your AI coding assistant. It reads your code, understands how files are connected, and gives your AI exactly the right context — so it spends less time searching and more time solving.

It works with Antigravity, VS Code, Cursor, Claude Code, and Windsurf.

💬 What Can You Do With It?

Just talk to your AI agent like normal. V.I.S.O.R. works behind the scenes to find the right code automatically.

Find a bug

"Find the code related to the login crash"

Without V.I.S.O.R., your AI reads 20+ files blindly. With V.I.S.O.R., it gets the 3–5 most relevant files instantly.

Understand your code

"Explain how authentication works in this project"

V.I.S.O.R. traces the full auth flow across files — showing your AI exactly which functions call which, and in what order.

Refactor safely

"What files would break if I change the database client?"

V.I.S.O.R. runs an impact analysis and shows every file that depends on the one you're changing.

Check for stale context

"Are the files you read earlier still up to date?"

V.I.S.O.R. checks file hashes and warns your AI if something changed since it last looked.

🚀 Install (2 minutes)

Step 1: Install and configure deliberately

Install the CLI, then review and add the displayed MCP entry to the client configuration you choose. V.I.S.O.R. does not edit IDE configuration files automatically.

uvx visor-mcp --help
visor-mcp init  # prints a configuration entry; it does not write one

Note: Claude Code handles installation natively via claude mcp add visor -- uvx visor-mcp.

{
  "mcpServers": {
    "visor": {
      "command": "uvx",
      "args": ["visor-mcp"]
    }
  }
}

{
  "servers": {
    "visor": {
      "command": "uvx",
      "args": ["visor-mcp"]
    }
  }
}

{
  "mcpServers": {
    "visor": {
      "command": "uvx",
      "args": ["visor-mcp"]
    }
  }
}

Prerequisite: You need uv installed. uvx (included with uv) handles virtual environments and dependencies automatically — no manual setup needed.

Step 2 (Optional): Install the 3D HUD Extension

Search for "V.I.S.O.R. HUD" in your editor's extension panel, or install from Open VSX. This gives you a live 3D visualization of your codebase graph right in the sidebar.

🤔 Evaluate It in Your Workflow

V.I.S.O.R. provides an AST-backed index, dependency graph, and focused context retrieval. Its effect on task success, latency, and context size depends on the repository, agent, model, and prompt. Use the reproducible paired-agent protocol in benchmarks/ before making performance claims.

✨ Key Features

🧠 Smart Context Engine

The heart of V.I.S.O.R. When your AI asks "find code related to X", it doesn't just search by text — it thinks:

• Understands your question — Detects if you're fixing a bug, exploring, or refactoring, and adjusts accordingly
• Scores code 5 different ways — Combines meaning similarity, name matching, file proximity, code connections, and how recently the file was changed
• Explains its choices — Every code snippet includes a plain-English reason for why it was picked
• Saves tokens — Reports estimated context sizes for the current retrieval result

⚡ Built-in Skills

Pre-built strategies that change how V.I.S.O.R. finds code. Think of them as "modes":

You can also create your own custom skills.

🔍 Code Understanding

V.I.S.O.R. reads your code structure (classes, functions, imports) in 9 languages:

Want more? Adding a new language is ~15 lines of code. See CONTRIBUTING.md.

📊 3D HUD (VS Code / Antigravity)

A real-time interactive graph of your codebase — right in your editor sidebar. Shows:

• Your code as connected nodes you can explore
• Live stats: how many tokens your AI is using, how many files are indexed
• Drift alerts when files change under your AI

⚠️ Drift Detection

Knows when your AI is looking at outdated code. Compares file hashes and warns before your AI makes decisions on stale information.

📦 Example: Finding a Bug

$ visor fix "authentication crash"

============================================================
  V.I.S.O.R. Context Intelligence Engine
============================================================
  Query:  authentication crash
  Intent: BUG_FIX
  Skill:  bug-fixer
────────────────────────────────────────────────────────────
  Tokens without V.I.S.O.R.: 11,400
  Tokens with V.I.S.O.R.:    2,180
  Reduction:                  80.9%
────────────────────────────────────────────────────────────
  Selected 4 nodes (truncated=False):

  [2.85]  src/auth/jwt.py:verify_token
          → Matched query token in symbol name
          → Co-located in same file as top semantic hit
          → Recently modified file (boosted)

  [2.12]  src/auth/middleware.py:auth_guard
          → Reachable via dependency chain
          → Semantic similarity (score: 0.375)

============================================================

What happened: This example illustrates the shape of a focused context response; its token estimates are not benchmark results.

🛠️ CLI Commands

You can also use V.I.S.O.R. from the terminal:

visor fix "login crash on null user"         # Find bug-related code
visor explain "database client"              # Understand how a module works
visor context "how is auth handled"          # General code search
visor trace src/auth.py src/db/client.py     # Show how two files are connected
visor drift                                  # Check for changed files

🛠️ MCP Tools (for AI Agents)

V.I.S.O.R. gives your AI agent 17 tools across 5 categories. Your AI uses these automatically — you don't need to call them manually.

See docs/MCP_TOOLS.md for the full API reference.

📚 Documentation

🤝 Contributing

V.I.S.O.R. welcomes contributions! The easiest way to start is by adding a new language — it's ~15 lines and a great first issue.

git clone https://github.com/dibun75/visor.git
cd visor && uv sync --dev
uv run pytest tests/ -v

See CONTRIBUTING.md for the full guide.

🌐 Works With

License

MIT © Arunav Mandal