Seraph

Local code search and Git-aware code intelligence for coding agents. Seraph indexes a local Git checkout into a SQLite database and exposes working-tree search, change impact, task context, repository maps, symbols, dependencies, history, and version comparison over MCP.

Install from a checkout

Requires Python 3.12 and Git. With uv:

uv tool install --from . seraph-mcp

For development directly from this directory:

uv sync
uv run seraph-mcp

Install the published package from PyPI:

python -m pip install seraph-mcp

Agent setup

Register a local stdio MCP server in your agent with command seraph-mcp and no arguments, then reload the MCP connection. Use your agent's own MCP setup UI or command because configuration differs by host. On every Seraph tool call, pass repo as the absolute path to the local Git checkout you want searched. Use the active workspace path for that project, or a different repository path when the question is about another checkout.

Seraph runs on the user's machine. Each tool accepts repo, the absolute path to the local Git checkout to search. The agent should pass the active workspace path on every call; if asked about another checkout, pass that checkout's path. The index is stored at <repo>/.seraph/index.sqlite and ignored by Git.

MCP tools

• search_code: retrieve relevant code from the selected checkout.
• search_at_version: retrieve code from a commit, branch, or tag.
• search_history: search indexed Git versions.
• find_symbol: locate a function, class, or method.
• find_dependencies: walk call, import, and inheritance relationships.
• get_working_tree_status: see staged, unstaged, and untracked source changes.
• search_worktree: search current on-disk source, including uncommitted edits and untracked files.
• change_impact: find statically resolved callers, importers, and related tests for symbols or changed paths.
• prepare_change_context: bundle task-relevant code, a repo map, change impact, and Git history in one bounded response.
• get_repo_map: get a compact file-to-symbol overview; select scope="worktree" for current on-disk files, expand a subtree with path_prefix, or raise max_files and max_chars.
• compare_versions: compare symbols, dependencies, and commits.
• index_repository: explicitly index a Git version; searches index automatically when needed.

The default retrieval setup is local and needs no API key. Benchmark/evaluation code and submission assets are intentionally excluded from this slim distribution.

prepare_change_context caps its response by characters, reports when it truncates, and suggests focused follow-up tools. The coding agent decides how that evidence fits its own token budget. Working-tree tools overlay changed supported source files on indexed HEAD; the overlay itself is temporary.

Optional local semantic search

The default install uses BM25 and does not install Torch or download a model.

For BGE-Code-v1 or GTE-ModernBERT, opt in to the Transformers 4 extra:

python -m pip install 'seraph-mcp[cpu]'  # CPU / Apple Silicon
# or, on an NVIDIA CUDA machine:
python -m pip install 'seraph-mcp[gpu]'

Seraph downloads BGE-Code-v1 (about 6 GB) from Hugging Face the first time semantic search needs it. Hugging Face caches the files, so the same user account reuses that model across repositories. Each teammate only downloads their own local cache if they opt in.

EmbeddingGemma-2 needs Transformers 5, so use its separate extra instead of cpu or gpu:

python -m pip install 'seraph-mcp[gemma2]'

Choose embeddinggemma-2 in Seraph's model configuration. The selected model weights download on first use and are then cached locally.

CLI

seraph --repo /path/to/repo index
seraph --repo /path/to/repo search "where is request authentication checked?"
seraph --repo /path/to/repo symbol authenticate_request
seraph --repo /path/to/repo deps authenticate_request
seraph --repo /path/to/repo compare <old-commit> <new-commit>

License

Released under the MIT License.