Sinter

sinter

A local code knowledge graph for coding agents, shipped as one static binary. sinter builds a typed, directed graph of a repository's symbols with tree-sitter and keeps it fresh incrementally. Start in an unfamiliar repository with sinter map: it returns a bounded structural inventory with module node/file counts, dependency hubs measured by graph in-degree, documentation entry points, and graph-health limitations. It does not infer runtime entry points or domain ownership. Then use the graph for focused work:

• Reverse blast radius — what transitively depends on a symbol, cross-file and cross-language (sinter affected). Traversal stops at hubs and names them; test dependents are counted, not listed, unless asked for.
• Paths — how one symbol reaches another (sinter path).
• Diff impact — which symbols and tests a changeset can affect (sinter impact), plus --expect for the unfinished-refactor check: direct dependents of a symbol the diff did not touch.
• Bounded text search — a regex search whose corpus is a graph traversal (sinter grep ' ' --within 'affected( )'), replacing the run-affected-then-grep-the-files pipeline.
• Polyglot, zero setup — syntax-only graphs work without an LSP. When the syntax provides the necessary type information, sinter resolves self receivers, locally typed receivers, typed fields, and explicit static/class calls. Complete receiver-call binding often requires a fresh SCIP index; zero setup is not compiler-complete resolution.
• Calibrated lexical navigation — sinter ask ranks content-bearing starting points from names, docs, paths, signatures, string literals, and limited call evidence. Its confidence line reflects the evidence class of the top hit; --explain adds the ranking-margin bucket and that bucket's holdout count with a 95% interval (the holdout is 46 cases, so the interval is wide). The bucket is not a per-result probability; ask is a navigator, not a semantic answer engine.
• Symbol orientation — sinter show turns a selected symbol into a compact card with its definition (attributes included) and a one-line used-by tally; --body adds the source (whole when it fits in 60 lines, else up to the byte budget), --impls the type's impl blocks, and show @file:line names the enclosing symbol. A span over 8 KB or 200 lines is a black hole no body dump can show: the card outlines it instead, listing the nested definitions, literal branches and command literals inside it with their line numbers (--outline forces it).
• Task evidence packet — sinter context " " resolves identifiers in the task against real node names (fuzzy when needed, shown as term ~> symbol) and seeds from them, returning edit candidates, string literals and hand-maintained mirrors that mention the task's terms, and affected tests as runnable commands with the symbol that reached each. It never abstains while it has hits. Add --workspace to rank candidates across declared member repositories in one packet.
• Snapshot-scoped assertions — sinter assert no-callers checks depth-one call edges in an explicit corpus scope. Its decision is one of violated, holds_for_indexed_snapshot, or not_proven; it never claims runtime exhaustiveness. sinter assert deletable tallies every depth-one dependent across all scopes, grouped by scope.
• Citation maintenance — sinter cite emits a Markdown location with a stable symbol key. sinter verify-doc re-resolves managed citations and fails on moved, missing, invalid, or identity-free references.
• [Cross-repo workspaces](docs/workspaces.md) — federated graphs over many repos for distributed systems: blast radius, paths, and PR impact across service boundaries (--workspace).

The design rule underneath everything: evidence or nothing. An edge exists only when structural, scope, import, or compiler (SCIP) evidence binds a reference to a definition (workspace manifests may add operator-declared cross-repo links, and Rust trait impls add labeled dynamic dispatch fan-out so blast radius survives dyn Trait). Ambiguity resolves to nothing — "unresolved" is a first-class, counted outcome, never a guess. Every edge carries its evidence kind, and every query can filter on it. Be clear about what that buys without a compiler: syntax-only evidence binds names it can prove by scope and imports and leaves the rest (receiver calls, re-exports, macros) unresolved, so the zero-setup graph is a precise subset, not the full graph. sinter scip closes that gap where a compiler index is available.

Install

Package managers:

cargo install sinter-io        # or: cargo binstall sinter-io (prebuilt)

uv tool install sinter-io # or: pipx install sinter-io brew install shellfu/tap/sinter

All of them put a binary named sinter on PATH. Or the one-liner, no dependencies (Linux and macOS; verifies the release checksum, installs to ~/.local/bin):

curl -fsSL https://raw.githubusercontent.com/shellfu/sinter/main/scripts/install.sh | sh

Windows, in PowerShell (new and less battle-tested; verifies the release checksum, installs to %LOCALAPPDATA%\sinter\bin):

irm https://raw.githubusercontent.com/shellfu/sinter/main/scripts/install.ps1 | iex

To verify a manually downloaded release asset against its GitHub build provenance attestation (requires the gh CLI):

gh attestation verify sinter-<target>.tar.gz --owner shellfu

PyPI wheels carry sigstore provenance via Trusted Publishing. Once installed, sinter update self-updates from GitHub releases.

Or build from source (requires a Rust toolchain):

cargo build --release

Quickstart

