knot

knot is a high-performance codebase indexer that extracts structural and semantic information from source code, enabling AI agents to understand, analyze, and navigate large code repositories. Currently supports Java, Kotlin, TypeScript, JavaScript/Node.js, Rust, Python, Groovy, C/C++, C#, HTML, and CSS/SCSS, plus Build Systems (Maven pom.xml, Gradle build.gradle, Jenkins pipeline, Cargo.toml, MSBuild .csproj + Directory.Packages.props), Configuration Files (YAML, JSON, .properties — optional), Kubernetes + Helm (optional), and Cross-Repo Dependency Linking with full cross-language linking.

For recent release notes see CHANGELOG.md.

The indexer automatically builds:

• Vector Search Database (Qdrant) — semantic understanding via embeddings

• Graph Database (Neo4j) — architectural relationships via call graphs

This dual-database approach powers both:

• MCP (Model Context Protocol) Server — Exposes read-only tools (search, callers, explore, list_files, list_endpoints, repos, deps) to any LLM client (Claude, Gemini, ChatGPT, Cursor, etc.)

• CLI Tool — Standalone knot command for terminal and scripting environments

Knot in action

CLI — instant reverse dependency lookup

MCP — JSON-RPC protocol for AI agents

🧮 Token Efficiency — Measured, Not Claimed

An LLM agent exploring an unfamiliar codebase pays for every byte it reads. Without an index it greps and then reads whole files; with knot it receives a targeted answer. The difference was measured on three real indexed repositories across nine realistic exploration tasks:

≈ 11× fewer tokens for the same nine questions — 205 000 tokens saved, enough to keep a long refactoring session inside a single context window. Measured with knot 1.15.1 on 2026-11-01, on a clean index.

Both sides are measured on the exact bytes an LLM would receive as tool output, counted with OpenAI's cl100k_base tokenizer (tiktoken):

The baseline is deliberately generous, so the measured saving is a lower bound:

• greps are restricted to the source files of the language (-t java, -t ts, -t rust) — no changelogs, no generated docs, no node_modules;

• for discovery the baseline is given oracle file selection: it reads only the files that answer the question, with zero wasted reads;

• for callers it reads at most 5 files, while a rigorous impact analysis would need every file with a textual hit.

Honest caveats: knot's cost scales with the number of results, not with repo size. callers answers list the references made from production code and count those made from test code (+N in tests, issue #52). Listing them too (include_tests, CLI --include-tests) costs 16 422 / 773 / 1 003 tokens for the three callers rows and brings the total saving to 84.8%: ToolCallingManager has 394 references, 320 of them in tests, and format_references_result is called mostly by unit tests. The explore rows for large files are the least favourable, because signatures plus docstrings are a large fraction of a well-documented file.

