Scc Sdk

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. scc is taken on npm, crates.io, PyPI and Homebrew by unrelated projects: npm install -g scc installs a 2013 SeaJS bundler, brew install scc installs a Go line counter (boyter/scc), pip install scc installs 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 are scc-sdk on npm and scc-sdk on 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

1. Install SCC and run scc init in the repository.
2. Run scc index — cold on first run, incremental afterwards.
3. Ask for a task pack before planning or editing: scc context task "<goal>".
4. For cross-layer changes, run scc impact <files> and honor the reported contracts, invariants, and downstream consumers.
5. Before trusting the model after external changes, run scc verify; re-index if it reports staleness.
6. In CI, gate with scc ci check and 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 the scc binary, 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).