V.I.S.O.R.

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

CI PyPI Open VSX License: MIT Python

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: The One-Command Install

You no longer need to manually copy and paste JSON configuration files. V.I.S.O.R. includes an interactive setup wizard that automatically configures your IDE.

# This will auto-detect Cursor, VS Code, or Antigravity and set up the MCP connection
uvx visor-mcp init

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.

🤔 The Proof: Why You Need V.I.S.O.R.

Every time your AI agent searches for context natively, it relies on brute-force text search (grep or ripgrep). This wastes tokens, misses dependencies, and hallucinates context.

Here is what happens when you ask an AI to "refactor the database client":

✨ 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 — Shows you exactly how many tokens it saved vs. a naive approach

⚡ 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: Instead of your AI reading every file in the project, V.I.S.O.R. found the 4 most relevant functions and saved 80% of the tokens.

🛠️ 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