System Context Compiler
Compile repositories into evidence-backed system context for coding agents.
Install · Publishing · Getting started · Context packs · System IR schema · Adapters · Benchmarks · Contributing
SCC continuously compiles code, configuration, infrastructure, runtime evidence, tests, and declared architectural intent into a verified machine model of the software system — then emits small, task-specific context packs so AI coding agents start every task with correct system understanding instead of rediscovering it through search. Every fact carries a provenance class and points at the exact evidence that supports it; stale facts never enter trusted context.
Give agents more repository understanding per token, not more repository text.
How it works
flowchart LR
A[Source code] --> B[Reality Graph]
C[Config and infra] --> B
D[Runtime traces] --> B
E[Intent] --> B
F[External analyzers] --> B
B --> G[System IR]
G --> H[System Atlas]
H --> I[Context Compiler]
I --> J[Context packs]
J --> K[Coding agents]
K --> L[Exact tools]
L --> A
The authority chain is strict:
runtime observation + compiler/LSP facts > deterministic extraction
> declared architecture > high-confidence inference > memory > model assumption
Inferred claims are labeled with confidence and evidence and never silently promoted. STALE facts are excluded from trusted packs and surfaced as warnings. Conflicts between evidence sources are recorded, not merged.
Capabilities
Quick start
Install
One path. It verifies the checksum before it installs:
curl -fsSL https://raw.githubusercontent.com/carterlasalle/scc/main/scripts/install.sh | sh
scc --version
That installs the latest release to ~/.local/bin/scc (Linux x86_64, macOS
arm64). Prefer pinning? Pass a version: sh install.sh --version 0.2.7.
Homebrew works too: brew install carterlasalle/tap/system-context-compiler.
Alternatives: brew install carterlasalle/tap/system-context-compiler,
npm install -g @carterlasalle/scc.
Everything else — Docker, building from source, supported platforms,
uninstall, troubleshooting — is in docs/INSTALL.md.
Package names.
sccis taken on npm, crates.io, PyPI and Homebrew by unrelated projects:npm install -g sccinstalls a 2013 SeaJS bundler,brew install sccinstalls a Go line counter (boyter/scc),pip install sccinstalls Open Microscopy OME tools. The CLI ships through GitHub Releases, Homebrew, npm (npm install -g @carterlasalle/scc), and crates.io (cargo install scc-cli). The SDKs arescc-sdkon npm andscc-sdkon PyPI.
If you're using Oh My Pi, the native extension ships inside the binary:
scc setup omp # writes .omp/extensions/scc, MCP config, skill
Index your repository
cd /path/to/your/repo
scc init # .scc/config.yaml + database
scc index # cold index; incremental afterwards
scc context task "change transcript normalization"
scc setup claude # automatic Claude Code hooks
scc setup omp # Oh My Pi native extension + MCP
The full command surface is in the CLI reference and scc --help.
Local access
CLI
scc atlas | overview | context task <goal> | context component <id> | context flow <id>
scc impact [--diff HEAD~1] [files...]
scc verify | drift | ci check
scc bench context | resolution | agent --cmd <agent-cmd> | index
scc import scip|ccg|gitnexus|beads|cbm|hindsight <file>
scc resolve --lsp | scc embed
scc runtime status | reconcile
scc export system-ir.json | jsonl | ccg | capsule.md
Daemon and MCP
The local daemon implements docs/openapi.yaml on loopback only (security.listen, default 127.0.0.1:7777):
Agent integrations
SDKs: TypeScript (scc-sdk, source in sdk/typescript) and Python (scc-sdk, source in sdk/python) wrapping the CLI.
Extend SCC without forking it: drop a scc-plugin.toml + JSON-over-stdio command into .scc/plugins/<id>/ and your operation joins the engine registry (scc plugin list / invoke / doctor / lock / check). Five-minute echo example and the rules that bite: Installing SCC → Plugins.
Application workflow
- Install SCC and run
scc initin the repository. - Run
scc index— cold on first run, incremental afterwards. - Ask for a task pack before planning or editing:
scc context task "<goal>". - For cross-layer changes, run
scc impact <files>and honor the reported contracts, invariants, and downstream consumers. - Before trusting the model after external changes, run
scc verify; re-index if it reports staleness. - In CI, gate with
scc ci checkand the context benchmark:scc bench context --min-recall 0.9.
Start with the implementation plan (phases 0–12 and the MVP cut) and the context compiler spec.
Architecture
SCC is a Rust workspace with deliberately narrow crate boundaries:
crates/
scc-core/ System IR types, provenance, identifiers, token budgeting
scc-store/ SQLite persistence (WAL + FTS5), migrations, snapshots
scc-indexer/ Scanning, extractors, resolvers, LSP, evidence adapters
scc-graph/ Components, flows, invariants, boundaries, co-change
scc-context/ Ranking, expansion, budgets, pack rendering
scc-cli/ CLI, daemon, MCP, plugins, benchmarks
adapters/ External evidence importers (beads, cbm, hindsight, context7)
sdk/ TypeScript and Python SDKs
plugins/ Hermes and Oh My Pi plugin packages
fixtures/ 8 golden repositories with ground-truth expectations
benchmarks/ tasks.json — 21 ground-truth tasks + hallucination probes
docs/ The full specification this implements
Extractors and adapters speak one evidence contract; analyzer-specific types never leak into the System IR. The adapter manifest declares filesystem/network/subprocess/credential use for every evidence source.
Safety model
SCC intentionally keeps repository analysis local and honest:
- Local-first by default. Source never leaves the machine; the daemon binds loopback only; remote inference and embeddings are opt-in.
- Secrets are never persisted. Config values are reduced to references; values are redacted before storage.
- Repository text is untrusted data. README/docs/comments are labeled (
DOCUMENTATION,UNTRUSTED TEXT) in context packs and never presented as system facts. - Path sandboxing. Symlink escapes and
..traversal are rejected; the Docker deployment mounts the repository read-only. - Provenance honesty. Inferred and memory-sourced claims are ranked below deterministic evidence; stale facts are excluded from trusted context; conflicts are surfaced.
- No telemetry. No repository content is exported; benchmarks emit only aggregate metrics.
The normative requirements are in docs/SECURITY.md.
Deployment status
SCC ships as a single static binary and supports three modes:
- Mode A — developer local (default):
scc serve— the daemon ships inside thesccbinary, SQLite, local parsers, loopback HTTP + MCP. No network dependencies. - Mode B — CI:
scc verify,scc drift,scc impact --diff origin/main...HEAD,scc ci check. CI can fail on stale generated IR, critical drift, ownership violations, broken invariants, or unapproved new boundaries. - Mode C — team server: post-MVP; not built.
Docker runs the daemon against a read-only repository mount with a writable state volume:
services:
scc:
image: system-context-compiler # built from the checked-in Dockerfile
volumes:
- .:/repo:ro
- scc-data:/data # SCC_STATE_DIR=/data (set in the image)
- ./docker/scc-config/.scc:/repo/.scc:ro # container-only config
environment:
# The daemon binds 127.0.0.1:7777 and refuses a non-loopback bind unless
# this is set — it has no authentication, so the opt-in is deliberate.
SCC_ALLOW_REMOTE_LISTEN: "1"
ports: ["127.0.0.1:7777:7777"] # never publish on 0.0.0.0
That container-only config must set security.listen: 0.0.0.0:7777 (the default
127.0.0.1 is unreachable through a published port), and the repository needs a
.scc/ directory before the container starts (scc init), because Docker
cannot create that mountpoint under a read-only mount. On Linux you can skip all
of it by sharing the host network instead. Both recipes, verified against the
daemon, are in docs/INSTALL.md.
Benchmarks
Reproduce them: scc bench context --min-recall 0.9, scc bench resolution, scc bench index --files 1000 --lines 250, or cargo test -p scc-cli --test perf cold_index_250k -- --ignored.
Documentation
Contributing
This repository uses protected, squash-only pull requests with required checks. Read CONTRIBUTING.md before making changes — it covers the extractor contract, adapter writing, benchmark methodology, and the CI gates (cargo clippy --workspace -- -D warnings, the full test suite, and scc bench context --min-recall 0.9).
