Crate comindly 

Comindly — deterministic, cross-repo code intelligence for coding agents.

One crate, one module per pipeline stage: model (SCIP identity + Symbol/Edge) → parse (tree-sitter) → git (incremental) → resolve (cross-repo binding) → index (LanceDB/S3 store) → graph (ripple/thread/…) → embed (Model2Vec + hybrid rank) → llm (enrichment) → mcp (agent server).

Modules

cache

Local mirror of a remote (S3) index for latency-sensitive readers such as agent hooks: the graph as a local Lance dataset and the ledger as one JSON file, refreshed in the background when stale. Writes still go to the remote store.

checks

Compiled constraint checks: forbid [<edge-kind>] from <sel> to <sel> and forbid dep <pkg> [<ver>], where a selector is <glob over repo/path>[::<glob over name>].

config

Comindly configuration — persistent defaults for the data location and model choices.

configvals

Values from a repo’s YAML config files (config*.yml, settings*.yml, application*.yml), kept as facts so settings paths the code cannot resolve (config.task_queue.queue) still name their queue, bucket or URL.

conventions

Conventions engine: measured coding conventions per repo, with support counts, central exemplars and counterexamples, mined from facts and the graph. An LLM may phrase them; it never invents them. Conventions shared by several repos form the org baseline.

credentials

~/.config/comindly/credentials: your LLM API keys, a default and optionally one per team name. Created readable only by you and never shared; OPENAI_API_KEY is the fallback.

doctor

Setup checks shared by comindly doctor and the web UI’s setup page.

embed

Comindly embed — local static embeddings for semantic code search.

eval

Graph-quality evaluation: compare resolved edges against a gold set (expected.toml).

facts

Per-file syntactic facts the parser extracts and the resolver binds: imports, references (as dotted paths) and type hints. Scope ids are rendered GlobalSymbolIds.

git

comindly-git — git change detection for incremental indexing.

graph

Comindly graph — the query layer a coding agent actually consumes.

hosting

Lists the repositories of a GitHub organisation or user, or a GitLab group (with subgroups), so they can be picked and cloned. Works with github.com, GitHub Enterprise, gitlab.com and self-hosted GitLab.

index

Comindly index — the versioned LanceDB store (local dir or S3).

infra

Terraform: queues, topics and buckets a repo declares or looks up, and which queues subscribe to which topics. Becomes contract facts on the .tf file’s symbol.

lang

Per-language syntax adapters. The generic walk in crate::parse asks each question of the file’s language; adding a language means implementing LangSpec for its grammar.

ledger

Reasoning ledger: why code is the way it is — decisions, failed attempts, constraints — as typed, symbol-anchored, append-only records in the user’s own store (<index-dir>/_ledger/inbox/<uuid>-<hash>.json, written create-only so writers never clash). Status (active, moved, stale, orphaned, superseded, retracted) is derived at read time.

llm

Comindly LLM enrichment — per-symbol summaries, symbol-aware query generation, and a repo style guide, via Rig (provider-agnostic: OpenAI by default; any OpenAI-compatible endpoint via COMINDLY_LLM_BASE_URL; Bedrock/Vertex/others can be added behind cargo features).

manifests

Packages and versions from manifests and lockfiles: what each repo publishes and depends on, so internal dependencies map to the repo that publishes them (and version skew shows).

mcp

Comindly MCP server — the code graph as tools a coding agent calls live.

model

Comindly core domain model.

packages

Importable module names for repo files: Python source roots (pyproject.toml, src/ layout) and TS/JS packages (package.json name + entry point).

parse

Comindly parse — tree-sitter extraction of symbols, the Contains hierarchy and per-file facts.

preflight

Preflight: before a change lands, what the team already knows about the code it touches — recorded constraints and dead ends, contracts other services rely on, blast radius, and directories that usually change together but are missing from the change.

recipes

Recipes from history: when commits add code in a directory, which other directories change with it (“adding a route also touches models/ and tests/api/”), with an exemplar commit.

resolve

Comindly resolve — bind per-file facts to definitions, within and across repos.

scip

SCIP ingestion: compiler-grade definitions and references attached to per-file facts.

search

Hybrid code search: native LanceDB retrieval (BM25 + vector via RRF) followed by comindly’s code-aware rerank — definition/exact-name boosts, structured path penalties, LLM-query recall boost, and a dependency-graph centrality signal no pure search tool has.

server

Server mode (on when COMINDLY_PUBLIC_URL is set): members, invitations, sign-in links, sessions, personal access tokens and encrypted secrets, in SQLite next to comindly’s data.

signing

Optional SSH signatures on ledger records, with the key developers already sign git commits with (ssh-keygen -Y, namespace comindly-ledger). A signature that does not verify against allowed_signers drops the record to T0; unsigned records are unaffected.

storage

Index storage at any location LanceDB opens: a folder, s3://, gs:// or az://. Credentials, region and endpoint come from the platform’s own environment, never from comindly.

styleguide

Evidence for the multi-pass LLM style-guide synthesis.

team

Team settings, stored with the index (<index>/_team, a versioned LanceDB table) so everyone using it runs the same LLM, embedding model and LLM steps. No secrets: each member’s API key comes from their own credentials file or environment.

tui

comindly ui: a terminal UI over the index — overview, contracts, ledger, explorer and conventions. Data loads once; rendering is a pure function of the app state.

ui

Terminal UI helpers — styled status lines, spinners, and progress bars.

web

Web UI (comindly ui --web): one embedded page over a small JSON API. Locally it answers on localhost to the link’s token; in server mode members sign in. Ledger writes go to the index root.

worktree

comindly’s own checkout of each repository’s default branch: a detached git worktree under ~/.cache/comindly/worktrees, so indexing never touches your working folder or branches. Uses the git command, so your SSH keys and credential helpers apply.