Skip to main content
Vexor

Vexor

Python PyPI CI Codecov CodeRabbit Pull Request Reviews License Ask DeepWiki


Vexor is a semantic search engine that builds reusable indexes over files and code. It supports configurable embedding and reranking providers, and exposes the same core through a Python API, a CLI tool, and an MCP server.

Vexor Demo Video

Vexor has been recognized and featured by the community:

Why Vexor?

When you remember what a file does but forget its name or location, Vexor finds it instantly—no grep patterns or directory traversal needed.

Designed for both humans and AI coding assistants, enabling semantic file discovery in autonomous agent workflows.

Install

Download standalone binary from releases (no Python required), or:

pip install vexor  # also works with pipx, uv

Quick Start

vexor init

The wizard also runs automatically before the first interactive operational command when no config exists. Configuration-management (vexor config), MCP, help, and version commands run directly.

vexor "api client config"  # defaults to search current directory
# or explicit path:
vexor search "api client config" --path ~/projects/demo --top 5
# in-memory search only:
vexor search "api client config" --no-cache 

Vexor auto-indexes on first search. Example output:

Vexor semantic file search results
──────────────────────────────────
#   Similarity   File path                       Lines   Preview
1   0.923        ./src/config_loader.py          -       config loader entrypoint
2   0.871        ./src/utils/config_parse.py     -       parse config helpers
3   0.809        ./tests/test_config_loader.py   -       tests for config loader

2. Explicit Index (Optional)

vexor index  # indexes current directory
# or explicit path:
vexor index --path ~/projects/demo --mode code

Useful for CI warmup or when auto_index is disabled.

Python API

Vexor can also be imported and used directly from Python:

from vexor import index, search

index(path=".", mode="head")
response = search("config loader", path=".", mode="name")

for hit in response.results:
    print(hit.path, hit.score)

Configuration follows the same global and project-level resolution as the CLI. For runtime overrides, cache controls, and per-call options, see docs/api/python.md.

AI Agent Skill

This repo includes a skill for AI agents to use Vexor effectively:

vexor install --skills claude  # Claude Code
vexor install --skills codex   # Codex

Skill source: plugins/vexor/skills/vexor-cli

MCP Server

vexor MCP server

Vexor ships a built-in MCP stdio server, so any MCP-capable agent can use semantic file search as a native tool:

claude mcp add vexor -- vexor mcp   # Claude Code
codex mcp add vexor -- vexor mcp    # Codex

Or configure manually in any MCP client, optionally supplying the API key and any config overrides via env (no vexor init needed):

{
  "mcpServers": {
    "vexor": {
      "command": "vexor",
      "args": ["mcp"],
      "env": {
        "VEXOR_API_KEY": "sk-...",
        "VEXOR_CONFIG_JSON": "{\"provider\": \"gemini\", \"rerank\": \"bm25\"}"
      }
    }
  }
}

The server exposes two tools: vexor_search (semantic file search, returning the matching source text so an agent rarely needs a follow-up file read) and vexor_index (explicit index warm-up). No extra dependencies are required. Vexor is listed on the official MCP registry as io.github.scarletkc/vexor. See docs/mcp.md for tool schemas, environment variables, and client setup details.

Configuration

vexor init                             # guided setup (recommended)
vexor config --set-api-key "YOUR_KEY"  # or env: VEXOR_API_KEY / OPENAI_API_KEY / ...
vexor config --set-provider openai     # default; also gemini/voyageai/custom/local
vexor config --rerank hybrid           # optional: fuse exact keyword + semantic ranking
vexor config --show                    # view effective settings and origins

Global config lives in ~/.vexor/config.json; the nearest <project>/.vexor/config.json can override a restricted set of behavior fields for that project. Non-secret fields can also be injected via VEXOR_CONFIG_JSON (useful for MCP clients and CI), and fully offline use is supported through local embedding models.

See docs/configuration.md for the complete reference: project config fields and precedence, all config commands, API keys and environment variables, rerank strategies (hybrid / BM25 / FlashRank / remote), remote vs local providers, embedding dimensions, and offline local model setup.

CLI Reference

Everyday usage fits in vexor "query", vexor search, and vexor index (see Quick Start). The full command table, common flags, index modes (--mode auto/name/head/brief/full/code/outline), .vexorignore files, project-local indexes (vexor index --local), cache behavior, and porcelain output format are documented in docs/cli.md.

Documentation

  • Configuration — providers, API keys, rerank, embedding dimensions, local models
  • CLI reference — commands, flags, index modes, cache behavior
  • MCP server — client setup, environment variables, tool schemas
  • Python API — programmatic usage
  • Collections API — database-backed text records and filtered search

Contributing

Contributions, issues, and PRs welcome! Commit messages and PR titles follow Conventional Commits (e.g. feat(mcp): add stdio server). Star if you find it helpful.

Star History

Star History Chart

License

MIT

Metadata

Release files for vexor 0.31.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vexor 0.31.0
File Size Uploaded Provenance Actions
vexor-0.31.0.tar.gz 147.7 kB With provenance Details for vexor-0.31.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vexor 0.31.0
File Interpreter ABI Platform Actions
vexor-0.31.0-py3-none-any.whl Python 3 none any Details for vexor-0.31.0-py3-none-any.whl

Total release size: 313.7 kB

Release files / vexor-0.31.0.tar.gz

Download URL vexor-0.31.0.tar.gz
Size 147.7 kB
Tags Source
SHA-256 checksum
How to use checksums
037012ffb75471c319f3775a322f9d425e07af8eb53c7fc7733ad926acc55109
BLAKE2b-256 checksum
How to use checksums
10fe1bdc45a067f64d9159e30ecb60081fcbbf697f1da75048a0106de0d3cdf7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / vexor-0.31.0-py3-none-any.whl

Download URL vexor-0.31.0-py3-none-any.whl
Size 166.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4133a62decceab2849d2f1e31fc559c9c8e14312d07e9d3f08b1392dd0127b4c
BLAKE2b-256 checksum
How to use checksums
d3ba0b2cd417fd3654c0a89f647fcbf96004eefd804f90d0ecdcab92ed9d7e43
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Security for vexor 0.31.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for vexor-0.31.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.31.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page