{"id":34423190,"url":"https://github.com/scarletkc/vexor","last_synced_at":"2026-04-01T20:45:27.853Z","repository":{"id":323307842,"uuid":"1092747695","full_name":"scarletkc/vexor","owner":"scarletkc","description":"A semantic search engine for files and code.","archived":false,"fork":false,"pushed_at":"2026-03-06T17:20:07.000Z","size":9829,"stargazers_count":205,"open_issues_count":2,"forks_count":11,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-06T20:52:19.364Z","etag":null,"topics":["ai","claude","cli","codex","desktop-app","electron","embeddings","gui","python","search","skills","terminal","vector","vue"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/vexor/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scarletkc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-09T08:18:11.000Z","updated_at":"2026-03-06T17:20:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/scarletkc/vexor","commit_stats":null,"previous_names":["scarletkc/vexor"],"tags_count":38,"template":false,"template_full_name":null,"purl":"pkg:github/scarletkc/vexor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scarletkc%2Fvexor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scarletkc%2Fvexor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scarletkc%2Fvexor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scarletkc%2Fvexor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scarletkc","download_url":"https://codeload.github.com/scarletkc/vexor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scarletkc%2Fvexor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291795,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","cli","codex","desktop-app","electron","embeddings","gui","python","search","skills","terminal","vector","vue"],"created_at":"2025-12-21T10:00:36.162Z","updated_at":"2026-04-01T20:45:27.835Z","avatar_url":"https://github.com/scarletkc.png","language":"Python","funding_links":[],"categories":["Sponsors ❤️","Knowledge \u0026 Memory"],"sub_categories":["Community Skills"],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://raw.githubusercontent.com/scarletkc/vexor/refs/heads/main/assets/vexor.svg\" alt=\"Vexor\" width=\"35%\" height=\"auto\"\u003e\n\n# Vexor\n\n[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)\n[![PyPI](https://img.shields.io/pypi/v/vexor.svg)](https://pypi.org/project/vexor/)\n[![CI](https://img.shields.io/github/actions/workflow/status/scarletkc/vexor/publish.yml?branch=main)](https://github.com/scarletkc/vexor/actions/workflows/publish.yml)\n[![Codecov](https://img.shields.io/codecov/c/github/scarletkc/vexor/main)](https://codecov.io/github/scarletkc/vexor)\n[![License](https://img.shields.io/github/license/scarletkc/vexor.svg)](https://github.com/scarletkc/vexor/blob/main/LICENSE)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/scarletkc/vexor)\n\n\u003c/div\u003e\n\n---\n\n**Vexor** is a semantic search engine that builds reusable indexes over files and code.\nIt supports configurable embedding and reranking providers, and exposes the same core through a Python API, a CLI tool, and an optional desktop frontend.\n\n\u003cvideo src=\"https://github.com/user-attachments/assets/4d53eefd-ab35-4232-98a7-f8dc005983a9\" controls=\"controls\" style=\"max-width: 600px;\"\u003e\n      Vexor Demo Video\n    \u003c/video\u003e\n\n## Featured In\n\nVexor has been recognized and featured by the community:\n\n- **[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.\n- **[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.\n\n## Why Vexor?\n\nWhen you remember what a file *does* but forget its name or location, Vexor finds it instantly—no grep patterns or directory traversal needed.\n\nDesigned for both humans and AI coding assistants, enabling semantic file discovery in autonomous agent workflows.\n\n## Install\n\nDownload standalone binary from [releases](https://github.com/scarletkc/vexor/releases) (no Python required), or:\n```bash\npip install vexor  # also works with pipx, uv\n```\n\n## Quick Start\n\n### 0. Guided Setup (Recommended)\n```bash\nvexor init\n```\nThe wizard also runs automatically on first use when no config exists.\n\n### 1. Search\n```bash\nvexor \"api client config\"  # defaults to search current directory\n# or explicit path:\nvexor search \"api client config\" --path ~/projects/demo --top 5\n# in-memory search only:\nvexor search \"api client config\" --no-cache \n```\n\nVexor auto-indexes on first search. Example output:\n```\nVexor semantic file search results\n──────────────────────────────────\n#   Similarity   File path                       Lines   Preview\n1   0.923        ./src/config_loader.py          -       config loader entrypoint\n2   0.871        ./src/utils/config_parse.py     -       parse config helpers\n3   0.809        ./tests/test_config_loader.py   -       tests for config loader\n```\n\n### 2. Explicit Index (Optional)\n```bash\nvexor index  # indexes current directory\n# or explicit path:\nvexor index --path ~/projects/demo --mode code\n```\nUseful for CI warmup or when `auto_index` is disabled.\n\n## Desktop App (Experimental)\n\n\u003e The desktop app is experimental and not actively maintained.\n\u003e It may be unstable. For production use, prefer the CLI.\n\n![GUI](https://raw.githubusercontent.com/scarletkc/vexor/refs/heads/main/assets/gui_demo.png)\n\nDownload the desktop app from [releases](https://github.com/scarletkc/vexor/releases).\n\n## Python API\n\nVexor can also be imported and used directly from Python:\n\n```python\nfrom vexor import index, search\n\nindex(path=\".\", mode=\"head\")\nresponse = search(\"config loader\", path=\".\", mode=\"name\")\n\nfor hit in response.results:\n    print(hit.path, hit.score)\n```\n\nBy default it reads `~/.vexor/config.json`. For runtime config overrides, cache\ncontrols, and per-call options, see [`docs/api/python.md`](https://github.com/scarletkc/vexor/tree/main/docs/api/python.md).\n\n## AI Agent Skill\n\nThis repo includes a skill for AI agents to use Vexor effectively:\n\n```bash\nvexor install --skills claude  # Claude Code\nvexor install --skills codex   # Codex\n```\n\nSkill source: [`plugins/vexor/skills/vexor-cli`](https://github.com/scarletkc/vexor/raw/refs/heads/main/plugins/vexor/skills/vexor-cli/SKILL.md)\n\n## Configuration\n\n```bash\nvexor config --set-provider openai          # default; also supports gemini/voyageai/custom/local\nvexor config --set-model text-embedding-3-small\nvexor config --set-provider voyageai        # uses voyage defaults when model/base_url are unset\nvexor config --set-batch-size 0             # 0 = single request\nvexor config --set-embed-concurrency 4       # parallel embedding requests\nvexor config --set-extract-concurrency 4     # parallel file extraction workers\nvexor config --set-extract-backend auto      # auto|thread|process (default: auto)\nvexor config --set-embedding-dimensions 1024 # optional, model/provider dependent\nvexor config --clear-embedding-dimensions    # reset to model default dimension\nvexor config --set-auto-index true          # auto-index before search (default)\nvexor config --rerank bm25                  # optional BM25 rerank for top-k results\nvexor config --rerank flashrank             # FlashRank rerank (requires optional extra)\nvexor config --rerank remote                # remote rerank via HTTP endpoint\nvexor config --set-flashrank-model ms-marco-MultiBERT-L-12  # multilingual model\nvexor config --set-flashrank-model          # reset FlashRank model to default\nvexor config --clear-flashrank              # remove cached FlashRank models\nvexor config --set-remote-rerank-url https://proxy.example.com/v1/rerank\nvexor config --set-remote-rerank-model bge-reranker-v2-m3\nvexor config --set-remote-rerank-api-key $VEXOR_REMOTE_RERANK_API_KEY  # or env var\nvexor config --clear-remote-rerank          # clear remote rerank config\nvexor config --set-base-url https://proxy.example.com  # optional proxy\nvexor config --clear-base-url               # reset to official endpoint\nvexor config --show                         # view current settings\n```\n\nRerank defaults to `off`. **It is highly recommended to configure the Reranker in advance to improve search accuracy.**\nFlashRank requires `pip install \"vexor[flashrank]\"` and caches models under `~/.vexor/flashrank`.\n\nConfig stored in `~/.vexor/config.json`.\n\n### Configure API Key\n```bash\nvexor config --set-api-key \"YOUR_KEY\"\n```\nOr via environment: `VEXOR_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_GENAI_API_KEY`, or `VOYAGE_API_KEY`.\n\n### Rerank\n\nRerank reorders the semantic results with a secondary ranker. Candidate sizing uses\n`clamp(int(--top * 2), 20, 150)`.\n\nRecommended defaults:\n- Keep `off` unless you want extra precision.\n- Use `bm25` for lightweight lexical boosts; it is fast and lightweight.\n- BM25 uses a multilingual tokenizer (Bert pre-tokenizer), so it can handle CJK better.\n- Use `flashrank` for stronger reranking (requires `pip install \"vexor[flashrank]\"` and\n  downloads a model to `~/.vexor/flashrank`).\n- Use `remote` to call a hosted reranker that accepts `{model, query, documents}` and\n  returns ranked indexes.\n- For Chinese or multi-language content, set `--set-flashrank-model ms-marco-MultiBERT-L-12`.\n- If unset, FlashRank defaults to `ms-marco-TinyBERT-L-2-v2`.\n\n### Providers: Remote vs Local\n\nVexor supports both remote API providers (`openai`, `gemini`, `voyageai`, `custom`) and a local provider (`local`):\n- Remote providers use `api_key` and optional `base_url`.\n- `voyageai` defaults to `https://api.voyageai.com/v1` when `base_url` is not set.\n- `custom` is OpenAI-compatible and requires both `model` and `base_url`.\n- Local provider ignores `api_key/base_url` and only uses `model` plus `local_cuda` (CPU/GPU switch).\n\n### Embedding Dimensions\n\nEmbedding dimensions are optional. If unset, the provider/model default is used.\nCustom dimensions are validated for:\n- OpenAI `text-embedding-3-*`\n- Voyage `voyage-3*` and `voyage-code-3*`\n\n```bash\nvexor config --set-embedding-dimensions 1024\nvexor config --clear-embedding-dimensions\n```\n\nIf you change dimensions after an index is built, rebuild the index:\n\n```bash\nvexor index --path .\n```\n\n### Local Model (Offline)\n\nInstall the lightweight local backend:\n```bash\npip install \"vexor[local]\"\n```\n\nGPU backend (requires CUDA drivers):\n```bash\npip install \"vexor[local-cuda]\"\n```\n\nDownload a local embedding model and auto-configure Vexor:\n```bash\nvexor local --setup --model intfloat/multilingual-e5-small\n```\n\nThen use `vexor search` / `vexor index` as usual.\n\nLocal models are stored in `~/.vexor/models` (clear with `vexor local --clean-up`).\n\nGPU (optional): install `onnxruntime-gpu` (or `vexor[local-cuda]`) and use `vexor local --setup --cuda` (or `vexor local --cuda`).\nSwitch back with `vexor local --cpu`.\n\n## Index Modes\n\nControl embedding granularity with `--mode`:\n\n| Mode | Description |\n|------|-------------|\n| `auto` | **Default.** Smart routing: Python/JS/TS → `code`, Markdown → `outline`, small files → `full`, large files → `head` |\n| `name` | Embed filename only (fastest, zero content reads) |\n| `head` | Extract first snippet for lightweight semantic context |\n| `brief` | Extract high-frequency keywords from PRDs/requirements docs |\n| `full` | Chunk entire content; long documents searchable end-to-end |\n| `code` | AST-aware chunking by module/class/function boundaries for Python and JavaScript/TypeScript; other files fall back to `full` |\n| `outline` | Chunk Markdown by heading hierarchy with breadcrumbs; non-`.md` falls back to `full` |\n\n## Cache Behavior\n\nIndex cache keys derive from: `--path`, `--mode`, `--include-hidden`, `--no-recursive`, `--no-respect-gitignore`, `--ext`, `--exclude-pattern`.\n\nKeep flags consistent to reuse cache; changing flags creates a separate index.\n\n```bash\nvexor config --show-index-all    # list all cached indexes\nvexor config --clear-index-all   # clear all cached indexes\nvexor index --path . --clear     # clear index for specific path\n```\n\nRe-running `vexor index` only re-embeds changed files; \u003e50% changes trigger full rebuild.\n\n## Command Reference\n\n| Command | Description |\n|---------|-------------|\n| `vexor init` | Run the interactive setup wizard |\n| `vexor QUERY` | Shortcut for `vexor search QUERY` |\n| `vexor search QUERY --path PATH` | Semantic search (auto-indexes if needed) |\n| `vexor index --path PATH` | Build/refresh index manually |\n| `vexor config --show` | Display current configuration |\n| `vexor config --clear-flashrank` | Remove cached FlashRank models under `~/.vexor/flashrank` |\n| `vexor local --setup [--model MODEL]` | Download a local model and set provider to `local` |\n| `vexor local --clean-up` | Remove local model cache under `~/.vexor/models` |\n| `vexor local --cuda` | Enable CUDA for local embeddings (requires `onnxruntime-gpu`) |\n| `vexor local --cpu` | Disable CUDA and use CPU for local embeddings |\n| `vexor install --skills claude` | Install Agent Skill for Claude Code |\n| `vexor install --skills codex` | Install Agent Skill for Codex |\n| `vexor doctor` | Run diagnostic checks (command, config, cache, API key, API connectivity) |\n| `vexor update [--upgrade] [--pre]` | Check for new version (optionally upgrade; `--pre` includes pre-releases) |\n| `vexor feedback` | Open GitHub issue form (or use `gh`) |\n| `vexor alias` | Print a shell alias for `vx` and optionally apply it |\n\n### Common Flags\n\n| Flag | Description |\n|------|-------------|\n| `--path PATH` | Target directory (default: current working directory) |\n| `--mode MODE` | Index mode (`auto`/`name`/`head`/`brief`/`full`/`code`/`outline`) |\n| `--top K` / `-k` | Number of results (default: 5) |\n| `--ext .py,.md` / `-e` | Filter by extension (repeatable) |\n| `--exclude-pattern PATTERN` | Exclude paths by gitignore-style pattern (repeatable; `.js` treated as `**/*.js`) |\n| `--include-hidden` / `-i` | Include hidden files |\n| `--no-recursive` / `-n` | Don't recurse into subdirectories |\n| `--no-respect-gitignore` | Include gitignored files |\n| `--format porcelain` | Script-friendly TSV output |\n| `--format porcelain-z` | NUL-delimited output |\n| `--no-cache` | In-memory only; do not read/write index cache |\n\nPorcelain output fields: `rank`, `similarity`, `path`, `chunk_index`, `start_line`, `end_line`, `preview` (line fields are `-` when unavailable).\n\n## Documentation\n\nSee [docs](https://github.com/scarletkc/vexor/tree/main/docs) for more details.\n\n## Contributing\n\nContributions, issues, and PRs welcome! Star if you find it helpful.\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=scarletkc/vexor\u0026type=date\u0026legend=top-left)](https://www.star-history.com/#scarletkc/vexor\u0026type=date\u0026legend=top-left)\n\n## License\n\n[MIT](http://github.com/scarletkc/vexor/blob/main/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscarletkc%2Fvexor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscarletkc%2Fvexor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscarletkc%2Fvexor/lists"}