How the answers shrank on the same snapshots (knot tokens, 9 tasks): 59 579 with knot 1.12.4, 53 806 with 1.14.1 (compact search and explore answers, #50) and 28 373 with 1.15.0 (compact callers answers, #52), all on an index built incrementally that still held the stale entities of #53; 20 266 with 1.15.1 after a --clean re-index. The callers rows alone went from 29 772 to 4 194 tokens. The clean re-index also changed rows of repositories without stale entities (re-computed embeddings and edges), by a few hundred tokens.

Repositories measured (as indexed): spring-ai 2 490 files / 27 775 entities (commit b6b5767), puppeteer 1 286 files / 11 733 entities (08e7b1a), knot 390 files / 5 956 entities (421b515). Raw measurements are stored in .perf_metrics/token_savings.json.

pip install tiktoken            # optional: falls back to a chars/4 estimate
# edit the `root` paths in scripts/token_savings_tasks.json to match your checkouts
python3 scripts/token_savings_benchmark.py \
  --config scripts/token_savings_tasks.json \
  --save-json .perf_metrics/token_savings.json

The task definitions live in scripts/token_savings_tasks.json and the harness in scripts/token_savings_benchmark.py; point them at any repository you have indexed to measure your own codebase.

Related MCP server: MCP-RAG

✨ Key Features

🔍 Code Intelligence Tools

• search_hybrid_context: Semantic + structural search. Find code by meaning, class name, method signature, docstrings, or comments. Returns full context including dependencies.

• find_callers: Reverse dependency lookup. Identify dead code, perform impact analysis, or understand the full call chain of any function/method. Whenever the query resolves to more than one entity sharing the same name (e.g., find_nearest_entity_by_line in different files), results are automatically grouped by target (### Target: <fqn> at <file>:<line>) showing which specific entity each caller references — including when only one of the homonyms has callers. A genuinely single-target resolution keeps the concise ungrouped form. Supports cross-repository call resolution via DEPENDS_ON graph edges. A call whose receiver type is declared in the caller's own repository never binds to a dependency's same-named type, even when the local member is not indexed (macro-generated, derived, annotation-processed): it stays unresolved instead. Likewise, a call on a type no indexed repository declares (JDK, standard library, third-party package: String.valueOf(..), a field typed ModelMapper) never binds to a repository method that merely shares the callee's name. In Java and Kotlin, an unqualified type name — a call receiver, a receiver named after its type (config → Config), an extends or a type reference — resolves through the caller file's imports: a single-type import (or Kotlin as alias) first, then the file's own package, then on-demand imports (com.x.*), so same-named types of different packages are never mixed up; an import of a type no indexed repository declares leaves the call unresolved. For JVM languages (Java/Kotlin/Groovy) it also surfaces method-level OVERRIDES edges bidirectionally — an Overridden by group listing subtype implementations/overrides and an Overrides group listing the supertype methods a method implements/overrides — plus a Dispatched calls group listing callers that reach the queried method through dynamic dispatch (bound to an override or to the supertype method), so an interface method called only through its implementation (or vice versa) is never reported as unused.

• explore_file: File anatomy inspection. Quickly see all classes, interfaces, methods, functions, constants, and other entities in a file with signatures and documentation. Attribute-usage markup tokens (html_class, html_id) are summarized in a separate section by default to avoid cluttering code lists; use --include-markup (CLI) or include_markup: true (MCP) to list them in full. Structured content returns markup_count and markup_references alongside ambiguous_path_candidates.

• list_repo_dependencies (MCP) / knot deps (CLI): Dependency graph visualization. Show which repositories depend on each other, forward and reverse, with transitive resolution.

• list_files (MCP) / knot files (CLI): Read-only file enumeration with entity counts, deterministically ordered. Accepts an optional path — a repo-relative directory prefix matched on a path boundary (src/api never matches src/api-notes.md) or a glob (src/**/*_test.rs). Prefixes and globs alike page the repository file list in pages of 2000 entries with per-page boundary filtering, ensuring no valid candidates are dropped. When output exceeds 2000 matches, a truncation notice is displayed below the table reporting the exact pre-truncation match count when known (or an explicit lower bound when the scan stopped early). JSON output carries total_matches and total_is_lower_bound. Pair with the new --path/path scope on search_hybrid_context to restrict a semantic search to a subtree.

• list_endpoints (MCP) / knot endpoints (CLI): HTTP endpoint catalogue. Lists the endpoints Java and Kotlin code serves — JAX-RS (class/method @Path + @GET/@POST/…) and Spring MVC (class @RequestMapping + @GetMapping/… or @RequestMapping(method = …)) — as <METHOD> <path> with the handler method each one routes to. Class and method paths are joined, path arrays expand, path-variable patterns are dropped ({id: [0-9]+} → {id}), and string constants resolve whether declared in the same file or in another file of the repository (found through imports and package; Kotlin const val templates included). Filters: method (case-insensitive; ANY, a @RequestMapping without method, matches every method) and path (segment-wise prefix where an endpoint's {variable} segment matches any value, so a concrete URL such as /api/owners/42 finds GET /api/owners/{id}). Each endpoint is an http_endpoint entity linked to its handler by a ROUTES_TO edge: find_callers on a handler lists it under HTTP routes (a handler reached only over HTTP is never reported as unused), explore_file groups a resource's endpoints under HTTP Endpoints, and search_hybrid_context finds them by route. Paths are relative to the application — the context path (server.servlet.context-path, @ApplicationPath) is not applied to the listed paths. Declarative clients (@FeignClient, @RegisterRestClient, @HttpExchange interfaces) are not endpoints, and interfaces generated at build time (OpenAPI generator) are not in the source tree. An unresolved constant stays visible as <expression>.

• HTTP client linking (Java/Kotlin, heuristic): every routed method of a declarative client — OpenFeign (@FeignClient), MicroProfile REST Client (@RegisterRestClient), Spring HTTP interface (@GetExchange/@HttpExchange) — and every imperative call — RestTemplate (getForObject, postForEntity, exchange(url, HttpMethod.X, …), …), WebClient / RestClient (.get().uri(…), .method(HttpMethod.X).uri(…)) — becomes an http_client_call entity (GET /api/items/{id}, base URL path applied), and after every indexing run an HTTP_CALLS edge links it to the endpoint it hits, across every indexed repository and whatever the indexing order — no build dependency between client and server is needed. Each recomputation is a single transaction serialized across concurrent indexers (cluster nodes sharing Neo4j), so readers never see the edges half replaced and the last run sees every repository. The subgraph query (knot-server's graph API) accepts HTTP_CALLS. find_callers on a handler or endpoint lists the client calls under HTTP callers (heuristic: client call → endpoint), and explore_file groups them under HTTP Client Calls. Base URLs come from the annotation (url, path, baseUri) or the client's configuration (spring.cloud.openfeign.client.config.<name>.url, quarkus.rest-client.<key>.url, <key>/mp-rest/url, ${prop:default} placeholders); the application* / bootstrap* .yml|.yaml|.properties and microprofile-config.properties files are read for this even without --include-config-files (test sources excluded). The Feign service name and the URL host select the servers whose spring.application.name / quarkus.application.name match; a server's context path (server.servlet.context-path, spring.mvc.servlet.path, quarkus.http.root-path, @ApplicationPath, …) may or may not appear in the client path. Verbs must agree (ANY matches all), {variable} segments match any value, at least one literal segment must match exactly, and the most literal endpoint wins (/items/{id} over /items/export); when several endpoints match equally well nothing is linked. Imperative calls are recognised textually (put / delete only on a receiver declared as RestTemplate / RestOperations), belong to the method containing them, and their URL is evaluated from literals, concatenation, Kotlin templates, constants, @Value("${…}") fields and parameters, URI.create, String.format and UriComponentsBuilder / uriBuilder path(…) calls: an unknown leading part (a baseUrl variable) stands for scheme and host, an unknown later part for a {variable} segment ("/items/" + id → /items/{id}), and a relative URL takes the base of the file's single baseUrl(…) / rootUri(…) builder call. Test code is skipped. Not covered yet: Java's HttpClient, base URLs set in another file (treated as unknown), and a change to a client's configuration alone (re-index with --clean).

• list_repositories / knot repos: Repository inventory. List every indexed repository along with its entity count, file count, build system, and primary language. Supports optional case-insensitive name filtering via --filter (CLI) or filter parameter (MCP). Useful for orientation, sanity-checking indexing runs, and discovering which languages and build systems are present in the workspace.

🧩 Reference Resolution

• Deterministic edge targets: when a reference matches several candidates at once — a receiver call whose FQN search hits a method name reused across module paths (pkg.alpha.Widget.render vs pkg.beta.Widget.render), a short class name that suffix-matches several fully-qualified classes (pkg.alpha.ChatModel vs pkg.beta.ChatModel), or a VCL include whose basename matches several files (alpha/shared.vcl vs beta/shared.vcl) — the edge always lands on the same target. Candidates are ranked by a total order: a target declared in the caller's own file first, then the lexicographically smallest FQN, then the smallest UUID. Recall is unaffected: an edge is created whenever at least one candidate matches, and only the choice of target among genuinely ambiguous candidates is decided. Cyclic re-export aliases collapse to the smallest UUID in the cycle and are fully path-compressed, independently of hash-map iteration order.

🏗️ Multi-Language Support

• Java: Full AST extraction with package-aware FQN resolution (e.g., com.example.app.UserService), class inheritance (EXTENDS), interface implementation (IMPLEMENTS), annotation tracking, and declared-type receiver resolution for fields (including this.field), record components, method/lambda/catch parameters, local, loop and try-with-resources variables, and pattern variables (instanceof Type x, case Type x). Scoping is respected: an inner declaration with the same name shadows the field even when its type is unknown (var, untyped lambda parameters, multi-catch), so the field's type is never applied to a different variable. Calls and method references (expr::method) on interface-typed fields resolve to the interface declaration regardless of variable naming, while hierarchy-aware resolution links inherited interface methods. Calls to overloaded methods bind by argument count within the receiver class and its supertypes (foo.bar(1, 2) → Foo.bar(int, int), varargs and default parameters accepted), never to a same-name/same-arity method of an unrelated class. Arity narrows name-only candidates but never picks a target on its own. A var local takes its type from a new initializer (var r = new TextRenderer() → TextRenderer, so a third-party type leaves the call unresolved). A receiver whose type stays unknown (var m = factory.create(), untyped lambda parameters) binds by method name alone only to a method whose type is visible from the caller's file — in the caller's package, imported (single-type or on demand), or nested in an imported type; Kotlin applies the same rule (top-level functions must be imported or in the caller's package). Bare calls and languages without imports (Python, JavaScript, Groovy) keep the name-only fallback.

• Kotlin: Complete support for Kotlin codebases with classes, interfaces, objects, companion objects, functions, methods, and properties. Fully compatible with tree-sitter-kotlin-ng grammar. FQNs carry the file's package (com.example.app.Config.load, top-level functions com.example.app.bootstrap), so same-named types in different packages stay distinct for find_callers, explore_file, search and OVERRIDES. Calls carry their argument count (a trailing lambda counts as one), so calls to overloaded methods bind by arity within the receiver class and its supertypes.

• C#: Full C# support via tree-sitter-c-sharp. Extracts classes, interfaces, structs, records (both record class and record struct), enums, methods, constructors, properties, fields (with const detection), delegates, events, indexers, operators, local functions, and namespaces with CSharp* entity kinds. Namespace-qualified FQNs (MyApp.Services.UserService.GetUserAsync) work across both file-scoped (C# 10+) and block-form namespaces, including nested namespaces and nested types. The base_list heuristic splits : Base, IFace into EXTENDS/IMPLEMENTS using the IPascalCase convention (structs and interfaces are deterministic), generic arguments are stripped (IRepository<User> → IRepository), XML doc comments (///) become docstrings, and attributes ([Obsolete]) are captured as decorators. Calls through field-typed receivers resolve to the exact implementation method, and C# virtual/override plus interface implementation produce method-level OVERRIDES edges. MSBuild/NuGet: .csproj files are parsed for project identity and dependencies (Central Package Management via Directory.Packages.props is supported); C# repos get build_system: "nuget" in the Repository node instead of the prior "none".

• TypeScript/TSX/CTS: Complete support for modern JavaScript/TypeScript codebases, including CommonJS TypeScript files. Calls bind to the overload signature whose arity matches (bar(a): T; bar(a, b): T); a this: parameter is not counted. this.m() binds to the enclosing class's method or, failing that, to the nearest superclass declaring it. Each class member reports only the decorators written directly before it (@computed, @action, @Get(...)), never those of an earlier member. A this.x read, write or argument that is not called is a member access: it produces a REFERENCES edge to a field (so find_callers on a field lists its readers and writers as references, not invocations) and a CALLS edge only to a getter or method (this.total, app.use(this.handler)); this.m() stays a call

• JavaScript/Node.js: Vanilla JS, Node.js, and module systems (.js, .mjs, .cjs, .jsx). Arity never constrains call resolution in JavaScript, where every parameter is optional. In both JavaScript and TypeScript, a const / let / var declared inside a function, method or arrow body is a local and is not indexed; module-level constants, class fields and local function definitions are. Function locals and parameters passed as call arguments are treated as values rather than callbacks, and receiverless calls obey module visibility (same-file or imported callable), so locals never bind to fields of unrelated modules

• Hybrid Web Ecosystem: Cross-language linking between JavaScript, HTML, and CSS for full-stack SPA analysis

• HTML: Custom elements (Web Components, Angular), id and class attribute indexing for cross-language CSS search

• JSX/TSX Attributes: Extracts id and className from React components for unified HTML/CSS discovery

• CSS/SCSS: Stylesheet indexing with class/ID selector extraction and variable tracking (CSS/SCSS variables, mixins, functions)

• Rust: Struct, enum, union, trait, function, method, module extraction with trait implementation tracking (IMPLEMENTS relationships) and macro invocation references. Methods are indexed with the qualified FQN Type::method (e.g., KnotMcpHandler::new, WidgetA::new, Logger::new) and qualified calls from top-level functions resolve to the right target by receiver. Method calls through self, a field path (self.repo.save()) or a call chain (self.builder().finish(), x.iter().map(..).sum()) produce CALLS edges: self.m() binds to the enclosing type by its crate-anchored FQN, and other compound receivers bind only when their last path segment names the type (self.repo → Repo). They never fall back to an unrelated method that merely shares the name, so std calls like .collect() or .as_str() stay unbound. Braced import/use capture — use foo::{Bar, Baz} and use foo::Bar as Baz produce explicit REFERENCES edges for all imported names, including traits imported solely to bring methods into scope. All Rust entity FQNs are now anchored at the owning crate and module path (e.g. knot::config::Config, knot::pipeline::parser::languages::rust::qualify_rust_fqns), so two crates that declare a type with the same bare name no longer collide. Files outside src/ (tests, benches, examples) receive a __fixture::<path>::<Entity> FQN prefix (e.g. __fixture::tests::testing_files::sample::Config), and files without a Cargo.toml ancestor receive __loose::<path>::<Entity>, preventing name collisions with real source entities. CONTAINS relationships use enclosing_class_fqn for exact disambiguation when multiple entities share the same class name. The on-disk index state file (.knot/index_state.json) carries a version field; opening a state file from an older version prints an error with instructions to run knot-indexer --clean.

• Python: Full Python extraction with class, function, method support, constants, module-level imports, ValueReference tracking for keyword arguments, class inheritance (EXTENDS), decorator extraction (@property, @staticmethod, @route(...), @dataclass), generic type hints (List[str], Optional[Dict], *args/**kwargs), Py2/Py3 exception syntax compatibility, and self.method() resolution with inherited method walking. Captures class_definition, function_definition (including async via optional async modifier), lambda assignments, and distinguishes methods from functions via parent context detection. Class instantiation (ClassName(...)) is automatically redirected to ClassName.__init__ so find_callers ClassName.__init__ lists every constructor call site (with fallback to inherited __init__ via the extends chain); only class/struct kinds trigger the redirect — functions keep the legacy behavior.

• Groovy: Full Groovy language support via hybrid tree-sitter + ad-hoc lexical parser. Extracts classes, interfaces, traits, enums, typed/def/quoted methods (incl. Spock specs), constructors, closures, script-level variables, fields/properties with visibility modifiers, nested classes, and decorators. Tracks package FQN and enclosing class relationships. Multi-line signatures (closure default params), assignment-vs-declaration disambiguation, innermost assignment for nested closures, UUID collision fix for duplicate method names, find_callers accurately tracks private methods including those in anonymous new AnAction closures. Inheritance tracking: emits EXTENDS/IMPLEMENTS reference intents for class/interface/trait/enum headers (single-line and multi-line) so find_callers surfaces real nextflow-style hierarchies — qualified parents (e.g. extends nextflow.plugin.BasePlugin) and generic-argument stripping (e.g. extends AbstractRepo<Order, Long> → extends AbstractRepo) are supported, and generic bounds (class Box<T extends Comparable>) are correctly not promoted to inheritance edges. Property accessors: bare property declarations (Path baseDir, boolean cacheable) are now indexed as GroovyProperty, and compiler-generated getX/setX/isX accessors are synthesised as first-class method entities so OVERRIDES edges link Groovy properties to interface getter declarations. Comment-stripping prevents Javadoc continuation lines (* The pipeline script name) from producing phantom entities or corrupting scope tracking. Calls whose only argument is a trailing closure (parts.each { ... }, withLock { ... }) are detected with arity one, with or without a receiver. Parenthesized calls carry their argument count (trailing closures included; named arguments, spreads and multi-line argument lists stay uncounted), and a trailing array parameter accepts varargs, so overloads bind by arity. Calls written on a method's declaration line — one-line methods such as String wide(Formatter f) { f.format('x', 80) }, including calls inside a one-line closure — belong to that method; the declaration itself (the method's name, its typed parameters) is never reported as a call. A receiver call a.b(..) is reported once, with its receiver, so a call on an unindexed type never binds to a repository method by its bare name.

• Build Systems: Maven pom.xml (dependencies + plugins via roxmltree), Gradle build.gradle (deps + plugins + tasks), Jenkinsfile pipeline (stages + steps), Cargo Cargo.toml (deps + workspace members + features), and MSBuild .csproj / Directory.Packages.props extraction. MSBuild resolves project identity (<PackageId> → <AssemblyName> → file stem), emits a BuildDependency per <PackageReference> (attribute-form and version-less), and resolves Central Package Management versions from the nearest Directory.Packages.props ancestor. UTF-8 BOMs are tolerated defensively. Identity marker identity: package_id is carried in the signature when the project has an explicit <PackageId> so the cross-repo resolver prefers published packages over depth-tied unmarked candidates. When several manifests sit at the same depth, the repository identity is picked deterministically (marker, then depth, then relative path), so it no longer changes between indexing runs.

• Cargo.toml: Rust package manager support with package metadata, features, workspace members, and multi-format dependency parsing (simple, table, git, path).

• Configuration Files: YAML (.yml/.yaml), JSON (.json), and Java Properties (.properties) with leaf-key granularity. Special handling for package.json (detected by filename: npm dependencies as BuildDependency, scripts as ConfigProperty, ProjectIdentity even for dependency-free library manifests).

• Varnish Cache: Hand-written parsers for .vcl (configuration), .vtc (test cases), and .vcc (VMOD C source). VCL extracts backends, probes, ACLs, subroutines (custom + built-in with vcl_* names, including aggregator entities for multi-part built-ins), import directives (with as aliases and from paths), include edges, unused declarations, VMOD instantiations, and req.backend_hint assignments. VTC extracts varnishtest/vtest cases, servers, clients, varnish instances, logexpect blocks, barriers, and -vcl+backend synthesised backends (with is_test_context). VCC extracts $Module, $Function, $Object, $Method, $Event, $Restrict, ENUMs, and default parameters. References: Calls, Extends, Implements, References (with intents VclSubCall, VclBackendRef, VclProbeRef, VclAclRef, VclInclude, VclVmodImport, VclUnusedRef, ValueReference); relationships: UsesBackend, UsesProbe, UsesAcl, Includes, ImportsVmod, DeclaredUnused. The Fastly VCL dialect is detected and skipped (returns empty entities).

• Kubernetes + Helm: K8s manifest parsing (Deployment, Service, ConfigMap, Secret, Ingress, Namespace) with label/annotation tracking and cross-resource references. Helm chart indexing (Chart.yaml metadata, values.yaml key-value pairs, template variable extraction via {{ .Values.X }}).

• C/C++: Complete C/C++ support with namespace-aware FQN resolution (Engine::MyClass::start), class/struct extraction, function/method tracking, macro definition and usage detection (uppercase identifier heuristic), type reference tracking (declarations, new expressions), and full call graph analysis. Supports .c, .h, .cpp, .hpp, .cc, .cxx, .hh, .hxx extensions via tree-sitter-c and tree-sitter-cpp parsers. Includes intelligent auto-detection for .h headers to parse them correctly as C or C++ based on their contents.

• Markdown: Documentation indexing with MarkdownDocument (one per .md/.markdown file) and MarkdownSection (one per ATX heading H1–H6). Section bodies — including paragraphs, fenced code blocks, lists, and tables — are captured into embed_text for full semantic search over documentation content, not just heading titles. FQNs are hierarchical and file-scoped (e.g. README.md::Setup > Installation > Linux), so same-named headings in different files or under different parents disambiguate cleanly. Section boundaries respect heading depth: a section's body extends until the next heading of equal or higher level, ensuring ### Linux under ## Installation does not bleed into a sibling ## Configuration. Headings with inline markdown (backticks, em-dash, links, emoji) parse without losing their bodies, and real start_line/end_line positions are computed via tree-sitter for each section.

📚 Rich Comment Extraction

• Captures docstrings (JavaDoc, JSDoc) preceding declarations

• Extracts inline comments within method/function bodies

• Respects nesting boundaries (class comments don't capture method comments)

• Intelligently aggregates comment blocks

📊 Dual-Database Architecture

• Qdrant: Vector search for semantic code understanding

• Neo4j: Graph relationships for structural navigation

🚀 High Performance

• Parallel Streaming Pipeline: Overlaps CPU-bound embedding with I/O-bound ingestion via MPSC channels

• Incremental Indexing: Uses SHA-256 hashes to skip unchanged files

• Real-time Watch Mode: Automatically re-indexes changed files in seconds via --watch

• Embed-Text Recall: Every entity's embed text carries its identifier surface — name, FQN and the camel/snake-case-tokenized form of both, plus the tokenized names of what it calls in its body. A function with no doc comment is still findable by the behaviour described in natural language ("authenticate user with email and password" surfaces a doc-less login through the normalize_email / verify_credentials vocabulary in its body). Rust signatures ((email: &str, password: &str)) survive extraction too. Requires one re-index when upgrading from an older index state version (automatic: old states are rejected with instructions).

• CPU Parallelism: AST extraction via Rayon

• Scalable: Configurable batch processing and constant memory footprint (~2GB) regardless of repository size

• Performance Benchmarking: Multi-level validation framework

  • Unit benchmarks: Criterion-based benchmarks for parse, embed, and graph write throughput (benches/)

  • E2E benchmarks: Full pipeline metrics capture with per-stage timing (tests/benchmark_e2e.sh)

  • CI regression tracking: Automated baseline comparison against tolerance thresholds (scripts/compare_perf_metrics.sh)

  • Token efficiency: LLM token cost of knot answers vs reading source files (scripts/token_savings_benchmark.py) — see Token Efficiency

🛠️ Installation

Prerequisites

Option A: Pre-compiled Binaries (macOS & Modern Linux)

Go to the Releases page and download the native executable for your platform.

Install knot binaries (CLI, MCP server, and indexer):

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/knot/releases/latest/download/knot-installer.sh | sh

Install agent-skills for your AI (Optional): Paste this into your LLM agent (Claude Code, OpenCode, Cursor, etc.):

Install the knot agent skills by following the instructions at: https://raw.githubusercontent.com/raultov/knot/master/README.md

The first command installs the knot binary to your PATH. The second (optional) allows your AI assistant to automatically download the agent skill index (.knot-agent.md) and run the installer to extract comprehensive guides for using knot CLI with AI agents and code analysis tools.

System Requirements:

• Linux: glibc 2.38+ (Ubuntu 24.04+, Debian 13+, Fedora 39+, Arch)

• macOS: Modern versions supported

• Windows: Use Docker (Option B)

Option B: Docker (Universal Compatibility)

Docker images provide universal compatibility for any Linux distribution and Windows.

Docker Installation (All Binaries)

Build the image:

docker build -t knot:latest . --network=host

Run the indexer:

# Use --network host to connect to databases running on your host machine
docker run --rm \
  -v /path/to/your/repo:/workspace \
  -e KNOT_REPO_PATH=/workspace \
  -e KNOT_NEO4J_PASSWORD=your-password \
  --network host \
  knot:latest \
  knot-indexer

Run the CLI tool:

docker run --rm \
  -v /path/to/your/repo:/workspace \
  -e KNOT_REPO_PATH=/workspace \
  -e KNOT_NEO4J_PASSWORD=your-password \
  --network host \
  knot:latest \
  knot search "user login flow"

Run the MCP server:

docker run --rm \
  -e KNOT_REPO_PATH=/workspace \
  -e KNOT_NEO4J_PASSWORD=your-password \
  --network host \
  knot:latest \
  knot-mcp

Note: Uses Debian Trixie (glibc 2.38+) and includes ONNX Runtime for full functionality.

Option C: Install via Cargo

cargo install --git https://github.com/raultov/knot

Option D: Build from Source

1. Start infrastructure with Docker:

docker compose up -d

2. Clone and build:

git clone https://github.com/raultov/knot
cd knot
cargo build --release

3. Configure:

mkdir -p ~/.config/knot
cp .env.example ~/.config/knot/.env
$EDITOR ~/.config/knot/.env  # Set KNOT_REPO_PATH and Neo4j credentials

4. Index a codebase:

./target/release/knot-indexer

5. Query via CLI:

./target/release/knot search "your query"

6. Start the MCP server:

./target/release/knot-mcp

📖 Usage

🤖 Install Agent Skills (For AI Agents)

Option A: Let an LLM do it

Paste this into any LLM agent (Claude Code, OpenCode, Cursor, etc.):

Install the knot agent skills by following the instructions at: https://raw.githubusercontent.com/raultov/knot/master/README.md

Option B: Terminal (Manual)

curl -sO https://raw.githubusercontent.com/raultov/knot/master/.knot-agent.md && curl -fsSL https://raw.githubusercontent.com/raultov/knot/master/scripts/install-agent-skills.sh | bash

📥 Quick Downloads (Binaries)

Download knot binaries (CLI + MCP server):

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/knot/releases/latest/download/knot-installer.sh | sh

📖 Agent-Skills Guides

Comprehensive documentation for using knot tools. The agent skills installer extracts:

• search.md — Semantic code discovery guide with examples

• callers.md — Reverse dependency lookup with critical usage rules

• explore.md — File anatomy inspection guide

• deps.md — Repository dependency graph guide

• repos.md — Indexed repository inventory

• workflows.md — Common patterns and best practices

For quick reference without downloading, see .knot-agent.md.

Using the CLI

The knot CLI provides the same capabilities as the MCP server via command-line commands, making it ideal for:

• Terminal-only environments

• Bash scripting and automation

• CI/CD pipelines

• Direct integration with other tools

Three main commands:

knot search — Semantic Code Search

knot search "user authentication" --max-results 10 --repo my-app
knot search "user authentication" --max-results 20 --repo "app-a,app-b"  # Union across repos
knot search "user authentication" --max-results 20 --repo all              # All indexed repos ('all' or '*')
knot search "user authentication" --kinds definition                        # Only functions/methods/types

Find code entities by meaning, class names, docstrings, or comments.

Ranking is kind-aware: function/method/class/struct definitions outrank markdown docs, test files, config properties and build-dependency entities for natural-language queries, and callers/helpers are shown as context attached to a definition — never as substitutes. The shared entry point of the highest-ranked helpers outranks those helpers, and an entity merely named after a generic verb (find, get, create, build, acquire, …) does not win on the bare verb unless its container (FQN) corroborates the query. Use --kinds to narrow the result types (aliases: definition, callable, class/type/struct, or exact kinds like rust_function).

knot callers — Reverse Dependency Lookup

knot callers "LoginService" --repo my-app
knot callers "LoginService" --repo "auth-service,billing-service"
knot callers "LoginService" --repo all
knot callers "com.x.Foo.bar(int, int)"                    # One overload by parameter types

Find all code that references a specific entity (dead code detection, impact analysis, call chains). Whenever the query resolves to more than one target sharing that name, results are automatically grouped by target (### Target: <fqn> at <file>:<line>) with file locations and signatures — including when only one of the homonyms has callers.

Overloads share one FQN in the index, and a trailing parameter list of types addresses a single one: com.x.Foo.bar(int, int) resolves com.x.Foo.bar with the usual tiers, then keeps the overloads whose declared parameter types match — simple type names (List, not java.util.List), generic arguments compared only when written (List matches List<String>), arrays and varargs as [] or ..., and name: Type accepted for Kotlin/TypeScript. When no overload matches, the answer lists the declared ones (No overload of com.x.Foo.bar takes (String). Declared overloads: …). The bare FQN still returns every overload, each labelled by its parameter list (### Target: com.x.Foo.bar(int, int)). Works on existing indexes: no re-index is needed.

Target resolution is code-only by default: documentation, configuration, build-system and Kubernetes/Helm entities (markdown_section, config_property, build_dependency, cargo_package, project_identity, k8s_*, helm_*, …) can never be presented as resolved targets. When the filter removes matches the response discloses them (Non-code matches hidden — N entities …) and names the fix (kinds=all to include them). A fuzzy query like cargo no longer fills the target list with Cargo.toml metadata. Fuzzy matching is also case-insensitive, so hikari finds Hikari-named artifacts. Queries shorter than 4 characters resolve by anchored name prefix rather than substring: knot callers use returns useSearch, useSources, useSaveCv and friends without dragging in every *STATUSES constant that merely contains use. Queries of 4+ characters keep the case-insensitive fuzzy substring fallback. Override the scope with --kinds all / MCP kinds:"all", or pass an explicit allow-list (--kinds callable, --kinds build_dependency).

The buckets cover every edge type the pipeline produces: Calls, Extends, Implements, References, Macro calls (Rust MACRO_CALLS), DOM references (JS → HTML element id), CSS class usage (JS → CSS class), script/stylesheet imports, the VCL edges (uses backend/probe/acl, includes, VMOD imports, declared-unused), HTTP routes (ROUTES_TO: the endpoint serving a handler), HTTP callers (HTTP_CALLS: the HTTP client calls hitting a handler's endpoint, heuristic) plus Overridden by / Overrides / Dispatched calls — so init_vec's macro call sites and app-container's JS manipulators now show up instead of a false "may be unused".

Every answer is self-labeling: the resolution block names each target's repository as (repo: <name>). When every reference belongs to one repository, the Found line names it once; when the scope spans several, every row carries its own (repo: <name>). The Markdown answer is compact (#52): one line per row, with the signature on that line when it is not empty, and a file's <module> row (its import) folded into the file's other rows. References made from test code (test files, Rust #[cfg(test)]) are included in every count but listed only with include_tests: true (CLI --include-tests); each group then ends with +N in tests. The JSON output is unchanged and lists every row, now with an is_test_context field.

# References to `LoginService`

Resolved to 1 target by exact name match:
- `auth::service::LoginService` (class) at `src/service.rs:12`  (repo: auth-service)

Found 3 reference(s) across all relationship types (repo: auth-service) — 1 in tests, counted but not listed (`include_tests` lists them):

## Calls (function/method invocations) (3)

- **`signup`** (function) at `src/handlers.rs:88` — `(form: SignupForm)`
- **`login`** (function) at `src/handlers.rs:120` — `(form: LoginForm)`
- +1 in tests (`include_tests` lists them)

In the CLI table the Target column is labeled only for genuine cross-repo references (a caller in repo A referencing a target in repo B); the Caller column is always labeled when a repository is known.

knot explore — File Structure Inspection

knot explore "src/services/auth.ts" --repo my-app

List all classes, methods, functions in a file with signatures and documentation.

knot deps — Repository Dependency Graph

knot deps my-app --depth 2           # Show forward dependencies (transitive)
knot deps my-app --reverse           # Show who depends on this repo

Visualize auto-discovered dependencies between indexed repositories with transitive resolution up to 3 levels deep.

knot repos — List Indexed Repositories

knot repos                          # Table with REPO / BUILD SYSTEM / LANGUAGE / FILES / ENTITIES
knot repos --filter app             # Case-insensitive name filter (substring match)
knot repos --output json            # Machine-readable list
knot repos --output markdown        # GFM table for chat UIs

Show the status of every repository currently indexed in the graph database — useful for orientation, sanity-checking that an indexing run completed, and discovering which languages and build systems are present across the workspace. Use --filter to quickly locate a specific repository when working with multiple indexed codebases.

Repository Scope Selection: Both the CLI --repo/-r flag and MCP repo_name parameter support:

• Single repository name: --repo my-app

• Comma-separated list: --repo "repo-a,repo-b" (MCP also accepts ["repo-a", "repo-b"])

• Sentinel: --repo all or --repo "*" (searches every indexed repository)

Note: Multi-repo scope applies a global max_results limit across the union. Increase --max-results (range 1-100, enforced; larger values are clamped and a note is printed — no pagination, narrow with --kinds/--path/--repo or refine the query instead) when searching across multiple repositories.

For detailed CLI usage guide, see .knot-agent.md — a machine-readable skill that teaches LLMs how to use knot CLI for autonomous code analysis.

Indexing a Codebase

Incremental Indexing (Default)

# First run: indexes all files
knot-indexer --repo-path /path/to/your/repo --neo4j-password secret

# Subsequent runs: only re-indexes changed files (fast!)
knot-indexer --repo-path /path/to/your/repo --neo4j-password secret

# NEW: Real-time Watch mode
knot-indexer --watch --repo-path /path/to/your/repo --neo4j-password secret

How it works:

• Tracks file content via SHA-256 hashes in .knot/index_state.json

• Stores the downloaded fastembed model in .knot/fastembed_cache/ to keep the workspace clean

• Automatically detects: modified, added, and deleted files

• Only re-parses and re-embeds changed files; a modified file's previous entities are deleted first, so an entity that moved or was removed never lingers as a duplicate

• Preserves graph relationships to unchanged files: edges from unchanged files (or other repositories) into a modified file are re-pointed at its re-indexed entities (same file, FQN, kind and signature); edges into entities that no longer exist are dropped

• Processes entities in memory-efficient 512-entity chunks

Performance:

• Initial index (3800 files): ~60 minutes on standard hardware

• Incremental update (3 files changed): ~5-10 seconds

• Memory usage: Constant ~2GB regardless of repository size

Full Re-Index (Clean Mode)

# Force complete re-index (deletes all existing data)
knot-indexer --clean --repo-path /path/to/your/repo --neo4j-password secret

Use --clean when:

• You want to rebuild the entire index from scratch

• You've changed Tree-sitter queries or embedding models

• Troubleshooting indexing issues

Upgrade note (v1.5.1): File paths are now persisted as repo-relative paths with POSIX separators (e.g. src/pipeline/embed.rs). Upgrading from v1.4.x triggers an automatic full re-index on first run — the on-disk .knot/index_state.json carries a version field that the loader rejects when stale, and knot-indexer then wipes the repo from both databases before rebuilding. No manual steps required. Entity UUIDs become machine-independent in the process: the same repo indexed from different checkout locations now produces identical UUIDs.

Indexing Progress

The indexer emits [Progress] log lines showing real-time completion across the whole pipeline (parsing, embedding, ingestion, reference resolution). The percentage is monotonically non-decreasing and reaches 100% only once the run genuinely terminates.

Upgrade note (v1.6.2): The percentage now spans the entire pipeline via weighted bands. Previously it measured only file reading and saturated at 100% within seconds of starting, then froze for minutes while embedding and ingestion were still running. See docs/specs/indexing_progress_accuracy_plan.md for the full design.

Example with 5000 files where 1000 have been parsed and 5,000 entities are half-way through ingestion:

[Progress] [my-repo] 50.0% — files 5000/5000, entities 41600/83200, batch #325 (128 entities)

Band table

A final log line confirms completion:

[Progress] [my-repo] 100.0% — files 5000/5000, entities 83200/83200 — parsing and ingestion complete, resolving references...

Library API (knot-server integration)

Callers that need to observe progress programmatically can use the ProgressTracker:

use std::sync::Arc;
use knot::pipeline::{ProgressTracker, run_indexing_pipeline_with_progress};

let progress = Arc::new(ProgressTracker::new());
let progress_clone = Arc::clone(&progress);

// Poll snapshot() from another task while the pipeline runs
tokio::spawn(async move {
    loop {
        let snap = progress_clone.snapshot();
        println!(
            "{:.1}% — files {}/{}, entities {}/{}",
            snap.percent_complete,
            snap.parsed_files,
            snap.total_files,
            snap.entities_ingested,
            snap.total_entities
        );
        if snap.stage == IndexingStage::Completed || snap.stage == IndexingStage::Failed {
            break;
        }
        tokio::time::sleep(std::time::Duration::from_millis(500)).await;
    }
});

run_indexing_pipeline_with_progress(&cfg, &vdb, &gdb, &mut state, progress).await?;

The snapshot() method is thread-safe (read-only locks + atomic loads) and returns a IndexingProgress struct that serializes directly to JSON for REST endpoints.

Running E2E Integration Tests

To ensure indexer stability, run the E2E integration test suite:

# Run all language E2E tests (TypeScript, Java, JavaScript, Web, Kotlin, Rust, ...)
./tests/run_all_e2e_fast.sh

# Run only Kotlin E2E tests
./tests/run_kotlin_e2e.sh

# Run only Rust E2E tests
./tests/run_rust_e2e.sh

# Run only C# E2E tests
./tests/run_csharp_e2e.sh

# Run only Varnish E2E tests
./tests/run_varnish_e2e.sh

See tests/KOTLIN_E2E_TESTS.md for detailed coverage and troubleshooting.

Using the MCP Server

The MCP server exposes five tools to any compatible AI client (built on rust-mcp-sdk 1.1 implementing MCP protocol 2025-11-25 with full tool annotations):

Embedding the tool surface: library consumers can serve the same five tools from their own transport (e.g. an HTTP /mcp endpoint) without going through the stdio server. KnotMcpHandler::tools() returns the canonical tool table (no state or database connection required), and KnotMcpHandler::dispatch(params) executes a tools/call without needing an Arc<dyn McpServer> runtime handle. The stdio ServerHandler methods delegate to these two entry points, so every surface stays identical by construction.

Tool 1: search_hybrid_context

Find code by meaning or keywords

Query: "How is user authentication implemented?"
Result: All auth-related code, signatures, docstrings, and dependencies

Capabilities:

• Semantic search by functionality (vector embeddings)

• Global multi-repository search by default (repo_name: "all")

• Class/method/function name lookup

• Docstring and inline comment search

• Architectural pattern discovery

• Full dependency context

Search ranking contract (kind-aware re-rank, query-time only):

1. Definition channel — alongside the plain cosine scan, a second bounded Qdrant pass excluding all non-code kinds guarantees code definitions enter the candidate pool even on documentation-heavy repositories (a prose-saturated cosine window once left the entry-point signal dead). An explicit documentation-scoped search (kinds=markdown_section, …) never sees the code channel.

2. Recall channels in one pool — cosine hits, the definition channel, the name/token probe (identifiers the query literally names) and the caller-recall bridge (callers of the top semantic roots — seeded from the union of channels, depth 1 + depth 2 in the call graph) all merge into one deduplicated pool before ranking.

3. Kinds — callables outrank type declarations, which outrank prose and config/build/infra; test paths carry an additional penalty. A neutral kind (constant, …) whose graph node orchestrates ≥ 2 outgoing CALLS edges earns a boost: a TypeScript MCP tool is export const x = defineTool({...}), and behavior is not the wiring's kind. Prose/config/test never take structural boosts.

4. Entry-point signal — how many of the top semantic roots a candidate calls, directly or through one helper, attributed to the caller covering a strictly greater root set with the full entry-point signature (≥ 2 distinct roots).

5. Name-prefix contract is definition-only — a query matching an entity's name keeps leading slots only for definition kinds; prose, config/build and k8s/helm prefix hits are demoted into the pool and ranked on their own cosine (documentation-only topics with no competing definition still surface their best section). Test paths keep their slot but stay penalized inside the re-rank.

6. Determinism — ties break on (file_path, start_line, uuid); the CLI (knot search) and the MCP tool share the same core (run_search_hybrid_context).

Live-index verification of the reported recall regression set runs via the opt-in harness tests/run_rank_recall_live.sh (requires indexed repositories; skipped otherwise).

Relationship summary per result (same edges as find_callers): each result is annotated from the graph edges of its own entity (looked up by UUID, never by bare name), so the summary always agrees with find_callers on that entity's fully qualified name:

• Called by: N — direct CALLS edges into the entity. Same-named methods in other classes or modules never contribute (a private computeValue in two classes keeps two separate caller sets).

• Called via dispatch: N — callers reaching the entity only through dynamic dispatch, i.e. the Dispatched calls group of find_callers (an interface method called only through its implementation shows Called via dispatch: 1, not phantom direct callers).

• Calls — the callees, qualified with their owning type or module (StandardAdjuster.computeValue, GraphDb::connect), deduplicated.

• Subclasses / Implementers / Type Usage — as before.

Tool 2: find_callers

Find who calls a specific function

Query: "Find callers of getCurrentTimeInSeconds"
Result: All code that invokes this function + file locations

Each caller entry, target group header, and resolved target carries its repository as (repo: <name>), so results remain attributable under multi-repo scopes (repo_name: "all" or a comma list). The raw JSON (--output json) mirrors this with repo_name (referencing entity) and target_repo_name (referenced entity) fields on every row, plus repo_name on each resolution.targets[] entry.

Advanced: Search by Signature

# Find by full signature (Java)
echo '{"method":"tools/call","params":{"name":"find_callers","arguments":{"entity_name":"registerUser(String"}}}' | knot-mcp

# Find by parameter type (Kotlin)
echo '{"method":"tools/call","params":{"name":"find_callers","arguments":{"entity_name":"findById(Int"}}}' | knot-mcp

# Find by type annotation (TypeScript)
echo '{"method":"tools/call","params":{"name":"find_callers","arguments":{"entity_name":"(EventData"}}}' | knot-mcp

# Find by C# interface method (surfaces implementations + call sites)
echo '{"method":"tools/call","params":{"name":"find_callers","arguments":{"entity_name":"FindByIdAsync"}}}' | knot-mcp

Use Cases:

• Dead Code Detection: Zero callers = unused code

• Impact Analysis: "What breaks if I modify this?"

• Refactoring Safety: Find all references before removing

• Override Discovery (JVM + C#): For Java/Kotlin/Groovy/C# methods, results include an Overridden by group (implementations/overrides in subtypes) and an Overrides group (the supertype methods a method implements/overrides). These are backed by real OVERRIDES edges built at index time and resolved transitively at query time, so querying an interface/superclass method surfaces every implementation, and querying an implementation surfaces the declaration it overrides. Overloads are told apart: an override links only to the same-named declaration whose arity and parameter types match (update(List, boolean) never claims to override update(List)); type variables match concrete types (put(T) ← put(Setting)), the most specific overload wins when several fit, and Groovy default parameters count for every arity they generate. Methods without a readable signature fall back to name-only matching.

• Dynamic Dispatch (JVM + C#): a Dispatched calls group lists the callers whose CALLS edge is bound to a method related to the target through OVERRIDES — calls on the interface when you query the implementation, and calls on a concrete implementation when you query the interface. Each row names the method the call is statically bound to (### Target: / the table's Target column). Both legs of the traversal are directed, so callers of a sibling implementation never leak in.

Truncation & completeness: the queried name is first resolved to concrete targets, capped at 25 by default (hard ceiling 500). When more targets match, the response states it explicitly and quantified:

> **Truncated** — 112 targets matched; showing the first 25 by FQN.

> **Counts below are partial** — they cover only the 25 of 112 targets shown.
> Re-run with a fully qualified name, or raise `max_targets`, for the complete set.

The relationship buckets (Calls, Extends, Implements, References) are complete for the resolved targets — there is no per-bucket cap — so the partial counts caveat tells you exactly what to do next: pass a fully qualified name to disambiguate homonyms, or raise max_targets (MCP parameter, default 25, maximum 500; CLI --max-targets) to opt into the full impact set.

The same shown-vs-total contract applies to search_hybrid_context: each relationship summary is one line, and when it lists fewer samples than the reported count it ends with … +N more instead of implying the sample is the complete set:

**Called by:** 21 location(s), 4 in tests: handle (same file), checkout in orders.ts, … +15 more

Search answers are kept compact for LLM agents (issue #50): a sample in the result's own file reads name (same file), other samples show the file name only (the full path is one find_callers away); callers and usages in test code stay in the count but are reported as N in tests and listed only with include_tests: true (CLI --include-tests); Calls: lists are capped at 8 items plus +N more; signatures print on one line and empty ones (()) are omitted; documentation keeps its first paragraph without @param/@return tags; and a result declared in a file already shown says File: same as \`. Pass detail: "brief"(CLI--detail brief) for one line per result — name (kind) — file:line — called by N, calls M— then expand the hit you need withfind_callers, explore_fileor afullsearch. On the reference sample (8 queries over 4 repositories)fullanswers are 28% shorter than in v1.12 andbrief` answers 82% shorter.

Tool 3: explore_file

Understand file structure

Query: "What's in BrowserService.ts?"
Result: All classes, methods, constants, and functions with signatures and docs, plus compact markup summaries

Tool 4: list_repositories

Discover indexed codebases

Query: "What codebases are indexed?"
Result: Markdown table of all indexed repos with entity/file counts, language, and build system

Tool 4b: list_files

Enumerate a repository's files

Query: path = "src/hooks", repo = "my-app"
Result: Ordered table of the files under src/hooks with their entity counts

search_hybrid_context shares the same path parameter to scope results to that subtree.

Tool 4c: list_endpoints

Catalogue the HTTP endpoints a service serves (Java/Kotlin: JAX-RS, Spring MVC)

Query: method = "GET", path = "/api/owners/42", repo = "my-service"
Result: | GET | /api/owners/{ownerId} | com.shop.web.OwnerController.showOwner | src/.../OwnerController.java:41 | my-service |

Tool 5: list_repo_dependencies

Traverse cross-repository dependency graphs

Query: "What repositories depend on auth-lib?"
Result: Repositories declaring build dependencies (pom.xml, build.gradle, Cargo.toml, package.json, NuGet)

Indexing either side of a relationship creates the DEPENDS_ON edge: index a library after its consumers and they are linked retroactively (reverse sweep); an empty lookup is explained explicitly with a three-way classification — declared-but-unindexed dependencies are listed by name (uncapped), but a dependency that resolves to an indexed repository without an edge yet is reported as a stale graph with a re-index hint instead of being falsely called "not indexed"; the reverse direction names consumers that declare the repo without an edge — never a bare "No dependencies found."

🔗 MCP Client Configuration

Supported Clients

knot works with any MCP-compatible AI client:

• ✅ Claude Desktop (Anthropic)

• ✅ Gemini CLI (Google)

• ✅ ChatGPT CLI / GPT (OpenAI)

• ✅ Cursor (AI IDE)

• ✅ Any standard MCP client

Configuration Examples

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "knot": {
      "command": "/absolute/path/to/knot/target/release/knot-mcp",
      "env": {
        "KNOT_REPO_PATH": "/path/to/indexed/repo",
        "KNOT_QDRANT_URL": "http://localhost:6334",
        "KNOT_NEO4J_URI": "bolt://localhost:7687",
        "KNOT_NEO4J_USER": "neo4j",
        "KNOT_NEO4J_PASSWORD": "your-password"
      }
    }
  }
}

Gemini CLI

{
  "mcpServers": {
    "knot": {
      "command": "/absolute/path/to/knot/target/release/knot-mcp",
      "env": {
        "KNOT_REPO_PATH": "/path/to/indexed/repo",
        "KNOT_QDRANT_URL": "http://localhost:6334",
        "KNOT_NEO4J_URI": "bolt://localhost:7687",
        "KNOT_NEO4J_USER": "neo4j",
        "KNOT_NEO4J_PASSWORD": "your-password"
      }
    }
  }
}

ChatGPT / GPT CLI

Similar JSON configuration in your client's MCP configuration file.

⚙️ Configuration Reference

All options can be set via CLI flags, environment variables, or a ~/.config/knot/.env file. Priority (highest to lowest): CLI flags > environment variables > .env file.

🤖 Embedding Model Selection

knot supports exactly two embedding models, selected via KNOT_EMBED_MODEL or --embed-model. The default is chosen for backward compatibility: a v1.10.0 user upgrading finds zero re-index and zero configuration change — same model, same collection, same dimension.

The supported set is closed: the whole model universe for knot is this table (src/pipeline/embed/model.rs), and adding a future model must be a one-row change there. The four models available in v1.10.0 only (BGESmallENV15, MultilingualE5Small, JinaEmbeddingsV2BaseCode, NomicEmbedTextV15) were removed on purpose — setting one aborts startup with an error listing the two accepted names. The vector dimension is derived from the model: KNOT_EMBED_DIM / --embed-dim are hidden and deprecated (a value that agrees emits a deprecation warning; one that contradicts is a hard error because it means you believe a different model is active).

An explicit collection (KNOT_QDRANT_COLLECTION set by CLI, env or .env) always wins; when it is unset, the model's derived collection applies — BGE users could otherwise collide with a fixed-size knot_entities created at 384.

search_hybrid_context re-ranks independently of the model's cosine scale: each candidate pool is normalized before the boosts are applied, so switching model does not require re-tuning the ranker.

Startup guards (model markers)

Every index run records the producing model on the repository's :Repository node. On startup, knot and knot-mcp verify that the configured model matches the collection's real vector dimension and every marked repository:

• Dimension mismatch with the collection — aborts with an actionable message (a collection's vector size is fixed at creation).

• Every marked repository on another model — aborts, naming both models.

• Some repositories on another model — warns and names the repositories that will not appear in semantic search. Scope-limited searches (search_hybrid_context with repo) specifically return a note instead of a silent empty result.

• Legacy index without markers — the dimension infers the model (384 ⇒ AllMiniLML6V2, 768 ⇒ BGEBaseENV15); a consistent legacy index is never fail-closed and self-heals (writes the marker) on the next index run.

Runbook: opting into BGE-base

# 1. Choose the model (consumers read this too):
export KNOT_EMBED_MODEL=BGEBaseENV15

# 2. Every repository needs a clean re-index; the alternative collection
#    knot_entities_bge768 is derived automatically for every run afterwards:
KNOT_REPO_PATH=/path/to/repo KNOT_REPO_NAME=my-repo knot-indexer --clean

# 3. Restart every consumer (knot-mcp servers, knot CLI users).

Cost and recall measurements for both models live in docs/measurements/ (model_cost_1_11.md, model_matrix_1_11.md).

🎨 Custom Tree-sitter Queries

The built-in extraction queries (queries/java.scm, queries/typescript.scm, queries/csharp.scm) can be overridden without recompiling:

KNOT_CUSTOM_QUERIES_PATH=/path/to/my/queries ./target/release/knot-indexer

Place java.scm, typescript.scm, and/or csharp.scm in your custom directory. Missing files fall back to built-in defaults.

🔐 Corporate SSL / CA Certificates

In restricted corporate environments with SSL-inspecting proxies, you may need to provide a custom CA certificate bundle so that knot can download the embedding model from HuggingFace.

Via environment variable:

export KNOT_CUSTOM_CA_CERTS=/etc/ssl/certs/corporate-bundle.pem
./target/release/knot-indexer --repo-path /path/to/repo --neo4j-password secret

Via CLI flag:

./target/release/knot-indexer \
  --custom-ca-certs /etc/ssl/certs/corporate-bundle.pem \
  --repo-path /path/to/repo \
  --neo4j-password secret

Via .env file:

echo "KNOT_CUSTOM_CA_CERTS=/etc/ssl/certs/corporate-bundle.pem" >> ~/.config/knot/.env
./target/release/knot-indexer

This works for all three binaries: knot-indexer, knot-mcp, and knot.

🔄 Workflow Example

Step 1: Index a Java project

./target/release/knot-indexer --repo-path /home/user/my-java-app --neo4j-password secret

Step 2: Query via CLI (Instant search)

./target/release/knot search "authentication logic"
./target/release/knot callers "UserService.login"

Step 3: Start MCP server (For AI Agents)

./target/release/knot-mcp

Step 4: Use with Claude Desktop

• Claude will list the read-only tool surface in its Tools menu

• Ask: "Search for all authentication logic"

• Ask: "Find who calls the login method"

• Ask: "Explore the structure of UserService.java"

🤖 Auto-Configuring AI Agents

knot includes a universal .prompt file in its root directory that automatically configures modern AI coding agents (Cursor, Cline, opencode, Claude, etc.) to use the knot-mcp tools correctly.

The directive explicitly instructs AI agents to prioritize:

• search_hybrid_context — for semantic code discovery (instead of grep)

• find_callers — for reverse dependency analysis (instead of finding references manually)

• explore_file — for file structure inspection (instead of reading line-by-line)

This ensures that when you ask an AI agent to analyze, refactor, or understand your code, it leverages the full power of the vector and graph databases rather than falling back to context-blind regex searches. The .prompt file is universal and tool-agnostic, working with any LLM client that reads codebase directives.

🤝 Contributing

Contributions are welcome! Please ensure:

• All code passes cargo clippy and cargo fmt

• No new unsafe code (unsafe_code = "deny" at crate level; one audited exception in src/utils/mod.rs for corporate proxy CA bundle injection, documented via #[expect(unsafe_code, reason = "…")])

• Changes are compatible with Rust 2024 edition

• All new functionality includes unit tests

• Performance regressions are validated with the benchmark framework before submitting PRs

Development & Code Quality

make check                                  # Run all local quality gates (fmt, clippy, test, dupes)

# Or run gates individually:
cargo clippy --all-targets -- -D warnings  # Must pass
cargo fmt -- --check                        # Must pass
cargo test                                  # Run all unit tests
cargo dupes check                           # Code duplication check

Performance Benchmarking

The project includes a three-level benchmarking framework to validate optimizations and detect regressions:

Level 1 — Unit Benchmarks (Criterion):

cargo bench --bench pipeline_bench          # Parse + prepare throughput per language
cargo bench --bench graph_upsert_bench     # Neo4j UNWIND batching speedup (needs Neo4j)
cargo bench --bench channel_backpressure_bench  # Bounded channel overhead

Level 2 — E2E Integration Benchmarks:

# Full pipeline metrics with memory and per-stage timing
./tests/benchmark_e2e.sh --focus rust_e2e --output-dir /tmp/perf_results

# Compare against baseline (fails CI if tolerance exceeded)
scripts/compare_perf_metrics.sh /tmp/perf_results .perf_metrics/baseline.json

Level 3 — Token Efficiency Benchmark:

# Measures knot tool output vs grep + file reads on indexed repositories
python3 scripts/token_savings_benchmark.py \
  --config scripts/token_savings_tasks.json \
  --save-json .perf_metrics/token_savings.json

Unlike levels 1 and 2 (which measure indexing throughput), this one measures the consumer side: how many LLM tokens an agent spends to answer a question with knot versus by reading source files. Requires rg, a built knot binary, the repositories in the config already indexed, and optionally tiktoken for exact token counts. See Token Efficiency for the published results.

Baseline files: .perf_metrics/baseline.json stores the last known good metrics (committed, updated on main/master merges). Tolerance thresholds in .perf_metrics/threshold_tolerances.json control regression gates (±5% time, ±10% memory by default).

CI Integration: The test-performance job in .github/workflows/ci.yml runs after all E2E correctness tests pass, comparing results against baseline and fails the build on regression.

📜 License

This project is licensed under the MIT License. See LICENSE for details.

🚀 Roadmap

For the full release history see CHANGELOG.md.

Upcoming

Long-Term Vision

• Go support

• IDE plugins (VS Code, IntelliJ, Vim)

• Language Server Protocol (LSP) integration

• Automated Code Review tool (MCP-based)

• Ruby support

💬 Questions?

For issues, feature requests, or discussions, please open a GitHub issue.