Crate comindly_engine 

comindly as a server: the web app and its /api/v1, MCP for agents, indexing jobs, members and roles, and the backends that keep them, plus this machine’s preferences and credentials. Re-exports the engine, so comindly_engine::index is comindly_core::index.

Re-exports

pub use comindly_api as api;

Modules

agents

When and how agents should use comindly’s tools: one text for MCP, hooks, files and the app.

answers

What the read commands answer, computed the same way on this machine and on a server, so a command run with --server prints what a local run would.

backends

What a server stores and how it signs people in, as traits; server::Store and Smtp are the defaults.

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>].

client

The command line’s client for an engine’s /api/v1: typed requests, its error shape, job events and signing in by browser approval.

config

Your preferences on this machine — which index to open, the repositories this machine indexes, and how your ledger records are named and signed — kept in a versioned LanceDB table in comindly’s config folder. A TOML file of the same shape can be imported and exported. What an index runs with is stored with the index; a server keeps its settings in its database.

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.

context

What a call into core needs, passed in rather than looked up: where the index lives, the settings it runs with, the LLM, where events go, and when to stop.

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, and the server comindly login signed you in to. Readable only by you and never shared; OPENAI_API_KEY is the fallback key.

docstore

One settings document in a LanceDB table: each save is a new table version, recording who changed it and when, and a save based on an older version is refused.

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).

events

What core reports while it works: steps, results, warnings and progress, as structured events. The CLI renders them in the terminal; a server keeps them with the job, streams them to the app and writes them to its log.

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).

indexer

Index jobs run in a child comindly index-job, so the memory a run takes goes back when it ends.

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.

jobs

Work the server runs in the background, indexing for now: jobs run one at a time in order, each with a record, a status and its events kept in a JobStore; followers get them live.

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.

oidc

Sign-in through an OpenID Connect provider: the authorization code flow with PKCE.

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.

pipeline

Indexing: check out repositories, parse and bind them across repositories, persist the graph, then the optional steps (search embeddings, summaries, style guides, flow walkthroughs). Async and cancellable; CPU-heavy work runs on the blocking pool; progress goes to the context’s reporter. LLM output is saved as it is written and reused while its input is unchanged, so an interrupted run continues where it stopped.

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.

prompts

The LLM prompts indexing uses: built in (v0) or an activated version, stored with the index (<index>/_team, table prompts), for what the next index writes; nothing is redone for them.

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.

rt

Running async code from synchronous callers (CLI commands, the terminal UI, blocking-pool work): one shared runtime for the process, never one per call.

run

Starting an engine: a team server when COMINDLY_PUBLIC_URL is set, else a local one for this machine’s command line and app.

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 a LanceDB table next to the index.

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.

sources

File contents of the indexed commit, kept in the index so code can be shown without a checkout.

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.

telemetry

The process’s logs and traces: tracing events rendered as readable lines or, with COMINDLY_LOG_FORMAT=json, one JSON object per line; spans sent over OTLP when configured.

ui

Terminal UI helpers — styled status lines, spinners, and progress bars; with COMINDLY_LOG_FORMAT=json, the same messages as one JSON event per line.

view

What the apps show of an index — graph, contracts, ledger, conventions, dependencies — read once.

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.