V.I.S.O.R.

V.I.S.O.R. is a local-first context engine for Codex, Claude Code, and other coding agents. It builds an AST-backed repository index and dependency graph, then returns focused code context with the files, symbols, and reasons behind each selection.

It works from the terminal, through the Agent Skill, or over MCP. Lexical retrieval is the default and runs offline. Semantic retrieval is optional. A VS Code / Open VSX HUD is optional and is not required for the CLI or MCP server.

Terminal demo

From a checkout of this repository:

uv run visor doctor
uv run visor index
uv run visor context "resolve local workspace project root"

Recorded from demo/terminal_demo.tape. The same take is also at docs/assets/terminal-demo.mp4.

If V.I.S.O.R. is useful in your workflow, consider starring the repository—it helps other coding-agent users discover it.

Related MCP server: cctx-mcp

Quick Start

Prerequisite: uv. uvx installs visor-mcp into a temporary environment.

# Check local/headless compatibility
uvx --from visor-mcp visor doctor

# Index the current repository
uvx --from visor-mcp visor index

# Retrieve focused context
uvx --from visor-mcp visor context \
  "where is workspace detection handled?"

visor init prints an MCP configuration entry for review. It does not edit IDE files.

Register the stdio server with Codex or Claude Code:

codex mcp add visor -- uvx visor-mcp
claude mcp add visor -- uvx visor-mcp

Cursor (~/.cursor/mcp.json):

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

VS Code (.vscode/mcp.json). The same file is the setup documented here for Antigravity:

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

Claude Desktop (claude_desktop_config.json):

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

Agent Skill

The Skill tells an agent to request V.I.S.O.R. context, treat the files, symbols, and reasons as leads, and verify those leads in the repository. Installing it does not guarantee that every client will select it automatically.

• Skill source: skills/visor-context/SKILL.md

• Install notes for Codex, Claude Code, and other clients: docs/AGENT_SKILL.md

Supported integrations

Any other MCP client can launch the same stdio command: uvx visor-mcp.

Measured pilot results

Three published pilots are in this repository. None is a universal token-reduction claim. All depend on the task, agent, model, cache behavior, and context. Provider token fields are not comparable across Codex and Claude Code. V.I.S.O.R. context was supplied as leads and had to be checked against the repository.

Adversarial retrieval misses, 2–3 November 2026

Four hidden-cause fixes, three repeats, Codex and Claude Code, native and V.I.S.O.R., produced 48 cells (24 native/V.I.S.O.R. pairs). Every V.I.S.O.R. initial context omitted the declared causal file and included an obvious API decoy, so initial gold-file recall was 0%. A patch counted as correct only when its behavioral check passed and it changed the causal file. Full figures: benchmarks/results/v1.4.2-adversarial-retrieval-summary.json.

Claude Code recovered the omitted causal file in all 12 V.I.S.O.R. runs. Codex recovered it in 8/12 V.I.S.O.R. runs; four Codex V.I.S.O.R. runs made behaviorally plausible edits in the decoy file instead. Codex also made three wrong-location edits without V.I.S.O.R. The one-run correctness difference is not evidence of a real advantage or disadvantage: this is a small synthetic suite, and the five discordant Codex pairs split 3 native-only to 2 V.I.S.O.R.-only. The result shows the failure mode exists and must be measured; it does not establish that focused context generally helps or hurts correctness.

Patch correctness, 31 October 2026

Three seeded fixes, three repeats, Codex and Claude Code, native and V.I.S.O.R., 36 paired cells. Every cell had its own detached worktree. A check command scored the patch after the agent. Deltas are V.I.S.O.R. minus native. Full figures: benchmarks/results/v1.2.1-patch-pilot-summary.json.

All 36 patches passed. The token and runtime intervals are wide and, except for Claude's two-token uncached input difference, include both directions. Claude's input_tokens value is the uncached remainder; cache-read tokens are a separate field and that paired interval also crosses zero. Codex does not report monetary cost. This does not show that V.I.S.O.R. saves a fixed share of tokens.

Diagnostic navigation, v1.2.0

The v1.2.0 diagnostic pilot compared native repository navigation with the same tasks plus V.I.S.O.R. context. Figures are from benchmarks/results/v1.2.0-diagnostic-pilot-summary.json. Paired intervals were recomputed from the preserved scored records.

Limitations:

• The navigation pilot does not measure patch correctness, refactoring quality, or task success.

• The patch and adversarial pilots use small synthetic fixtures, not representative production repositories.

• Timing and token counts are machine-, model-, provider-, plan-, and cache-dependent.

• Evidence recall is a heuristic, not human correctness review.

• These results are not proof that V.I.S.O.R. makes coding agents universally faster, cheaper, or better.

Protocol: benchmarks/README.md. Published-result notes: benchmarks/results/README.md.

Why V.I.S.O.R.

V.I.S.O.R. complements normal repository inspection, including an agent's own search. It adds a persistent local index the agent can query.

build_context classifies a query into an intent profile, can apply a built-in skill (bug-fixer, architecture-explainer, refactor-assistant, performance-optimizer), and returns a reason string for each selected node. Those reasons explain the score. They do not establish that the selection is sufficient for a code change.

Each context response also includes an internal size estimate: tokens for the full text of candidate files compared with tokens for the returned snippets. That estimate is not a measured change in agent token use.

Optional visual HUD

Prefer a visual graph? Install the optional V.I.S.O.R. HUD from Open VSX.

The HUD is a VS Code extension that draws the indexed graph and shows local telemetry. The MCP server and CLI do not need it.

Install V.I.S.O.R. HUD from the editor's extension view or Open VSX. Extension notes: src/visor/extension/README.md.

Local-first and privacy

• The index and dependency graph are stored locally, under ~/.visor/.

• Lexical retrieval works offline and does not download a model.

• Semantic mode is optional (visor --retrieval-mode semantic or VISOR_RETRIEVAL_MODE=semantic) and uses all-MiniLM-L6-v2, which may be downloaded on first use.

• V.I.S.O.R. itself does not require uploading the whole repository to a hosted V.I.S.O.R. service. The MCP server speaks stdio.

• Retrieved snippets are still passed to whichever coding agent the user has configured, subject to that provider's policies.

store_memory embeds the stored text with the semantic model. Lexical indexing does not.

Languages

Tree-sitter parsing covers nine languages. TSX uses the TypeScript grammar's TSX variant. It is not a tenth language.

Adding a language is a small parser change. See CONTRIBUTING.md.

CLI

visor doctor
visor index
visor status
visor init
visor context "how is auth handled"
visor fix "login crash on null user"
visor explain "database client"
visor trace src/visor/server.py src/visor/workspace.py
visor drift
visor feedback useful src/app.py --query "how is auth handled"
visor feedback list --json

visor feedback stores an explicit useful, irrelevant, or missing verdict for a file and query. V.I.S.O.R. can apply that feedback to similar future queries in the same workspace. It is not automatic learning, it does not change import or call edges, and visor feedback delete or visor feedback clear --yes removes it.

fix and explain call build_context with bug-fixer and architecture-explainer. Terminal details: docs/TERMINAL.md.

MCP tools

The server registers 21 tools in src/visor/tools/core.py and src/visor/server.py. get_visor_skill is an MCP prompt, not one of those tools. Clients do not have to call any of them automatically.

Reference: docs/MCP_TOOLS.md.

Documentation

Community

• Report a bug

• Request a feature

• Contributing

• Security reports

Please follow the Code of Conduct when participating.

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

License

MIT © Arunav Mandal