vgrep is a local semantic search CLI for code and notes. It builds an embedding index on your machine and lets you query your project with natural language.

vgrep is designed for fast, local project search when keyword grep is not enough.

• Local-first: embeddings and index data stay on your machine.
• Language-flexible indexing: text files are indexed even when extensions are unknown.
• Code-aware chunking where available: known languages use tree-sitter-based symbol chunking; other files fall back to fixed-size chunking.
• Ignore-aware traversal: respects .gitignore and .vgrepignore.

Index data is stored under .vgrep/ in the project root.

Recommended global install with uv tool:

uv tool install .
vgrep --help

Alternative global install with pipx:

pipx install .
vgrep --help

Local editable install for development:

uv venv
source .venv/bin/activate
uv pip install -e .
vgrep --help

1. Initialize vgrep storage in a project:

uv run vgrep init .

2. Build or refresh the semantic index:

uv run vgrep index .

3. Search using natural language:

uv run vgrep search "database connection pooling logic"

Common options:

# Run embeddings in-process instead of daemon mode
uv run vgrep index . --no-daemon

# Search a specific project root
uv run vgrep search "queue retries" --project-root /path/to/project

# Adjust result count
uv run vgrep search "authentication flow" --limit 20

Install dependencies:

uv sync --extra dev

Initialize local vgrep storage in this repo:

uv run vgrep init .

Run local quality checks:

uv run ruff check src tests
uv run python -m pytest -q

Minimal CI baseline:

uv sync --extra dev
uv run ruff check src tests
uv run python -m pytest -q