Agents that only need a usable local graph should create derived state without installing hooks or editing client configuration:

sinter ensure /path/to/repo

This command only builds or refreshes .sinter/. It is safe to run within a read-oriented coding flow.

Onboard a repository — builds the graph, installs git hooks, registers agent integration (AGENTS.md block, MCP), and finishes with a doctor report:

./target/release/sinter init /path/to/repo

Init prints everything it is about to write, grouped by scope, and asks once before writing any of it (-y skips the prompt; a non-interactive run prints the plan and proceeds). Every write lands inside the repo — nothing under ~/.claude is touched unless --global is passed, which adds the machine-wide skill card and enforcement hooks. Both init and ensure append .sinter/ to the root .gitignore when the repository is a git worktree and no existing line covers it.

Repo-local Claude hooks use bounded strict enforcement: the first broad recursive search in a session is redirected to Sinter, while a retry is allowed with a fallback-search reminder. Machine-wide hooks installed by --global remain advisory.

On a terminal, init asks before running compiler indexers (sinter scip) because those toolchains execute repository build scripts; pass --scip or --no-scip to answer up front (non-interactive init skips them).

After that, every query self-syncs at the query boundary — when nothing changed, the sync is a stat-only walk (no file reads, no write transactions) — and the git hooks refresh eagerly on commit; sinter build stays available for CI and scripting. Commands also work from any subdirectory, discovering the graph root the way git does. The build report distinguishes the heuristic's anchored miss rate from compiler-relative accuracy. The anchored rate is useful without SCIP but is not recall: the heuristic can classify a compiler-resolvable reference as external.

resolution (this pass): ... resolved (scip 0, import 118, scope 189), ... unresolved (105 internal, 3193 external)

anchored miss rate (this pass): 25.5% (heuristic classification, not compiler-relative recall)

When a SCIP index is present, the report also prints the compiler cross-check (what share of internally-bound refs agree with the compiler) and internal recall vs the compiler (how many compiler-bound refs sinter found without SCIP). Files edited since the index was built get no SCIP evidence at all — their references fall back to import and scope resolution rather than being rebound by byte position — so a stale index never attributes a call to a name that no longer sits on that line. Files the grammar could only parse partially are counted in one build line (N parsed partially (M symbols in them; …)); sinter doctor --verbose lists them.

Orient before searching so the next query uses the repository's own module and symbol vocabulary:

sinter map /path/to/repo

The map is the first-pass inventory. Use ask next when the target is still a concept rather than a known symbol.

Ask a question against the graph (output shown for this repository):

$ sinter ask "where is the trigram search"

1. function Store::search [doc+name+path+sig 2/2 terms] crates/sinter-store/src/search.rs:148 /// Fuzzy candidates: nodes sharing the most trigrams with the query, pub fn search(&self, query: &str, limit: usize) -> Result , StoreError>

ask is a calibrated lexical navigator, so treat its hits as places to inspect rather than generated answers. Every hit shows its match provenance and the text card carries one confidence line (confidence: high — verify top hit) rated from the top hit's evidence; a weak top hit is unrated. String literals that match the question are listed after the symbol hits, and fixture, example, and test-local definitions rank below production ones with the same evidence. Agent JSON groups results by topic under one strict result budget and keeps each hit lean: rank, name, kind, file, line, signature, doc, matched terms, channels, and a one-word confidence. --explain (text or JSON) adds the ranking margin, query-term coverage, the named holdout calibration, and per-hit scores. Query terms expand through a small synonym table (cap, limit, budget; size, bytes; caller, dependent) at reduced weight, so a literal match always outranks a synonym. Weak singletons, low term coverage, and undersampled ranking-margin buckets abstain. CLI JSON and MCP structuredContent.data use the same payload.

Every affected, deps, and path response is deliberately bounded. deps defaults to depth 1 (--max-depth widens). affected stops at hubs (fan-in over 100, or a seed with more than 50 direct callers) and says so (stopped at hub Store (fan-in 114); --through-hubs to continue). Both count test-scope rows instead of listing them (--include-tests), and --relations calls,uses drops file-level import rows. path -k N returns up to N node-disjoint routes; a miss prints the closest frontier, the edges the filter excluded, reason: filter_excluded when a filter caused it, and a retry to run. In --json, positive and negative answers carry a coverage summary (completeness, conclusive, snapshot, compiler-index state); --coverage restores the repository-wide block with evidence sources, certain and possible result counts, unresolved-reference counts, and explicit gaps. The universe field names the repository root or every declared workspace member searched. completeness describes only the indexed snapshot and conclusive remains false, so agents do not turn a non-empty syntax-only result into an exhaustive claim.

Agent-facing node id values are stable symbol keys and survive unrelated offset shifts. snapshot_id retains the byte-exact locator for the reported snapshot. Handle-consuming operations accept if_snapshot and return typed stale-snapshot, relocated-handle, or ambiguous-candidate outcomes instead of silently rebinding. A