Metadata-Version: 2.4
Name: vecgrep
Version: 0.1.0
Summary: Cursor-style vector search MCP plugin for Claude Code
Project-URL: Homepage, https://github.com/iamvirul/VecGrep
Project-URL: Repository, https://github.com/iamvirul/VecGrep
Project-URL: Issues, https://github.com/iamvirul/VecGrep/issues
Author: iamvirul
License: MIT
License-File: LICENSE
Keywords: claude,code-search,embeddings,mcp,semantic-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: mcp[cli]<2.0,>=1.0
Requires-Dist: numpy>=1.26
Requires-Dist: sentence-transformers<4.0,>=3.0
Requires-Dist: tree-sitter-languages<2.0,>=1.10
Provides-Extra: dev
Requires-Dist: pyright>=1.1.360; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# VecGrep

[![CI](https://github.com/iamvirul/VecGrep/actions/workflows/ci.yml/badge.svg)](https://github.com/iamvirul/VecGrep/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/iamvirul/VecGrep/branch/main/graph/badge.svg)](https://codecov.io/gh/iamvirul/VecGrep)

Cursor-style semantic code search as an MCP plugin for Claude Code.

Instead of grepping 50 files and sending 30,000 tokens to Claude, VecGrep returns the top 8 semantically relevant code chunks (~1,600 tokens). That's a **~95% token reduction** for codebase queries.

## How it works

1. **Chunk** — Parses source files with tree-sitter to extract semantic units (functions, classes, methods)
2. **Embed** — Encodes each chunk locally using `all-MiniLM-L6-v2` (384-dim, ~80MB one-time download)
3. **Store** — Saves embeddings + metadata in SQLite under `~/.vecgrep/<project_hash>/`
4. **Search** — Cosine similarity over all embeddings returns the most relevant snippets

Incremental re-indexing via SHA256 file hashing skips unchanged files.

## Installation

Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).

```bash
pip install vecgrep        # standard pip
uv tool install vecgrep   # uv tool (isolated, recommended)
```

## Claude Code integration

Add to your Claude Code MCP settings (`~/.claude/claude_desktop_config.json` or via `claude mcp add`):

```json
{
  "mcpServers": {
    "vecgrep": {
      "command": "uvx",
      "args": ["vecgrep"]
    }
  }
}
```

Or with the CLI:

```bash
claude mcp add vecgrep -- uvx vecgrep
```

`uvx` downloads and runs VecGrep in an isolated environment on first use — no cloning or manual setup required.

## Tools

### `index_codebase(path, force=False)`

Index a project directory. Skips unchanged files on subsequent calls.

```
index_codebase("/path/to/myproject")
# → "Indexed 142 file(s), 1847 chunk(s) added (0 file(s) skipped, unchanged)"
```

### `search_code(query, path, top_k=8)`

Semantic search. Auto-indexes if no index exists.

```
search_code("how does user authentication work", "/path/to/myproject")
```

Returns formatted snippets with file paths, line numbers, and similarity scores:

```
[1] src/auth.py:45-72 (score: 0.87)
def authenticate_user(token: str) -> User:
    ...

[2] src/middleware.py:12-28 (score: 0.81)
...
```

### `get_index_status(path)`

Check index statistics.

```
Index status for: /path/to/myproject
  Files indexed:  142
  Total chunks:   1847
  Last indexed:   2026-02-22T07:20:31+00:00
  Index size:     28.4 MB
```

## Supported languages

Python, JavaScript/TypeScript, Rust, Go, Java, C/C++, Ruby, Swift, Kotlin, C#

All other text files fall back to sliding-window line chunks.

## Index location

`~/.vecgrep/<sha256-of-project-path>/index.db`

Each project gets its own isolated index. Delete the directory to wipe the index.
