Content
<!-- mcp-name: io.github.srclight/srclight -->
# Srclight
[](https://github.com/Allegion-Sandbox/srclight/blob/develop/LICENSE)
> **Disclaimer:** This fork was created after I noticed the original repository was no longer progressing or being actively maintained. I started this fork to keep moving forward with refactoring and to add missing features I needed.
**Deep code indexing for AI agents.** SQLite FTS5 + tree-sitter + embeddings + MCP.
## Why?
AI coding agents (Claude Code, Cursor, etc.) spend **40-60% of their tokens on orientation** — searching for files, reading code to understand structure, hunting for callers and callees. Srclight eliminates this waste.
| Without Srclight | With Srclight |
|---|---|
| 8-12 grep rounds to find callers | `trace("lookup", type="callers")`, one call |
| Read 5 files to understand module | `trace(type="codebase_map")`, instant overview |
| "Find code that does X" -> 20 greps | `search("dictionary lookup", kind="semantic")`, one call |
| Edit a function, break 47 callers | `trace(type="changes")`, shows blast radius before you commit |
| 15-25 tool calls per bug fix | 5-8 tool calls per bug fix |
## Features
- **Minimal dependencies** — single SQLite file per repo, no Docker/Redis/vector DB
- **Fully offline** — no API calls, works air-gapped (Ollama local embeddings)
- **Incremental** — only re-indexes changed files (content hash detection)
- **305 languages** — Python, JavaScript, TypeScript, Go, Rust, Ruby, Java, C/C++, C#, and [295+ more](docs/languages.md) via `tree-sitter-language-pack`
- **10 document formats** — PDF, DOCX, XLSX, HTML, CSV/TSV, email (.eml), images (PNG/JPG/SVG/etc.), plain text, RST, Markdown
- **OCR** — PaddleOCR for scanned/image-only PDF pages; pytesseract for images
- **4 search modes** — symbol names, source code (trigram), documentation (stemmed), semantic (embeddings)
- **Hybrid search** — three-way weighted RRF fusion (exact name: 2.0, FTS keyword: 1.0, semantic vector: 0.7) with cosine similarity threshold (≥ 0.45) for best precision
- **Multi-repo workspaces** — search across all your repos simultaneously via SQLite ATTACH+UNION
- **MCP server** — works with Claude Code, Cursor, and any MCP client
- **CLI** — index, search, and inspect from the terminal
- **Auto-reindex** — git post-commit/post-checkout hooks keep indexes fresh
- **Graph analysis** — circular dependency detection, 360° symbol view, hub/bridge centrality analysis (`trace type="hubs"`, `type="bridges"`), and surprise scoring for unexpected cross-community coupling (`trace type="surprise"`) — plus confidence-scored call-graph edges
- **Context artifact indexing** — open-ended artifact search by any `category`, `subcategory`, or `extension` value (e.g., `kubernetes`, `helm`, `sql`, `terraform`); legacy kinds `database-schema`, `api-spec`, `infra-config` still work
- **Platform auto-integration** — `srclight setup` detects, configures, and uninstalls Cursor, Claude Desktop, OpenCode, GitHub Copilot, and Claude Code integrations automatically
## Requirements
- **Python 3.11+**
- **Git** (for change intelligence and auto-reindex hooks)
- **Ollama** (optional, for semantic search / embeddings) — [ollama.com](https://ollama.com)
- **Poppler** (optional, for PaddleOCR scanned-PDF support) — `apt install poppler-utils` / `brew install poppler`
## Quick Start
```bash
# Build the standalone bundle for this platform (macOS Apple Silicon)
git clone https://github.com/srclight/srclight.git
cd srclight
# Optional system prerequisite for PDF extraction support
brew install poppler
# Build the one-dir bundle for the current machine
bash packaging/pyinstaller/build.sh
# Extract it under a stable local directory
mkdir -p "$HOME/.local/opt"
tar -xzf dist/srclight-*-macos-arm64.tar.gz -C "$HOME/.local/opt"
# Put the bundled executable directory on PATH
echo 'export PATH="$HOME/.local/opt/srclight:$PATH"' >> ~/.zprofile
source ~/.zprofile
# Verify the binary
srclight --version
# Index your project
cd /path/to/your/project
# Search
srclight search "Database"
srclight search "Database" --kind semantic
srclight search --symbol "Database.connect"
srclight trace "Database.connect" --type callers,blame
srclight trace --type hotspots,recent_changes
srclight manage status
srclight manage index # incremental (only changed files)
srclight manage reindex # purge SQLite + Qdrant, fresh full index
# Start MCP server (for Claude Code / Cursor)
srclight serve
```
### Standalone bundle notes
- The build script is `packaging/pyinstaller/build.sh` (macOS/Linux) and `packaging/pyinstaller/build.ps1` (Windows). They create standalone executable bundles. On Windows, Vulkan is used for `llama-cpp-python` acceleration (removing complex external GPU driver or CUDA dependencies), while Metal is used on Apple Silicon.
- The bundle path you add to `PATH` is the extracted `srclight/` directory, because that directory contains both `srclight` and `srclight-backend` executables.
- The current binary build includes all mandatory dependencies and the required `qdrant_edge` runtime used for semantic search.
### If you need the full Python dependency set on this machine
Use a local editable install in a virtual environment and put the venv's `bin/` directory on `PATH`:
```bash
git clone https://github.com/srclight/srclight.git
cd srclight
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip setuptools wheel
# Optional system prerequisites for OCR/PDF helpers (tesseract/poppler are still optional system tools)
brew install poppler tesseract
# Install the local project (all features are in the base install)
pip install -e .
# Expose the venv's CLI on PATH for future shells
echo 'export PATH="'$PWD'/.venv/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile
srclight --version
```
> **Note:** Running indexing automatically adds `.srclight/` to your `.gitignore`. Index databases and embedding files can be large and should never be committed.
## Context Artifact Indexing & Cascade Auto-Classification
Srclight features a **zero-configuration Cascade Auto-Classification System** (two-layer cascade) that automatically categorizes all files in your repository during normal indexing. No manual configuration is required!
### The Two-Layer Cascade: SchemaStore + puremagic
Every indexed file is automatically classified with:
- **extension**: normalized format / language (e.g., `python`, `yaml`, `sql`, `pdf`)
- **category**: broad retrieval routing (e.g., `source-code`, `config`, `spec`, `build-ci`, `infra`, `data`, `document`, `binary`, `policy`)
- **subcategory**: task-relevant semantic slice (e.g., `kubernetes`, `openapi`, `github-actions`, `terraform`, `helm`, `sql`, `image`, `archive`)
Run `srclight manage index` (no extra config needed). Then search:
### Full Taxonomy
Every indexed file is tagged with a `category`, `subcategory`, and `extension`. Pass any of these as the `--type` (or `type=`) parameter to filter results across any search kind:
| category | subcategories |
|----------|---------------|
| `config` | `generic-config`, `tool-config`, `package-manifest`, `devcontainer`, `dependency-bot`, `schema-backed-config` |
| `spec` | `openapi`, `asyncapi`, `json-schema` |
| `build-ci` | `github-actions`, `gitlab-ci`, `azure-pipelines`, `circleci`, `bitbucket-pipelines`, `container-build`, `build-system` |
| `infra` | `kubernetes`, `helm`, `docker-compose`, `terraform` |
| `data` | `tabular-data`, `sql`, `notebook`, `database-file` |
| `document` | `text-doc`, `office-doc` |
| `binary` | `image`, `media`, `archive`, `executable`, `certificate`, `unknown-binary` |
| `text` | `unclassified-text` |
**Extension examples:** `yaml`, `yml`, `json`, `toml`, `sql`, `md`, `rst`, `txt`, `csv`, `tsv`, `ipynb`, `pdf`, `dockerfile`, `makefile`, `pem`, `crt`, `sqlite`, etc.
Run `srclight manage index`. Then search:
```bash
# Global taxonomy filtering on any search mode
srclight search "redis pods" --type kubernetes
srclight search "auth endpoints" --type openapi
srclight search "create table" --type sql
# Search only context files
srclight search "config" --kind file --type yaml
# List all SQL context files without a query
srclight search --kind file --type sql
```
Or via MCP:
```python
# Filters standard search results globally to sql files
search(query="users", type="sql")
# Searches only context files
search(query="auth", kind="file")
# Searches only context files matching kubernetes type
search(query="redis", kind="file", type="kubernetes")
# Lists all yaml context files
search(kind="file", type="yaml")
```
## Semantic Search (Embeddings)
Srclight supports embedding-based semantic search for natural language queries like "find code that handles authentication" or "where is the database connection pool".
### Setup
```bash
# Install Ollama (https://ollama.com)
# Pull an embedding model
ollama pull qwen3-embedding # Best quality (8B params, needs ~6GB VRAM)
ollama pull nomic-embed-text # Lighter alternative (137M params)
# Index with embeddings
srclight manage index --embed qwen3-embedding
# Or reindex a whole workspace with embeddings
srclight manage reindex -w myworkspace --embed qwen3-embedding
```
### How It Works
1. Each symbol's name, signature, docstring, and content is embedded as a float vector.
2. Symbol, file, graph, and FTS metadata remain in SQLite.
3. Embedding vectors are stored in a per-project Qdrant Edge shard under `.srclight/qdrant/`.
4. `search(query, kind="semantic")` embeds the query, searches Qdrant Edge for nearest neighbors, and enriches results from SQLite.
5. `search(query)` (which defaults to hybrid search) combines SQLite FTS results with Qdrant semantic results via Reciprocal Rank Fusion (RRF).
### Why Qdrant Edge
Srclight is designed to stay local, private, and easy to run on a single machine.
Qdrant Edge gives srclight a persistent embedded vector engine without introducing a
remote service or requiring the runtime to load a whole embedding matrix into process
memory just to answer semantic queries.
This creates a clean architecture split:
- **SQLite** stores files, symbols, FTS indexes, edges, and lightweight embedding metadata.
- **Qdrant Edge** stores dense vectors and handles nearest-neighbor retrieval.
That split keeps structural search and semantic retrieval independent while preserving
srclight's offline, local-first deployment model.
### Embedding Providers
| Provider | Model | Quality | Local? | Notes |
|----------|-------|---------|--------|-------|
| **Ollama** (default) | `qwen3-embedding` | Best local | Yes | Needs ~6GB VRAM |
| Ollama | `nomic-embed-text` | Good | Yes | Lighter, works on 8GB VRAM |
| **Voyage AI** (API) | `voyage-code-3` | Best overall | No | Requires `VOYAGE_API_KEY` |
| **OpenAI-compatible** (any) | any model | Varies | Depends | See below |
The `openai:[model]@[base_url]` scheme encodes the endpoint inline — no extra flags or env vars needed. For example:
```bash
# Voyage Code 3 (API, highest quality)
VOYAGE_API_KEY=your-key srclight manage index --embed voyage-code-3
# LM Studio (local)
srclight manage index --embed "openai:text-embedding-embeddingsgemma-300m@http://localhost:1234"
# vLLM (local)
srclight manage index --embed "openai:text-embedding-model@http://localhost:8000/v1"
# HuggingFace TEI (local)
srclight manage index --embed "openai:your-model@http://localhost:8080"
```
### Project Configuration (`.srclight/config.json`)
The `.srclight/config.json` file stores project-level embedding configuration. It is automatically created when you run `srclight manage index --embed [model]`, but can also be edited manually.
#### Schema
```json
{
"model": "qwen3-embedding", // Required: embedding model name
"openai": { // Optional: OpenAI-compatible provider settings
"base_url": "http://localhost:1234", // Optional: custom API endpoint
"api_key_env": "MY_API_KEY" // Optional: env var name for API key
}
}
```
#### Precedence Order
When resolving the embedding model, srclight uses this priority (highest to lowest):
1. **CLI flag** (`--embed`) — always wins when provided
2. **Project config** (`.srclight/config.json`) — read automatically during indexing
3. **Environment variables** (`OPENAI_BASE_URL`, `OPENAI_API_KEY`) — fallback for OpenAI-compatible providers
4. **Default** (Ollama) — used when no configuration is found
#### Automatic Configuration
The easiest way to create `.srclight/config.json` is via the CLI:
```bash
# Index with embeddings — automatically creates .srclight/config.json
srclight manage index --embed qwen3-embedding
# Workspace mode — creates config for each indexed project
srclight manage reindex -w myworkspace --embed qwen3-embedding
```
#### Manual Configuration
You can also create the file manually for more control:
```bash
# Create with model only
echo '{"model": "qwen3-embedding"}' > .srclight/config.json
# Create with OpenAI-compatible endpoint
cat > .srclight/config.json << 'EOF'
{
"model": "text-embedding-3-small",
"openai": {
"base_url": "http://localhost:8000/v1",
"api_key_env": "OPENAI_API_KEY"
}
}
EOF
```
#### Updating Configuration
To change the model after initial indexing:
```bash
# Re-index with new model — updates .srclight/config.json
srclight manage index --embed voyage-code-3
```
To remove the stored model (revert to no embeddings):
```bash
# Edit .srclight/config.json and remove the "model" key, or delete the file
rm .srclight/config.json
```
> **Note:** `.srclight/` is automatically added to `.gitignore`. Do not commit this directory — it contains large index files and local configuration.
#### MCP Configuration Updates
If you are configuring projects through MCP instead of the CLI, you can persist embedding settings directly when adding a workspace project or triggering a reindex.
```json
{
"path": "/path/to/repo",
"name": "repo-name",
"embed_model": "qwen3-embedding"
}
```
Or pass a full config object:
```json
{
"path": "/path/to/repo",
"embed_config": {
"model": "text-embedding-3-small",
"openai": {
"base_url": "http://localhost:8000/v1",
"api_key_env": "OPENAI_API_KEY"
}
}
}
```
Supported MCP flows:
- `manage` with `action="add"`: adds a repo to a workspace and optionally writes `.srclight/config.json`
- `manage` with `action="reindex"`: reindexes and optionally updates `.srclight/config.json` before embedding
`embed_model` is a shorthand for setting only the model. `embed_config` is the full structured form and is better when an LLM is configuring a custom OpenAI-compatible endpoint.
### Storage
Semantic-search data is split across SQLite and Qdrant Edge:
| Path | Purpose |
|------|---------|
| `.srclight/index.db` | Files, symbols, FTS indexes, graph data, and lightweight embedding-state metadata |
| `.srclight/config.json` | Project-level embedding model configuration |
| `.srclight/qdrant/` | Persistent Qdrant Edge shard containing embedding vectors |
Incremental embedding remains content-aware: srclight only re-embeds symbols whose
body content changed, then updates both the embedding-state metadata in SQLite and the
vector state in Qdrant Edge.
## Multi-Repo Workspaces
Search across multiple repos simultaneously. Each repo keeps its own `.srclight/index.db`; at query time, srclight ATTACHes them all and UNIONs across schemas.
```bash
# Add repos — the workspace is auto-created on the first add
srclight manage add --path /path/to/repo1 -w myworkspace
srclight manage add --path /path/to/repo2 -w myworkspace --name custom-name
# Index all repos (with optional embeddings)
srclight manage reindex -w myworkspace
srclight manage reindex -w myworkspace --embed qwen3-embedding
# Inspect the workspace
srclight manage list -w myworkspace
srclight manage status -w myworkspace
# Search a specific repo in the workspace
srclight search "Dictionary" --project repo1
srclight search "Dictionary" --path /path/to/repo1
# Start the MCP server (workspace= is per-request, not a serve flag)
srclight serve
```
**Git submodules** are not indexed automatically — `git ls-files` does not recurse into them. To index a submodule, clone it separately and add it as its own workspace project. See [docs/usage-guide.md](docs/usage-guide.md#git-submodules) for details.
## LLM & MCP Integration
Srclight supports two transport modes: **stdio** (one server per session) and **SSE** (persistent server, multiple sessions). SSE is recommended for workspaces.
### Reusable Agent Instructions
This repo uses a canonical cross-tool structure:
| File | Use |
|------|-----|
| `skills/srclight-usage.md` | Shared srclight usage skill / shared instruction source |
| `skills/srclight-manage.md` | Workspace management, embedding configuration, and uninstallation skill |
| `agents/srclight-specialist.md` | Specialist agent layered on top of the skills |
These files are the source of truth inside this repository. An LLM should map these canonical paths into each tool's expected structure. The shared pattern is: **skill first, specialist second**.
| Tool | Shared layer | Specialist layer |
|------|--------------|------------------|
| Claude Code | Map `skills/srclight-usage.md` into `AGENTS.md` or `CLAUDE.md` | Reusable prompt / overlay built from `agents/srclight-specialist.md` |
| OpenCode | Skill from `skills/srclight-usage.md` | Subagent from `agents/srclight-specialist.md` |
| Codex | Map `skills/srclight-usage.md` into `AGENTS.md` | Specialist prompt layered from `agents/srclight-specialist.md` |
| Cursor | Rules / project instructions from `skills/srclight-usage.md` | Specialist overlay or custom reusable agent from `agents/srclight-specialist.md` |
| GitHub Copilot | `.github/copilot-instructions.md` | Narrow specialist prompt if your workflow supports one |
| General tools | Shared project instructions from `skills/srclight-usage.md` | Optional specialist prompt from `agents/srclight-specialist.md` |
An LLM configuring the environment should treat `/skills` and `/agents` as the canonical repo structure, then adjust the final destination paths for the target tool.
### Srclight-First Configuration
To ensure your AI coding agent uses srclight for code search instead of raw grep/glob, do **not** put the base srclight search policy directly in root markdown.
Instead, make the canonical policy flow through this chain:
1. `agents/srclight-specialist.md` — the narrower srclight-focused specialist
2. `skills/srclight-usage.md` — the shared search policy loaded by the specialist
3. `skills/srclight-manage.md` — workspace management, embedding configuration, and uninstallation
The README should stay high-level: explain the canonical files, how to map them into a target tool, and how to verify the integration. The reusable search policy itself belongs in the skill, with any narrower role guidance in the specialist.
#### Step 1: Initialize the Repository
Before configuring instructions, ensure srclight is indexed. Depending on your setup, you can choose between **Single-Repo Mode** and **Multi-Repo Workspace Mode**.
##### When to Use Which Mode?
- **Single-Repo Mode**: Best for working within a single standalone project. Setup is instant and doesn't require explicit project registration. Fallbacks resolve to the MCP client's root path or the CLI execution directory automatically.
- **Multi-Repo Workspace Mode**: Best when your agent works across multiple independent repositories or packages. Enables simultaneous cross-project searching and lets you target specific projects using `path` or `project` parameters.
##### Option A: Single-Repo Mode (Zero Config)
Simply navigate to your project root and index it directly:
```bash
# Navigate to your project root
cd /path/to/your/project
# Index the codebase (with embeddings for semantic search)
srclight manage index --embed qwen3-embedding
# Verify the index is up to date
srclight manage status
```
##### Option B: Multi-Repo Workspace Mode
For multi-repo setups, add each repository to a workspace — the workspace is created automatically on the first add:
```bash
# 1. Add repositories — the workspace is auto-created on the first add
srclight manage add --path /path/to/repo1 -w myworkspace --name repo1
srclight manage add --path /path/to/repo2 -w myworkspace --name repo2
# 2. Index all workspace repositories (with embeddings for semantic search)
srclight manage reindex -w myworkspace --embed qwen3-embedding
# 3. Verify workspace status
srclight manage status -w myworkspace
srclight manage list -w myworkspace
```
Expected output should show:
- Files indexed count > 0
- Symbols extracted count > 0
- Database size > 0 MB
#### Step 2: Map the Canonical Instruction Chain
Map the canonical files into your tool instead of rewriting the policy in root docs:
| Tool | Shared skills | Specialist layer |
|------|---------------|------------------|
| Claude Code | `skills/srclight-usage.md` + `skills/srclight-manage.md` → `AGENTS.md` or `CLAUDE.md` | Layer `agents/srclight-specialist.md` on top if you want a named srclight-focused helper |
| Cursor | `skills/srclight-usage.md` + `skills/srclight-manage.md` → project rules / shared instructions | Layer `agents/srclight-specialist.md` on top for a narrower helper |
| OpenCode | Both as skills | `agents/srclight-specialist.md` as the subagent |
| GitHub Copilot | `skills/srclight-usage.md` + `skills/srclight-manage.md` → `.github/copilot-instructions.md` | Optionally derive a narrower specialist prompt from `agents/srclight-specialist.md` |
| Codex / general tools | `skills/srclight-usage.md` + `skills/srclight-manage.md` → shared instruction layer | Apply `agents/srclight-specialist.md` second if the tool supports a narrower agent |
Rule of thumb:
- **README** — architecture, integration shape, verification
- **Skill** — base srclight search policy and operating procedure
- **Specialist** — narrower role, invocation cues, and constraints
#### Step 3: Verify Srclight-First Workflow
Test that srclight is working correctly:
```bash
# Check index status
srclight manage status
# Test symbol search
srclight search "main"
# Test semantic search (requires embeddings)
srclight search "handles dictionary lookup" --kind semantic
# Test hybrid search (FTS5 + embeddings)
srclight search "parse"
# List all tools available
srclight serve & # Start server, then test in your IDE
```
#### Troubleshooting
**Problem:** srclight returns no results
- **Solution:** Run `srclight manage index --embed [model]` to rebuild the index
**Problem:** Semantic search fails
- **Solution:** Ensure embeddings are generated: `srclight manage index --embed qwen3-embedding`
**Problem:** Agent still uses grep/glob
- **Solution:** Verify the tool is loading `skills/srclight-usage.md` (and `agents/srclight-specialist.md` if used) instead of relying on duplicated root markdown policy
> **Pro Tip:** The `.srclight/` directory is automatically gitignored. Do not commit it — it contains large index files and local configuration.
### Ask an LLM to Configure srclight
If your tool can edit config files or run terminal commands, you can ask it to wire srclight up for you. A good generic prompt is:
```text
Configure srclight for this environment. First detect whether this tool supports MCP, CLI-only usage, or both. If MCP is available, prefer SSE for shared workspaces and stdio for a single-repository setup. If MCP is unavailable, configure a CLI-only workflow and verify it with a simple srclight search. Reuse skills/srclight-usage.md as the shared instruction source. If this tool supports reusable agents, create the srclight specialist from agents/srclight-specialist.md and make sure it loads or imports skills/srclight-usage.md as its base skill.
Canonical repo structure: use skills/srclight-usage.md as the shared skill and agents/srclight-specialist.md as the narrower specialist overlay. Do not rewrite the base srclight search policy directly in root markdown if the tool supports a reusable skill/agent chain. Instead map those canonical files into the target tool's expected locations, such as AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, Cursor rules, or an OpenCode skill/agent definition.
```
Ask the LLM to finish by verifying the setup with one of these checks:
- "List srclight tools"
- "What projects are in the srclight workspace?"
- `srclight search "main"`
### Shared Integration Pattern
Across most tools, the setup pattern is the same:
1. Install srclight and index the repo or workspace.
2. Start `srclight serve` for MCP-based workflows, or use the CLI directly.
3. Add the server or command to the tool's MCP configuration.
4. Load `skills/srclight-usage.md` first, then layer `agents/srclight-specialist.md` on top if the tool supports specialist agents.
5. Verify with a simple symbol or workspace query.
> For detailed setup instructions for Claude Code, Cursor, OpenCode, OpenClaw, Claude Desktop, and any SSE-compatible client, see [docs/INTEGRATION.md](docs/INTEGRATION.md).
## MCP Tools (3)
Srclight exposes 3 MCP tools. The MCP server includes built-in instructions that guide AI agents on which tool to use and when, as agents receive a session protocol, tool selection guide, and `path`/`project` repo-targeting documentation automatically on connection.
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `search` | Find code, symbols, files by keyword, semantic, or hybrid search | `query`, `symbol`, `file`, `kind`, `symbol_kind`, `project`, `path`, `workspace`, `limit` |
| `trace` | Explore relationships, call graphs, git history, build targets | `symbol`, `type`, `project`, `path`, `workspace`, `transitive`, `ref`, `n`, `author`, `since`, `platform`, `limit` |
| `manage` | Control the index, workspaces, and server | `action` (list\|status\|index\|reindex\|add\|optimize\|stats\|restart\|workspaces), `path`, `project`, `name`, `embed_model`, `embed_config` |
Pass `workspace=` to `search` and `trace` for cross-repo ATTACH+UNION search. Add `project=` (CSV: `"repo1,repo2"`) to narrow to specific repos. In single-repo mode, no selector is needed — MCP root is used automatically.
Unregistered repo paths may be passed explicitly by `path`. They are used as-is and are never auto-added to the workspace.
### Unified Output Formats
To simplify agent parsing and support instant transition between code contexts, both `search` and `trace` tools return structured JSON envelopes wrapping a unified results schema.
#### Search Envelope
The search tool returns a flat result array wrapped in an envelope containing:
- `"tool"`: `"search"`
- `"query_info"`: Metadata about the executed query and active filters
- `"results"`: Array of matching result objects (see Unified Results Schema)
- `"errors"`: Object mapping error type → message (omitted when empty)
- `"summary"`: Object with `"total_results"` and `"categories_found"`
*Note: Legacy `"modes_run"` and `"result_count"` keys are no longer present.*
#### Trace Envelope
The trace tool returns a keyed result structure wrapped in an envelope containing:
- `"tool"`: `"trace"`
- `"query_info"`: Metadata about the target symbol and active trace types
- `"results"`: Object mapping active trace types (e.g., `"callers"`, `"dependents"`) to arrays of trace result objects
- `"errors"`: Object mapping error type → message (omitted when empty)
- `"summary"`: Object with `"total_results"` and `"categories_found"`
- `"symbol_definition"`: Optional. Full definition of the queried symbol (symbol-scoped traces only)
#### Unified 10-Field Results Schema
Every result returned (whether in search matches or trace nodes) has EXACTLY 10 fields:
- `id`: Globally unique identifier for the result item.
- `name`: Name of the symbol or file.
- `kind`: Category or symbol kind (e.g., `class`, `function`, `file`).
- `file`: Repository-relative path of the file.
- `line`: Start line number of the matching definition or context match.
- `content`: Code snippet or extracted text, using safe standard markdown `**` bold markers for matches instead of raw angle brackets or `>>>`/`<<<` markers.
- `relevance_score`: Relevance or confidence score ranging from `0.0` (lowest) to `1.0` (highest).
- `project`: Name of the project/repository.
- `navigation`: Shortcuts designed for direct agent transitions:
- `open_file`: Navigation path/command to open the file.
- `go_to_line`: Command/instruction to view the specific line.
- `get_symbol`: Direct lookup query/command to get full symbol details.
- `metadata`: Key-value properties of the matching item (such as taxonomy categories, change history details).
## CLI Commands
Srclight client (`srclight`) provides 5 commands for search, trace, indexing/workspace management, MCP serving, and setup:
| Command | Description | Key Options |
|---------|-------------|-------------|
| `search` | Run a unified search (keyword, semantic, exact symbol, file) | `[QUERY]`, `-s/--symbol`, `-f/--file`, `-k/--kind`, `--symbol-kind`, `-p/--project`, `--path`, `-w/--workspace`, `-n/--limit`, `-j/--json-output` |
| `trace` | Trace relationships, call graphs, git history, and blast radius | `[SYMBOL]`, `-t/--type`, `-p/--project`, `--path`, `-w/--workspace`, `--transitive`, `--ref`, `-n/--number`, `--author`, `--since`, `--platform` |
| `manage` | Manage index / workspace state (status, index, reindex, add, list, workspaces, etc.) | `[ACTION]` (status\|index\|reindex\|add\|optimize\|list\|stats\|restart\|workspaces), `--path`, `-p/--project`, `--name`, `--embed-model/--embed`, `-w/--workspace` |
| `serve` | Start the MCP server (supports stdio and SSE transports) | `-t/--transport` (stdio\|sse), `-p/--port` (default: 8742) |
| `setup` | Install/uninstall tool integrations | `--path/-p`, `--apply/-a`, `--remove/-r`, `--all`, `--platform/-t`, `--components/-c` |
| `hook` | Manage git auto-reindex hooks | `install`, `uninstall`, `status` |
Backend utility commands are exposed via `srclight-backend`:
| Command | Description |
|---------|-------------|
| `daemon` | Run the backend gRPC daemon for client RPC calls |
## Deployment Guide
See **[docs/usage-guide.md](docs/usage-guide.md)** for the full deployment and usage guide, including:
- Setting up srclight as a global MCP server for Claude Code
- Adding/removing repos from workspaces
- What happens on commits and branch switches
- Re-embedding workflows
- Troubleshooting
## Auto-Reindex (Git Hook)
Keep indexes fresh automatically:
```bash
# Install post-commit + post-checkout hooks in current repo
srclight hook install
# Install across all repos in a workspace
srclight hook install --workspace myworkspace
# Remove hooks
srclight hook uninstall
```
The hooks run `srclight manage index` in the background after each commit and branch switch.
## How It Works
1. **tree-sitter** parses every file whose extension maps to a supported language — 300+ languages via `tree-sitter-language-pack`, including infra formats (HCL, Terraform) and config DSLs. Language detection and cascade classification are **independent pipelines**: a `.tf` file gets both tree-sitter symbol extraction (HCL grammar) and infra/terraform classification simultaneously.
2. **Document extractors** handle non-code files (PDF, DOCX, XLSX, HTML, CSV, images, email, text) — extracting headings, tables, pages, and metadata as searchable symbols. Scanned PDF pages are optionally OCR'd via PaddleOCR.
3. Symbols (functions, classes, methods, structs, etc.) are extracted with full metadata
3a. **Cascade auto-classification** (SchemaStore + puremagic) assigns every indexed file an `extension`, `category`, and `subcategory` tag independently of whether tree-sitter parsed it. Source-code files are classified but stored only in `symbols`; non-source files (infra, config, spec, data, documents) are additionally stored in `context_artifacts`.
4. Three **SQLite FTS5** indexes are built with different tokenization strategies:
- **Names**: code-aware tokenization (splits `camelCase`, handles `::`, `->`)
- **Content**: trigram index for substring matching
- **Docs**: Porter stemming for natural language in docstrings
5. **Community detection** clusters symbols into functional modules via Louvain algorithm on call-graph edges, with TF-IDF auto-labeling
6. **Execution flows** are traced via BFS from entry points, and **impact analysis** scores each symbol's blast radius (LOW/MEDIUM/HIGH/CRITICAL)
7. Optional: **embedding vectors** are generated via Ollama or Voyage API and stored in a per-project **Qdrant Edge shard** (`.srclight/qdrant/`) for fast nearest-neighbor retrieval
8. The **MCP server** exposes structured query tools that AI agents call instead of grep
9. **Hybrid search** merges FTS5 keyword results and semantic embedding results via weighted Reciprocal Rank Fusion: exact name matches carry weight 2.0, general FTS matches carry weight 1.0, and embedding results carry weight 0.7 (k=60, Cormack et al. 2009). Semantic results below cosine similarity 0.45 are discarded before merging. The combined RRF score is normalized to `[0.0, 1.0]` using a ceiling of `2.7 / (k + 1)` — the maximum achievable by a result confirmed by both exact-name FTS and the vector index simultaneously.
### Architecture (Workspace Mode)
```
repo1/.srclight/index.db ──┐
repo2/.srclight/index.db ──┼── ATTACH ──→ :memory: ──→ UNION ALL queries
repo3/.srclight/index.db ──┘
```
Each repo is indexed independently. At query time, SQLite's ATTACH mechanism joins them into a single searchable namespace. Handles more than 10 repos via automatic batching (SQLite's ATTACH limit).
