sensegrep-cli

sensegrep (CLI) — Semantic Code Search

Search code by meaning, not text patterns, by running the sensegrep command-line tool. Uses AI embeddings + tree-sitter AST parsing. This skill is CLI-first: it runs shell commands and reads their output. It does not require the sensegrep MCP server. If the sensegrep MCP tools are available in your environment, prefer those; otherwise use the CLI commands below.

Setup

Install the CLI once (global), then index the project before the first search:

npm install -g @sensegrep/cli
sensegrep index            # builds the semantic index for the current directory

Add --json to search, context, audit, survey, cluster, graph, index-health, or detect-duplicates commands to get machine-readable output that is easy to parse programmatically. When --json is active, stdout is reserved for JSON; human progress and warnings go to stderr.

Use sensegrep --version to confirm the installed CLI version.

When to Use

• sensegrep search: Finding functions/classes by behavior, exploring structure, semantic queries, multi-criteria searches
• sensegrep literal: Exact strings and regex proof; add --filesystem when the evidence universe must not depend on the index
• grep/ripgrep: Fallback only when Sensegrep is unavailable or custom raw filesystem behavior is required

Routing rule: Start with sensegrep search whenever the task asks where or how behavior is implemented, even if the request contains candidate keywords. Use sensegrep literal only when the text or regex is already known, every textual occurrence is required, or you are verifying/refining a semantic result. If unsure, choose sensegrep search.

Local execution and evidence quality

• On Windows PowerShell, use sensegrep.cmd if execution policy blocks npm's sensegrep.ps1 wrapper. No policy change is needed.
• For local embeddings, set provider: "ollama", embedModel: "qwen3-embedding:0.6b", embedDim: 1024, and baseUrl: "http://127.0.0.1:11434" in ~/.config/sensegrep/config.json. Confirm the resolved provider with selftest; environment and CLI overrides can take precedence.
• Use incremental index --no-watch for normal updates. A missing index warrants indexing; a known text lookup does not.
• Start conceptual searches with a domain or framework when known (for example, "Clerk session token refresh"). If results are weak, reformulate before raising the result limit. Avoid premature kind filters: a business rule may live in a helper rather than a framework mutation.
• Follow relevant result IDs with show, then verify claims in source. confidence is a ranking heuristic, not a calibrated probability that a result answers the question.
• If context reports status: "incomplete" or retrieval.truncated, inspect selected IDs and expand missing evidence with show; a small token budget can omit an important file.
• graphCoverage measures resolved edges divided by resolved, unresolved, and ambiguous edges considered by the graph. It is not recall against every real reference in the repository. Use compiler-aware tools before refactoring when completeness matters.
• Report CLI wall time separately from internal search timings. Do not attribute process startup time to the embedding model.
• benchmark measures provider request concurrency, not index worker concurrency or Ollama server slots. Sequential adapters (including native Ollama) report a baseline without a recommendation; an OpenAI-compatible sample fitting in one HTTP batch also cannot compare concurrency. On older versions, disregard Ollama concurrency recommendations.
• Index plans distinguish internal estimatedBatches/batchSize from estimated HTTP requests. Ollama exposes httpBatchSize; request estimates exclude retries, and dry-run estimates may overstate work when vectors will be reused.