Sensegrep

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):

`bash

claude plugin marketplace add Stahldavid/sensegrep

claude plugin install sensegrep

`

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

`bash

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

• TypeScript / JavaScript (TSX/JSX included)
• Python (dataclasses, protocols, decorators, async generators, TypedDict, and more)
• Java (classes, interfaces, records, annotations, methods, and tree-shaken results)
• Vue (single-file components with / semantic support)
• More coming: C#, 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

Keep docs and markdown out of results

sensegrep search "authentication flow" --include "src/**/*.ts" --exclude "*.md"

Build a reading map for onboarding a domain

sensegrep survey "authentication login token" --language typescript --limit 4

Split a broad backend topic into subthemes

sensegrep cluster "price list commission ncm uf packaging" --language java --include "backend-api/**/*.java"

Build an agent context pack with a hard estimated-token budget

sensegrep context "authentication request flow" --max-tokens 8000

Review only code changed against a Git base

sensegrep audit "security and regression risks" --base origin/main

Navigate the local symbol graph

sensegrep references loadUser sensegrep impact loadUser --depth 3 sensegrep trace handleRequest loadUser

Graph nodes use canonical file/range identities. Ambiguous same-name call targets are omitted instead of expanded into speculative impact edges.

Index Operations

# Inspect local work before any embedding request

sensegrep index --dry-run --no-watch

Interrupted full builds resume their fingerprint-matched staging table

sensegrep index --full --no-watch

Compare safe concurrency candidates without changing saved config

sen