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 optional desktop frontend. Vexor Demo Video Vexor has been recognized and featured by the community: - Ruan Yifeng's Weekly (Issue 379) - A leading tech newsletter in the Chinese developer
Add this skill
npx mdskills install scarletkc/vexorProvides no actionable instructions or guidance for semantic file search functionality
1<div align="center">23<img src="https://raw.githubusercontent.com/scarletkc/vexor/refs/heads/main/assets/vexor.svg" alt="Vexor" width="35%" height="auto">45# Vexor67[](https://www.python.org/downloads/)8[](https://pypi.org/project/vexor/)9[](https://github.com/scarletkc/vexor/actions/workflows/publish.yml)10[](https://codecov.io/github/scarletkc/vexor)11[](https://github.com/scarletkc/vexor/blob/main/LICENSE)12[](https://deepwiki.com/scarletkc/vexor)1314</div>1516---1718**Vexor** is a semantic search engine that builds reusable indexes over files and code.19It supports configurable embedding and reranking providers, and exposes the same core through a Python API, a CLI tool, and an optional desktop frontend.2021<video src="https://github.com/user-attachments/assets/4d53eefd-ab35-4232-98a7-f8dc005983a9" controls="controls" style="max-width: 600px;">22 Vexor Demo Video23 </video>2425## Featured In2627Vexor has been recognized and featured by the community:2829- **[Ruan Yifeng's Weekly (Issue #379)](https://github.com/ruanyf/weekly/blob/master/docs/issue-379.md#ai-%E7%9B%B8%E5%85%B3)** - A leading tech newsletter in the Chinese developer community.30- **[Awesome Claude Skills](https://github.com/VoltAgent/awesome-claude-skills?tab=readme-ov-file#development-and-testing)** - Curated list of best-in-class skills for AI agents.3132## Why Vexor?3334When you remember what a file *does* but forget its name or location, Vexor finds it instantly—no grep patterns or directory traversal needed.3536Designed for both humans and AI coding assistants, enabling semantic file discovery in autonomous agent workflows.3738## Install3940Download standalone binary from [releases](https://github.com/scarletkc/vexor/releases) (no Python required), or:41```bash42pip install vexor # also works with pipx, uv43```4445## Quick Start4647### 0. Guided Setup (Recommended)48```bash49vexor init50```51The wizard also runs automatically on first use when no config exists.5253### 1. Search54```bash55vexor "api client config" # defaults to search current directory56# or explicit path:57vexor search "api client config" --path ~/projects/demo --top 558# in-memory search only:59vexor search "api client config" --no-cache60```6162Vexor auto-indexes on first search. Example output:63```64Vexor semantic file search results65──────────────────────────────────66# Similarity File path Lines Preview671 0.923 ./src/config_loader.py - config loader entrypoint682 0.871 ./src/utils/config_parse.py - parse config helpers693 0.809 ./tests/test_config_loader.py - tests for config loader70```7172### 2. Explicit Index (Optional)73```bash74vexor index # indexes current directory75# or explicit path:76vexor index --path ~/projects/demo --mode code77```78Useful for CI warmup or when `auto_index` is disabled.7980## Desktop App (Experimental)8182> The desktop app is experimental and not actively maintained.83> It may be unstable. For production use, prefer the CLI.84858687Download the desktop app from [releases](https://github.com/scarletkc/vexor/releases).8889## Python API9091Vexor can also be imported and used directly from Python:9293```python94from vexor import index, search9596index(path=".", mode="head")97response = search("config loader", path=".", mode="name")9899for hit in response.results:100 print(hit.path, hit.score)101```102103By default it reads `~/.vexor/config.json`. For runtime config overrides, cache104controls, and per-call options, see [`docs/api/python.md`](https://github.com/scarletkc/vexor/tree/main/docs/api/python.md).105106## AI Agent Skill107108This repo includes a skill for AI agents to use Vexor effectively:109110```bash111vexor install --skills claude # Claude Code112vexor install --skills codex # Codex113```114115Skill source: [`plugins/vexor/skills/vexor-cli`](https://github.com/scarletkc/vexor/raw/refs/heads/main/plugins/vexor/skills/vexor-cli/SKILL.md)116117## Configuration118119```bash120vexor config --set-provider openai # default; also supports gemini/voyageai/custom/local121vexor config --set-model text-embedding-3-small122vexor config --set-provider voyageai # uses voyage defaults when model/base_url are unset123vexor config --set-batch-size 0 # 0 = single request124vexor config --set-embed-concurrency 4 # parallel embedding requests125vexor config --set-extract-concurrency 4 # parallel file extraction workers126vexor config --set-extract-backend auto # auto|thread|process (default: auto)127vexor config --set-embedding-dimensions 1024 # optional, model/provider dependent128vexor config --clear-embedding-dimensions # reset to model default dimension129vexor config --set-auto-index true # auto-index before search (default)130vexor config --rerank bm25 # optional BM25 rerank for top-k results131vexor config --rerank flashrank # FlashRank rerank (requires optional extra)132vexor config --rerank remote # remote rerank via HTTP endpoint133vexor config --set-flashrank-model ms-marco-MultiBERT-L-12 # multilingual model134vexor config --set-flashrank-model # reset FlashRank model to default135vexor config --clear-flashrank # remove cached FlashRank models136vexor config --set-remote-rerank-url https://proxy.example.com/v1/rerank137vexor config --set-remote-rerank-model bge-reranker-v2-m3138vexor config --set-remote-rerank-api-key $VEXOR_REMOTE_RERANK_API_KEY # or env var139vexor config --clear-remote-rerank # clear remote rerank config140vexor config --set-base-url https://proxy.example.com # optional proxy141vexor config --clear-base-url # reset to official endpoint142vexor config --show # view current settings143```144145Rerank defaults to `off`. **It is highly recommended to configure the Reranker in advance to improve search accuracy.**146FlashRank requires `pip install "vexor[flashrank]"` and caches models under `~/.vexor/flashrank`.147148Config stored in `~/.vexor/config.json`.149150### Configure API Key151```bash152vexor config --set-api-key "YOUR_KEY"153```154Or via environment: `VEXOR_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_GENAI_API_KEY`, or `VOYAGE_API_KEY`.155156### Rerank157158Rerank reorders the semantic results with a secondary ranker. Candidate sizing uses159`clamp(int(--top * 2), 20, 150)`.160161Recommended defaults:162- Keep `off` unless you want extra precision.163- Use `bm25` for lightweight lexical boosts; it is fast and lightweight.164- BM25 uses a multilingual tokenizer (Bert pre-tokenizer), so it can handle CJK better.165- Use `flashrank` for stronger reranking (requires `pip install "vexor[flashrank]"` and166 downloads a model to `~/.vexor/flashrank`).167- Use `remote` to call a hosted reranker that accepts `{model, query, documents}` and168 returns ranked indexes.169- For Chinese or multi-language content, set `--set-flashrank-model ms-marco-MultiBERT-L-12`.170- If unset, FlashRank defaults to `ms-marco-TinyBERT-L-2-v2`.171172### Providers: Remote vs Local173174Vexor supports both remote API providers (`openai`, `gemini`, `voyageai`, `custom`) and a local provider (`local`):175- Remote providers use `api_key` and optional `base_url`.176- `voyageai` defaults to `https://api.voyageai.com/v1` when `base_url` is not set.177- `custom` is OpenAI-compatible and requires both `model` and `base_url`.178- Local provider ignores `api_key/base_url` and only uses `model` plus `local_cuda` (CPU/GPU switch).179180### Embedding Dimensions181182Embedding dimensions are optional. If unset, the provider/model default is used.183Custom dimensions are validated for:184- OpenAI `text-embedding-3-*`185- Voyage `voyage-3*` and `voyage-code-3*`186187```bash188vexor config --set-embedding-dimensions 1024189vexor config --clear-embedding-dimensions190```191192If you change dimensions after an index is built, rebuild the index:193194```bash195vexor index --path .196```197198### Local Model (Offline)199200Install the lightweight local backend:201```bash202pip install "vexor[local]"203```204205GPU backend (requires CUDA drivers):206```bash207pip install "vexor[local-cuda]"208```209210Download a local embedding model and auto-configure Vexor:211```bash212vexor local --setup --model intfloat/multilingual-e5-small213```214215Then use `vexor search` / `vexor index` as usual.216217Local models are stored in `~/.vexor/models` (clear with `vexor local --clean-up`).218219GPU (optional): install `onnxruntime-gpu` (or `vexor[local-cuda]`) and use `vexor local --setup --cuda` (or `vexor local --cuda`).220Switch back with `vexor local --cpu`.221222## Index Modes223224Control embedding granularity with `--mode`:225226| Mode | Description |227|------|-------------|228| `auto` | **Default.** Smart routing: Python/JS/TS → `code`, Markdown → `outline`, small files → `full`, large files → `head` |229| `name` | Embed filename only (fastest, zero content reads) |230| `head` | Extract first snippet for lightweight semantic context |231| `brief` | Extract high-frequency keywords from PRDs/requirements docs |232| `full` | Chunk entire content; long documents searchable end-to-end |233| `code` | AST-aware chunking by module/class/function boundaries for Python and JavaScript/TypeScript; other files fall back to `full` |234| `outline` | Chunk Markdown by heading hierarchy with breadcrumbs; non-`.md` falls back to `full` |235236## Cache Behavior237238Index cache keys derive from: `--path`, `--mode`, `--include-hidden`, `--no-recursive`, `--no-respect-gitignore`, `--ext`, `--exclude-pattern`.239240Keep flags consistent to reuse cache; changing flags creates a separate index.241242```bash243vexor config --show-index-all # list all cached indexes244vexor config --clear-index-all # clear all cached indexes245vexor index --path . --clear # clear index for specific path246```247248Re-running `vexor index` only re-embeds changed files; >50% changes trigger full rebuild.249250## Command Reference251252| Command | Description |253|---------|-------------|254| `vexor init` | Run the interactive setup wizard |255| `vexor QUERY` | Shortcut for `vexor search QUERY` |256| `vexor search QUERY --path PATH` | Semantic search (auto-indexes if needed) |257| `vexor index --path PATH` | Build/refresh index manually |258| `vexor config --show` | Display current configuration |259| `vexor config --clear-flashrank` | Remove cached FlashRank models under `~/.vexor/flashrank` |260| `vexor local --setup [--model MODEL]` | Download a local model and set provider to `local` |261| `vexor local --clean-up` | Remove local model cache under `~/.vexor/models` |262| `vexor local --cuda` | Enable CUDA for local embeddings (requires `onnxruntime-gpu`) |263| `vexor local --cpu` | Disable CUDA and use CPU for local embeddings |264| `vexor install --skills claude` | Install Agent Skill for Claude Code |265| `vexor install --skills codex` | Install Agent Skill for Codex |266| `vexor doctor` | Run diagnostic checks (command, config, cache, API key, API connectivity) |267| `vexor update [--upgrade] [--pre]` | Check for new version (optionally upgrade; `--pre` includes pre-releases) |268| `vexor feedback` | Open GitHub issue form (or use `gh`) |269| `vexor alias` | Print a shell alias for `vx` and optionally apply it |270271### Common Flags272273| Flag | Description |274|------|-------------|275| `--path PATH` | Target directory (default: current working directory) |276| `--mode MODE` | Index mode (`auto`/`name`/`head`/`brief`/`full`/`code`/`outline`) |277| `--top K` / `-k` | Number of results (default: 5) |278| `--ext .py,.md` / `-e` | Filter by extension (repeatable) |279| `--exclude-pattern PATTERN` | Exclude paths by gitignore-style pattern (repeatable; `.js` treated as `**/*.js`) |280| `--include-hidden` / `-i` | Include hidden files |281| `--no-recursive` / `-n` | Don't recurse into subdirectories |282| `--no-respect-gitignore` | Include gitignored files |283| `--format porcelain` | Script-friendly TSV output |284| `--format porcelain-z` | NUL-delimited output |285| `--no-cache` | In-memory only; do not read/write index cache |286287Porcelain output fields: `rank`, `similarity`, `path`, `chunk_index`, `start_line`, `end_line`, `preview` (line fields are `-` when unavailable).288289## Documentation290291See [docs](https://github.com/scarletkc/vexor/tree/main/docs) for more details.292293## Contributing294295Contributions, issues, and PRs welcome! Star if you find it helpful.296297## Star History298299[](https://www.star-history.com/#scarletkc/vexor&type=date&legend=top-left)300301## License302303[MIT](http://github.com/scarletkc/vexor/blob/main/LICENSE)304
Full transparency — inspect the skill content before installing.