Vexor Semantic Code Search
Find files by intent, not exact text — instantly locate where something is implemented, loaded, or defined in a medium or large repo.
The skill only performs local file search with no destructive defaults; documentation explicitly rejects sensitive fields (api_key etc.) in project config via a whitelist, with tests locking that behavior, giving fairly transparent data flow. Deducted for: install docs guide users to set an API key into global config with incomplete key-handling/rollback guidance; publisher is an unverified third party.
The repo has real CI (pytest + ruff) and committed tests covering key CLI paths (porcelain contract, JSON output, content truncation, invalid-config errors), which justifies exceeding the static cap of 10. Deducted for: tests are mostly unit tests with mocked backends; end-to-end semantic search is covered only via a DummyBackend, so real embedding/indexing behavior and failure feedback remain unverified by execution.
Trigger scenarios are clear (intent-based file discovery in medium/large repos), with good mode selection, troubleshooting and boundaries; name matches description. Deducted for: default reliance on remote embedding providers (openai/gemini etc.) raises mainland-China reachability concerns; the local model path requires downloading from HuggingFace with weak environment-fit evidence; limits on query quality are not disclosed.
SKILL.md is well structured with sensible progressive disclosure (install details in references/), MIT license is clear, and there is an identifiable maintainer plus release/changelog workflow. Deducted for: the skill file itself has no version/changelog, and bundling via pip couples skill version to CLI version opaquely; some features require jumping to external docs.
The core task path is complete; --content and --format return source text directly, reducing follow-up file reads; examples are concrete and community listings corroborate usage. Deducted for: static review cannot verify actual retrieval quality/accuracy; first query requires indexing and provider setup, so cold-start cost is relatively high for light users.
Auditable primary material exists: CI workflows, test code, config-whitelist tests, and third-party community listings (Ruan Yifeng weekly, awesome lists). Deducted for: no independent execution reproduction; semantic-quality claims rest on a demo video and sample output, and third-party evidence is listing rather than technical verification.
- Default remote embedding providers (openai/gemini etc.) may be unreachable from mainland China; consider configuring a local model (vexor[local]) or verifying network reachability
- Remote providers require an API key stored in global config; handle secrets carefully and minimize scope
- This is a static review with nothing executed; retrieval quality, indexing time and failure feedback are documentation claims, not independently verified
- The skill is bundled with the pip package, coupling skill content to CLI version; check changes when upgrading
What does this skill do, and when should you use it?
Vexor is a semantic search engine for files and code that builds reusable vector indexes, letting you search by what a file does instead of remembering its name or location. It ships as a CLI, a Python API, and an MCP server, with configurable embedding and reranking providers and full offline support via local models. The repo includes an Agent Skill (vexor-cli) that teaches shell-capable agents like Claude Code and Codex to drive the full CLI for semantic file discovery. MIT-licensed, Python 3.10+, installable via pip or as a standalone binary.
Chunks repository files according to a chosen mode (name/head/brief/code/outline/full) and builds vector indexes cached in memory or under .vexor/. It accepts natural-language queries and returns similarity-ranked file paths, line numbers, and snippet previews; --content or --format also prints the matching source text directly. The first search auto-indexes, and vexor index can warm up explicitly. It respects gitignore rules, .vexorignore, extension filters, and exclude patterns; configuration lives in ~/.vexor/config. (global) plus a restricted-field .vexor/config. (per project).
- A developer who forgot where a feature lives in a large repo wants to find it with a phrase like "where JWT claims are validated".
- Claude Code / Codex users want their agent to explore an unfamiliar codebase with vexor search instead of manual directory browsing.
- A docs writer searches Markdown by headings/sections with --mode outline.
- Engineers who need scriptable output pipe results using --format porcelain or porcelain-z.
- Offline teams configure local embedding models for fully offline semantic search.
- Users of MCP clients (Cursor, Windsurf, Zed, ...) wire semantic search in as a native tool via vexor mcp.
What are this skill's strengths and limitations?
- Intent-based file discovery removes the need for grep patterns and directory traversal.
- One install, three interfaces: CLI, Python API, and MCP server — serving both humans and AI agents.
- Multiple index modes let you pick the fastest or highest-recall strategy, including code-aware chunking.
- Fully offline capable (local embedding models) with per-project config isolation.
- --rerank hybrid fixes weak results on exact-identifier queries.
- Requires configuring an embedding provider and API key (or a local model) — there is initial setup cost.
- The first search indexes files and may take about a minute; long symbols split into chunks can yield content ranges offset from result line numbers.
- Disk-backed index caches can go stale in fast-changing repos, requiring vexor index re-runs.
- No benchmarks provided; quantitative comparison against traditional tools like grep is absent.
How do you install this skill?
1) Install vexor: pip install vexor (also works with pipx, uv), or download the standalone binary from GitHub Releases (no Python required). 2) Run vexor init for guided setup (set provider and API key, or use env vars like VEXOR_API_KEY). 3) For the Claude Code Agent Skill: vexor install --skills claude (Codex: vexor install --skills codex). Skill source lives at plugins/vexor/skills/vexor-cli/SKILL.md in the repo.
How do you use this skill?
The skill instructs agents to prefer vexor for intent-based file discovery. Typical commands: vexor "api client config" (defaults to current directory); vexor search "config loader" --path . --mode code --ext .py (code mode); vexor search "user authentication flow" --path docs --mode outline --ext .md --format porcelain. Add --content to read the matching source in the same call, skipping follow-up file reads. If exact-identifier searches are weak, run vexor config --rerank hybrid to fuse lexical and semantic matching. Diagnose configuration with vexor doctor or vexor config --show.
How does this skill compare with similar options?
The README positions the Agent Skill and MCP server as two access paths to the same core capability (the skill drives the full CLI; the MCP server exposes native tools) and recommends picking one per agent. No comparison with other specific search tools is made in the source.