SCS is a headless code-intelligence service. It indexes source repositories and
lets coding agents investigate them through a local MCP tool. An agent asks
query_code a question; SCS returns bounded evidence from its structural and
semantic index.
SCS starts with an empty index. It enrolls a repository only after an explicit CLI, MCP, or client request, and never changes repository source.
- Stable releases support Apple Silicon macOS and x86-64 Linux with CPython 3.14.
- Indexing needs an embedding provider. The default uses the OpenAI embeddings API and sends source-derived entity text to it. Local providers are available.
- Laya is an optional, local Apple Silicon feature for choosing query playbooks. SCS works without Laya on both supported platforms. SeeLaya requirements for its measured memory use.
Download the installer and checksum manifest from the same GitHub Release, verify the installer, and install SCS:
VERSION=0.2.0
curl -fsSLO "https://github.com/leonardoventurini/scs/releases/download/v${VERSION}/scs-installer-${VERSION}.sh"
curl -fsSLO "https://github.com/leonardoventurini/scs/releases/download/v${VERSION}/SHA256SUMS"
shasum -a 256 -c SHA256SUMS --ignore-missing
sh "scs-installer-${VERSION}.sh"
scs version
On Linux, use sha256sum -c SHA256SUMS --ignore-missing. The installer
verifies its wheel and constraints, installs without sudo, and uses a pinned,
checksum-verified uv binary when necessary. Current macOS releases are not
Apple-signed or notarized. See
distribution and upgrade details.
Configure an embedding provider before indexing. For the default OpenAI
provider, put this in ~/.scs/config.toml:
embedding_provider = "openai"
embedding_model = "text-embedding-3-large"
embedding_dimension = 3072
openai_api_key = "replace-with-your-key"
Keep the file owner-readable only (chmod 600 ~/.scs/config.toml). See
embedding configuration for local provider and
reranking options.
Register the installed stdio bridge with Codex, then index the repository containing your current directory:
codex mcp add scs -- "$HOME/.local/bin/scs" mcp
codex mcp get scs
scs index "$PWD"
scs status
If an existing scs MCP entry points elsewhere, remove it first with
codex mcp remove scs. Restart open Codex clients after changing MCP
configuration. Indexing runs as a durable background job; use scs status or
get_graph_stats to check when it is ready. The path above assumes the
installer's default ~/.local/bin location.
agent goal + repository + optional anchors
|
v
validate request and paths
|
v
select one of seven playbooks <--- optional local Laya classifier
|
v
bounded index search and graph reads
|
v
evidence + routing + trace + completeness
For example, an agent can ask:
query_code(
goal="Find tests affected by changes to the parser",
repo_path="/repo",
file_paths=["src/parser.py"],
mode="balanced",
)
The fast, balanced, and thorough modes set fixed time and evidence
budgets. Results show which playbook ran and whether evidence was complete,
truncated, or degraded. See the MCP tool reference for
anchors, tool contracts, and the
query_code migration guide for retired tools.
SCS indexes supported source files structurally. Other regular UTF-8 text files can be indexed at file level for lexical and semantic search. Git ignore rules and size limits apply. Once a repository is enrolled, SCS watches Git-visible changes and updates its index in the background. See indexing and project management for coverage, limits, reindexing, and deletion.
The default OpenAI embedding provider sends source-derived entity text to the configured API. SCS does not send whole repository files to a summarization service. You can instead configure a local OpenAI-compatible server or an in-process MLX provider. Provider details and trust controls are in embedding configuration.
On Apple Silicon, Laya can choose one of SCS's bounded query playbooks. SCS runs Laya in its own local MLX worker process; it does not call an external inference service. Laya receives the goal and explicit anchors, not repository source, embeddings, or retrieved evidence. SCS performs the search and graph reads. Without Laya, routing follows deterministic rules.
Resource example: On a Mac Studio M3 Ultra, the pinned model bundle occupied about 807 MB on disk, and a warmed Laya worker measured about 5.2 GB of physical memory footprint on 2026-09-24. This is one observed measurement, not a fixed minimum; usage can vary by host and workload. Laya is disabled unless explicitly configured.
To enable it from a source checkout on Apple Silicon:
uv sync --all-groups --extra laya
uv run --extra laya python scripts/install-laya.py
Add decision_model = "laya" to ~/.scs/config.toml, then run
uv run --extra laya scs daemon restart from that checkout. The release
installer installs the base tool without the optional Laya dependency.
The installation script downloads and verifies a pinned model bundle;
queries never download a model. A configured daemon reports ready only
after its worker loads and warms. If inference fails during a query, SCS
reports degradation and uses deterministic routing.
scs list shows enrolled projects and their stable numeric IDs.
scs reingest ID|PATH forces a full rebuild, and scs delete ID|PATH
removes only SCS-owned derived state. scs doctor checks daemon health;
scs metrics --days 7 --json reports aggregate operations without query
text, source text, file paths, job payloads, or results. See
indexing and project management for lifecycle details.
Each MCP client runs a small stdio bridge. Bridges share one lazily started
daemon, which shuts down after the last bridge disconnects. Persistent state
lives under SCS_HOME. See architecture for storage,
runtime ownership, and legacy-index migration.
For a source checkout:
just setup
just verify
just eval-search
just setup syncs dependencies, builds the private native extension, and
installs the repository's pre-commit hook. just verify runs strict
Basedpyright checks, Ruff, Python tests with branch coverage, and the Rust
workspace tests. Search and query evaluation guidance lives in
evals/README.md.