V.I.S.O.R.

Local-first context retrieval for Codex, Claude Code, and terminal coding agents.

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.

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

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

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

{
  "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

Two published pilots are in this repository. Neither is a universal token-reduction claim. Both 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.

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 pilot is three small fixtures, not a general coding benchmark.
• 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

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.

Current 1280×720 capture generated from this repository's real get_architecture_map, get_telemetry, and build_context outputs. The token panel is V.I.S.O.R.'s local byte-based estimate, not measured agent usage. Reproduce it with node demo/capture_hud.mjs.

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