semble-search

Use semble search to find code by describing what it does or naming a symbol/identifier, instead of grep:

semble search "authentication flow" ./my-project --max-snippet-lines 10  # first 10 lines only, concise
semble search "save_pretrained" ./my-project                          # full chunk content
semble search "save model to disk" ./my-project --top-k 10           # more results

Results are cached automatically on first run and invalidated when files change.

Use --content docs to search documentation and prose, --content config for config files (yaml, toml, etc.), or --content all to search code, docs, and config:

semble search "deployment guide" ./my-project --content docs
semble search "database host port" ./my-project --content config
semble search "authentication" ./my-project --content all

Use semble find-related to discover code similar to a known location (pass file_path and line from a prior search result):

semble find-related src/auth.py 42 ./my-project

path defaults to the current directory when omitted; git URLs are accepted. Pass several paths or URLs to search related repos together, e.g. when this project calls a service defined in a sibling repo. Result paths are then prefixed with the repo name and the output includes a repos map from prefix to location:

semble search "invoice endpoint" ./service-a ../service-b

If semble is not on $PATH, use uvx --from "semble[mcp]" semble in its place.

Workflow

1. Start with semble search to find relevant chunks. The index is built and cached automatically.
2. Use --content docs for documentation, --content config for config files, or --content all for everything.
3. Navigate directly to the returned file and line. Do not re-search or grep for the same content.
4. Optionally use semble find-related with a promising result's file_path and line to discover related implementations.
5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one semble search call.
6. Use grep only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function).