sensegrep

semantic grep for AI coding agents

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".

AI agents should not read more code, they should read the right code. sensegrep combines semantic search, exact matching, and AST-aware structural retrieval to deliver smaller, more relevant context.

For agent routing, search is the default for discovery: questions about behavior, concepts, structure, or where/how something is implemented. Use literal only for a known exact string or regex, an exhaustive occurrence audit, or verification/refinement after semantic discovery. If the intent is ambiguous, start with search.

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:

Quickstart

Optional remote evaluation: Jev setup, evidence-aware reranking, group labels and duplicate judgments. It is off by default and works alongside local Ollama embeddings.

Claude Code Plugin (recommended)

The fastest way to get sensegrep into Claude Code — zero configuration:

claude plugin marketplace add Stahldavid/sensegrep
claude plugin install sensegrep

This automatically sets up the MCP server and teaches Claude when and how to use sensegrep instead of grep. No manual JSON editing required.

Marketplace setup (required on first install):

Terminal

Copy

claude plugin marketplace add Stahldavid/sensegrep
claude plugin install sensegrep

After the marketplace has been added once, the explicit marketplace form also works:

Terminal

Copy

claude plugin install sensegrep@sensegrep

Running claude plugin install sensegrep@sensegrep on a fresh machine before claude plugin marketplace add Stahldavid/sensegrep will fail because Claude Code does not know the sensegrep marketplace yet.

CLI

npm i -g @sensegrep/cli

# Smoke-test local CLI/core/config without calling embeddings
sensegrep selftest --root .

# Default local embeddings use Ollama when no API key/provider is configured
ollama pull qwen3-embedding:0.6b
sensegrep index --root .

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

# Known exact text, deterministic and exhaustive: no embedding call
sensegrep literal "X-Goog-Message-Number" --include "src/**"

# Compact evidence cards, followed by deterministic expansion
sensegrep search "authentication flow" --purpose understand --json
sensegrep show <result-id> --before 10 --after 20

# Exhaustive within the ripgrep-visible filesystem, independent of the index
sensegrep literal "TODO:" --filesystem --max-output-bytes 50000 --json

# Complete changed-file review coverage in bounded batches
sensegrep audit "security regressions" --base origin/main --require-coverage --continue-uncovered --batch-tokens 4000 --max-total-tokens 8000 --max-output-bytes 32000 --max-batches 8

# Build a reading map for a broad theme
sensegrep survey "authentication login token" --language typescript --limit 4

# Break a broad topic into coherent subthemes
sensegrep cluster "checkout payment order cart" --limit 4

# Find duplicates
sensegrep detect-duplicates --threshold 0.85
sensegrep detect-duplicates --threshold 0.85 --timeout 30s --resume-cursor 0 --json

Agent-facing JSON is minified and minimal by default. Opt into --json-detail content, --diagnostic, --json-detail full, or --pretty only when that additional payload is needed. Schema v2 uses one card vocabulary across transports: id, file, lines, symbol, kind, rank, and relevance. Minimal output keeps retrieval sufficiency, compact index state, and structured warnings; budgets appear only when constrained. Physical output budgets apply to the final serialized JSON and retain a partial evidence card when possible. Duplicate JSON excludes source code unless --show-code is supplied. Survey and cluster JSON default to actionable summary mode with representative IDs.

Cursor Plugin

Install from the Cursor marketplace or via CLI:

cursor plugin install sensegrep

Includes the MCP server, an always-on rule to prefer sensegrep over grep, and a skill with full filter reference. Cursor plugin status: pending marketplace approval.

One-click MCP install link for Cursor:

Fallback deeplink (copy/paste if needed):

cursor://anysphere.cursor-deeplink/mcp/install?name=sensegrep&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzZW5zZWdyZXAvbWNwQGxhdGVzdCJdfQ%3D%3D

Codex Plugin

Install from the public marketplace — no manual config:

codex plugin marketplace add Stahldavid/sensegrep
codex plugin install sensegrep

See the Codex recipe for the manual ~/.codex/config.toml setup.

MCP Server (for Codex or manual setup)

npx -y @sensegrep/mcp

Add to your MCP configuration:

{
  "servers": {
    "sensegrep": {
      "command": "npx",
      "args": ["-y", "@sensegrep/mcp"]
    }
  }
}

Or with npm global install first:

npm install -g @sensegrep/mcp

{
  "servers": {
    "sensegrep": {
      "command": "sensegrep-mcp"
    }
  }
}

The MCP server provides canonical sensegrep_search, sensegrep_show, sensegrep_literal, sensegrep_context, sensegrep_survey, sensegrep_cluster, sensegrep_graph, sensegrep_index, and sensegrep_detect_duplicates tools. Legacy dotted names such as sensegrep.search remain available as compatibility aliases where supported.

Agent Skill — CLI (no MCP server)

For terminal-first agents or CI, you don't need an MCP server. Install the CLI and the sensegrep-cli Agent Skill, which teaches the agent to run sensegrep commands directly:

npm i -g @sensegrep/cli
npx skills add Stahldavid/sensegrep --skill sensegrep-cli -g

See docs/agent-skills.md for when to use the MCP tools vs the CLI skill.

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, and multi-root auto-indexing/watch mode.

Recipes

Copy-paste setup and practical workflows:

• Claude Code recipe
• Cursor recipe
• Codex recipe
• CI with GitHub Actions
• Generic CI recipe

Full index: docs/recipes/README.md

How It Works

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

1. Parse: Tree-sitter extracts AST nodes with full metadata (symbol type, exports, complexity, docs, decorators)
2. Chunk: Code is split into semantic chunks aligned to symbol boundaries
3. Embed: Each chunk is embedded using Ollama, Gemini, an OpenAI-compatible embeddings API, or Amazon Bedrock.
4. Store: Embeddings + metadata are stored in LanceDB for fast vector search
5. Search: Vector and lexical candidates are fused, structurally filtered, and optionally reranked
6. Tree-shake: Results are collapsed to show only relevant code, hiding unrelated symbols

Supported Languages