sensegrep

Semantic + structural code search for AI-native development.

sensegrep understands your code semantically. Instead of matching text patterns, it uses AI embeddings and tree-sitter AST parsing to find code by meaning - so you can search for "authentication logic" and actually find your auth functions, even if they never contain the word "authentication".

Sensegrep time-to-value demo

MP4 fallback: assets/time-to-value.mp4

Watch full product demo (25s): assets/time-to-value-full.mp4

Why sensegrep?

Traditional search tools (grep, ripgrep, ast-grep) match text patterns. sensegrep matches concepts:

Feature	grep/ripgrep	ast-grep	sensegrep
Exact text match	Yes	Yes	Yes (via `--pattern`)
AST-aware	No	Yes	Yes (tree-sitter)
Semantic search	No	No	Yes (AI embeddings)
Symbol metadata filters	No	Partial	Yes (30+ filters)
Duplicate detection	No	No	Yes (logical duplicates)
Tree-shaking output	No	No	Yes (collapse irrelevant code)
MCP server for AI agents	No	No	Yes

Quickstart

CLI

npm i -g @sensegrep/cli

# Index your project
sensegrep index --root .

# Search by meaning
sensegrep search "error handling and retry logic" --type function --exported

# Find duplicates
sensegrep detect-duplicates --threshold 0.85

MCP Server (for Claude Code, Cursor, Windsurf, etc.)

npx -y @sensegrep/mcp

Add to your MCP configuration:

{
  "mcpServers": {
    "sensegrep": {
      "command": "npx",
      "args": ["-y", "@sensegrep/mcp"],
      "env": {
        "SENSEGREP_ROOT": "/path/to/your/project"
      }
    }
  }
}

The MCP server provides sensegrep.search, sensegrep.index, sensegrep.stats, sensegrep.detect_duplicates, and sensegrep.languages tools.

VS Code Extension

Search for "Sensegrep" in the VS Code marketplace, or install from the extension page.

Features: semantic search sidebar, duplicate detection, code lens, semantic folding, auto-indexing with watch mode.

Recipes

Copy-paste setup and practical workflows:

Full index: docs/recipes/README.md

How It Works

Source Code
    │
    ▼
┌─────────────┐    ┌──────────────┐    ┌──────────────┐
│  Tree-Sitter │───▶│   Chunker    │───▶│  Embeddings  │
│  AST Parser  │    │  (symbols +  │    │  (local or   │
│              │    │   metadata)  │    │   Gemini)    │
└─────────────┘    └──────────────┘    └──────────────┘
                                              │
                                              ▼
                                       ┌──────────────┐
                          Query ──────▶│   LanceDB    │
                                       │ Vector Search│
                                       └──────┬───────┘
                                              │
                                              ▼
                                       ┌──────────────┐
                                       │ Tree-Shaker  │──▶ Results
                                       │ (collapse    │
                                       │  irrelevant) │
                                       └──────────────┘

Parse: Tree-sitter extracts AST nodes with full metadata (symbol type, exports, complexity, docs, decorators)
Chunk: Code is split into semantic chunks aligned to symbol boundaries
Embed: Each chunk is embedded using local models (HuggingFace transformers.js) or Gemini API
Store: Embeddings + metadata are stored in LanceDB for fast vector search
Search: Your query is embedded and matched against the index with optional structural filters
Tree-shake: Results are collapsed to show only relevant code, hiding unrelated symbols

Supported Languages

TypeScript / JavaScript (TSX/JSX included)
Python (dataclasses, protocols, decorators, async generators, TypedDict, and more)
More coming: C#, Java, HTML (see feature branches)

Search Filters

sensegrep supports 30+ structural filters that can be combined with semantic search:

# Find exported async functions with high complexity
sensegrep search "data processing" --type function --exported --async --min-complexity 5

# Find Python dataclasses
sensegrep search "user model" --type class --variant dataclass --language python

# Find undocumented complex code (refactoring candidates)
sensegrep search "business logic" --min-complexity 10 --has-docs false

# Filter by decorator
sensegrep search "route handler" --type function --decorator route

Embeddings Configuration

sensegrep supports local (default) and Gemini embeddings:

# Local (default) - no API key needed
sensegrep search "auth flow" --device cpu

# Gemini API
sensegrep search "auth flow" --provider gemini --embed-model gemini-embedding-001

# Custom local model
sensegrep search "auth flow" --embed-model BAAI/bge-base-en-v1.5 --embed-dim 768

Global defaults via ~/.config/sensegrep/config.json:

{
  "provider": "local",
  "embedModel": "BAAI/bge-small-en-v1.5",
  "embedDim": 384,
  "device": "cpu"
}

Environment variables: SENSEGREP_PROVIDER, SENSEGREP_EMBED_MODEL, SENSEGREP_EMBED_DIM, SENSEGREP_EMBED_DEVICE.

Packages

Package	Description	npm
@sensegrep/core	Search engine library
@sensegrep/cli	Command-line interface
@sensegrep/mcp	MCP server for AI agents
sensegrep	VS Code extension	Marketplace

Case Studies

Reproducible qualitative examples from public repositories:

Case studies

Roadmap

ROADMAP.md
Benchmark methodology vs ripgrep / ast-grep is scheduled for Month 2.

Contributing

See CONTRIBUTING.md for development setup, architecture overview, and contribution guidelines.

Community

License

Apache-2.0

Sensegrep

Quick Install