sinter

<p align="center">
  <img src="assets/sinter_logo.png" alt="sinter logo" width="360">
</p>

# 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 <symbol>` 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 '<regex>' --within 'affected(<sym>)'`), 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 "<task>"` 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 <manifest>` to rank
  candidates across declared member repositories in one packet.
- **Snapshot-scoped assertions** — `sinter assert no-callers <symbol>` 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 <symbol>` tallies every
  depth-one dependent across all scopes, grouped by scope.
- **Citation maintenance** — `sinter cite <symbol>` emits a Markdown location
  with a stable symbol key. `sinter verify-doc <file.md>` 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<Vec<Node>, 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, k