osnova

Deterministic repository context engine. Osnova maps a codebase into a symbol and edge graph using tree-sitter WASM, then serves it through a CLI and an MCP stdio server. No embeddings, no network, no telemetry.

• Languages v1: TypeScript, TSX, JavaScript, JSX, Python, Go, Rust, Java, C#. Every other file type gets a bare file card (path, hash, no symbols).

• Query surface: ask, findText, skeleton, callers, map, renderMapCard.

• Edge semantics v1: direct calls, imports and exports, name references. No type inference and no dynamic dispatch resolution; expect per-language precision limits.

• Determinism: incremental updates produce byte-identical artifacts to full rebuilds. All paths, symbols, and edges are sorted before serialization.

Install

npm install @getdomovoi/osnova

Node.js >= 22.13.0. The grammar WASMs ship in the package; there are no native builds.

Related MCP server: codeindex

CLI

osnova build <root>            # build and cache the index
osnova ask "<question>"        # keyword search with exact file:line hits
osnova grep "<pattern>"        # regex/literal search grouped by symbol
osnova skeleton <file>         # every definition's signature and span
osnova callers <symbol>        # direct or transitive callers/callees
osnova map                     # directory clusters, hubs, hotspots
osnova check <root>            # staleness gate for CI (exit 1 when stale)
osnova mcp --workspace <path>  # MCP stdio server

Query commands refresh the index first (hash diff plus incremental apply), so answers always describe current disk state, including uncommitted edits.

MCP server

osnova mcp --workspace /path/to/repo

Exposes five read-only tools: osnova_ask, osnova_find_text, osnova_skeleton, osnova_callers, osnova_map. Arguments mirror the API. The server never writes outside the cache directory and performs no network access.

Example client configuration:

{
  "mcpServers": {
    "osnova": {
      "command": "npx",
      "args": ["-y", "@getdomovoi/osnova", "mcp", "--workspace", "/path/to/repo"]
    }
  }
}

API

import { buildIndex, ask, renderMapCard } from "@getdomovoi/osnova";

const index = await buildIndex("/path/to/repo");
const hits = ask(index, "where do we validate tokens", { limit: 5 });
const card = await renderMapCard(index); // <= 16,384 code units

Exports: buildIndex, loadIndex, applyChanges, freshness, ask, findText, skeleton, callers, map, renderMapCard, index types, and the MCP stdio main (runMcpStdio).

Cache location: explicit cacheDir parameter, else OSNOVA_CACHE_DIR, else the platform default (macOS ~/Library/Caches/osnova/, Linux $XDG_CACHE_HOME/osnova/, Windows %LOCALAPPDATA%/osnova/cache/). One subdirectory per workspace, LRU-evicted across workspaces.

Scanning respects .gitignore plus an optional .osnovaignore file with the same syntax, skips dotfiles, binaries, and files above 1 MB.

Development

pnpm install
pnpm lint && pnpm typecheck && pnpm test && pnpm build && pnpm perf

The perf script enforces first-build and incremental-refresh budgets on a generated fixture repo. Tests include per-language extraction goldens, an incremental-equals-full property test over randomized edit sequences, CLI round-trips, and MCP handshake plus tool round-trips over an in-memory transport.

License

Apache-2.0