name: vexor-cli description: Semantic file discovery via vexor (use when you need intent-based file lookup in a repo). license: MIT

Vexor CLI

Purpose (for the agent)

Use Vexor as a fast "semantic grep": build (or refresh) an index for a directory, then query it to find the most relevant files/sections for the current task.

When to use

Use this skill when you need intent-based file discovery (not exact string match), e.g.:

• "Where is config loaded / validated?"
• "Which file defines the provider backends?"
• "Find the CLI command that prints this output"
• "Locate the code that chunks/embeds Python by function"

Checklist (do this in order)

1. Ensure the CLI exists:
   • Prefer vexor doctor or python -m vexor --help.
   • If vexor is missing: python -m pip install vexor (or pip install vexor / pipx install vexor).
2. Index the target root (required once per cache key):
   • vexor index --path <ROOT> [--mode <MODE>] [--ext .py,.md] [--include-hidden] [--no-recursive]
3. Search using the same cache key flags:
   • vexor search "<QUERY>" --path <ROOT> [--mode <MODE>] [--ext .py,.md] [--top 10]

Cache key (avoid "No cached index found…")

These flags must match between index and search:

• --path, --mode (defaults to auto when omitted)
• --include-hidden, --no-recursive
• --respect-gitignore/--no-respect-gitignore (default: respect, including nested .gitignore)
• --ext (repeatable; each value may be a comma/space-separated list like --ext .py,.md or --ext '.py .md')

Mode guidance (pick the least expensive that works)

• Default: auto (Python → code, Markdown → outline, small → full, large → head)
• If you only need filenames: name
• If you need a quick content hint: head
• If you need structure in Markdown docs: outline
• If you need Python symbols (functions/classes/methods): code
• If recall is still low: full (more expensive; many chunks per file)

Output parsing

• Default output is a rich table. It includes a Lines column when available.
• --format porcelain / porcelain-z emits: rank similarity path chunk_index start_line end_line preview (line fields may be - if unavailable).

Troubleshooting

• If results look stale: rerun vexor index for the same cache key.
• If you need ignored files: add --no-respect-gitignore to both commands.
• If API/config issues: vexor config --show and let the user fix them.