A deterministic code map for AI coding agents

Install with your agent

npm install -g @getdomovoi/osnova

osnova

01 / 0800:00.0

Osnova is a Slavic word.

оoсsнnоoвvаa

base, foundation
the warp: the threads a loom holds taut so the cloth can be woven on them

Osnova reads your repository

0 files

0 symbols

0 edges

osnova's own source at 0.11.0

with tree-sitter,

and builds a symbol and call graph.

Eleven of the calls refreshWorkspace makes in osnova 0.11.0, one weft per calling line.

Your agent asks where things are and who calls them,

and gets exact file and line back.

agentosnova 0.11.0, its own source

osnova_warp src/api.ts#refreshWorkspace

function src/api.ts#refreshWorkspace: 83 indexed edges

reach: d1 callers 83 in 14 files (3 dirs); d2 +16 in 2 files; unresolved same-name 10; tests 18

d1 calls src/cli/cli.ts#ensureIndex:81 [import-binding]

d1 calls src/cli/hook.ts#runHook:191,203,225,240 [import-binding]

d1 calls src/mcp/server.ts#createOsnovaMcpServer.refresh:301 [import-binding]

d1 calls test/cache-hardening.test.ts#<module>:137,138,143,151,158,166 [import-binding]

d1 calls refreshWorkspace scripts/perf.mjs:485,486,491 [import-target-unresolved]

Same commit, same answer.

build 1

text.bin35a0907989ddcb04

edges.jsonaa077378f5db9f52

warp outputcfeccec7a316834d

= = =

build 2

text.bin35a0907989ddcb04

edges.jsonaa077378f5db9f52

warp outputcfeccec7a316834d

Two fresh builds of osnova 0.11.0 on its own source. SHA-256, first 16 hex digits.

osnova

A deterministic code map for AI coding agents

$ npm install -g @getdomovoi/osnova

основа: a foundation, and the warp a weave is built on

Twenty languages
Ten tools over MCP and CLI
No telemetry, runs offline
Apache-2.0

Where it sits in one agent turn

Osnova answers twice. Before the edit, with the symbols, callers and tests the task touches. After it, with what the change reached.

prompt
The developer asks for a change in billing.
human
footing
The agent asks osnova for the symbols, callers and tests that touch the task.
osnova
edit
The agent edits with exact paths and line ranges instead of a guess.
agent
settle
Osnova re-indexes the diff and returns what the change reached.
osnova
review
The developer reads the impact list, not the whole diff.
human

Install with your agent

Paste one prompt into the agent you already use. It installs osnova, shows you the change to your agent config, and applies it only after you approve. You need Node.js 22.13 or newer.

Paste into Claude Code

Install osnova for Claude Code. Osnova is a deterministic code map that serves a symbol and call graph over MCP.

1. Check that `node --version` reports 22.13 or newer. If it does not, stop and tell me.
2. Run `npm install -g @getdomovoi/osnova`.
3. Run `osnova setup claude`. It prints the config diff and writes nothing. Show me the diff.
4. When I approve, run `osnova setup claude --apply`. It backs up every file it changes.
5. Run `osnova doctor` and tell me about any warning.
6. Tell me to restart Claude Code so the MCP server, hooks and skill load.

Or run it yourself

npm install -g @getdomovoi/osnova
osnova setup claude --apply

Adds the MCP entry, session, prompt and stop hooks, and the skill. Prefer a plugin with no global install? Type these in Claude Code:

/plugin marketplace add getdomovoi/osnova
/plugin install osnova@osnova

Remove it with osnova setup claude --uninstall --apply.

Paste into Codex

Install osnova for Codex. Osnova is a deterministic code map that serves a symbol and call graph over MCP.

1. Check that `node --version` reports 22.13 or newer. If it does not, stop and tell me.
2. Run `npm install -g @getdomovoi/osnova`.
3. Run `osnova setup agents --only codex`. It prints the config diff and writes nothing. Show me the diff.
4. When I approve, run `osnova setup agents --only codex --apply`. It backs up every file it changes.
5. Run `osnova doctor` and tell me about any warning.
6. Tell me to restart Codex, open `/hooks` and trust the three osnova hooks. Codex skips a hook it does not trust, without a message.

Or run it yourself

npm install -g @getdomovoi/osnova
osnova setup agents --only codex --apply

Adds the MCP entry, the session, prompt and stop hooks, and the shared skill. Then trust the hooks in /hooks.

Remove it with osnova setup agents --only codex --uninstall --apply.

Paste into Cursor

Install osnova for Cursor. Osnova is a deterministic code map that serves a symbol and call graph over MCP.

1. Check that `node --version` reports 22.13 or newer. If it does not, stop and tell me.
2. Run `npm install -g @getdomovoi/osnova`.
3. Run `osnova setup agents --only cursor`. It prints the config diff and writes nothing. Show me the diff.
4. When I approve, run `osnova setup agents --only cursor --apply`. It backs up every file it changes.
5. Run `osnova doctor` and tell me about any warning.
6. Tell me to restart Cursor so the MCP server and hooks load.

Or run it yourself

npm install -g @getdomovoi/osnova
osnova setup agents --only cursor --apply

Adds the MCP entry and a stop hook that sends what your change reached as a follow-up message.

Remove it with osnova setup agents --only cursor --uninstall --apply.

Paste into OpenCode

Install osnova for OpenCode. Osnova is a deterministic code map that serves a symbol and call graph over MCP.

1. Check that `node --version` reports 22.13 or newer. If it does not, stop and tell me.
2. Run `npm install -g @getdomovoi/osnova`.
3. Run `osnova setup agents --only opencode`. It prints the config diff and writes nothing. Show me the diff.
4. When I approve, run `osnova setup agents --only opencode --apply`. It backs up every file it changes.
5. Run `osnova doctor` and tell me about any warning.
6. Tell me to restart OpenCode so the MCP server and plugin load.

Or run it yourself

npm install -g @getdomovoi/osnova
osnova setup agents --only opencode --apply

Adds the MCP entry and a plugin that appends starting points to each message.

Remove it with osnova setup agents --only opencode --uninstall --apply.

Paste into Kilo

Install osnova for Kilo. Osnova is a deterministic code map that serves a symbol and call graph over MCP.

1. Check that `node --version` reports 22.13 or newer. If it does not, stop and tell me.
2. Run `npm install -g @getdomovoi/osnova`.
3. Run `osnova setup agents --only kilo`. It prints the config diff and writes nothing. Show me the diff.
4. When I approve, run `osnova setup agents --only kilo --apply`. It backs up every file it changes.
5. Run `osnova doctor` and tell me about any warning.
6. Tell me to restart Kilo so the MCP server and plugin load.

Or run it yourself

npm install -g @getdomovoi/osnova
osnova setup agents --only kilo --apply

Adds the MCP entry and the same plugin OpenCode uses.

Remove it with osnova setup agents --only kilo --uninstall --apply.

Paste into Pi

Install osnova for Pi. Osnova is a deterministic code map that serves a symbol and call graph over MCP.

1. Check that `node --version` reports 22.13 or newer. If it does not, stop and tell me.
2. Pi reaches MCP servers through the `pi-mcp-adapter` extension. If it is not installed, stop and tell me.
3. Run `npm install -g @getdomovoi/osnova`.
4. Run `osnova setup agents --only pi`. It prints the config diff and writes nothing. Show me the diff.
5. When I approve, run `osnova setup agents --only pi --apply`. It backs up every file it changes.
6. Run `osnova doctor` and tell me about any warning.
7. Tell me to restart Pi so the MCP server and extension load.

Or run it yourself

npm install -g @getdomovoi/osnova
osnova setup agents --only pi --apply

Adds the MCP entry for pi-mcp-adapter and an extension that adds starting points before each turn.

Remove it with osnova setup agents --only pi --uninstall --apply.

Paste into any of them

Install osnova for every coding agent on this machine. Osnova is a deterministic code map that serves a symbol and call graph over MCP.

1. Check that `node --version` reports 22.13 or newer. If it does not, stop and tell me.
2. Run `npm install -g @getdomovoi/osnova`.
3. Run `osnova setup claude` and `osnova setup agents`. They print the config diffs and write nothing. The agents family covers Codex, Cursor, OpenCode, Kilo and Pi, and skips any that is not installed. Show me both diffs.
4. When I approve, run `osnova setup claude --apply` and `osnova setup agents --apply`. They back up every file they change.
5. Run `osnova doctor` and tell me about any warning.
6. Tell me to restart each agent. If Codex is set up, tell me to open `/hooks` in Codex and trust the three osnova hooks.

Or run it yourself

npm install -g @getdomovoi/osnova
osnova setup claude --apply
osnova setup agents --apply

One global install serves every repository. Nothing is written inside your projects.

Remove it with osnova setup claude --uninstall --apply and osnova setup agents --uninstall --apply.

Paste into your agent

Add osnova to my MCP client. Osnova is a deterministic code map that serves a symbol and call graph over MCP. It runs through npx, so nothing is installed globally.

1. Check that `node --version` reports 22.13 or newer. If it does not, stop and tell me.
2. Find my MCP client's config file and tell me its path.
3. Add this server entry and keep every other key:
   { "mcpServers": { "osnova": { "command": "npx", "args": ["-y", "@getdomovoi/osnova", "mcp"] } } }
4. Show me the change before you save it.
5. Tell me to restart the client.

Or add it yourself

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

Works with any client that takes the common mcpServers shape. Pin a repository with --workspace /path/to/repo after mcp when the client does not start in the project root.

Ten tools, named for the ground under the code

Your agent calls them over MCP. You can type the same names on the command line: osnova warp and osnova_warp run the same query.

Find

ground: Keyword search. Ranked definitions with exact file and line.
thread: Text search. Regex or literal matches, grouped by the symbol they sit in.
outline: Signatures and line spans for one file.
groundwork: Repository map. Directory clusters, hubs and hotspots.

Trace

footing: Task context. Definitions, relationships and candidate tests around a question.
warp: Call graph. Callers and callees, direct or transitive, with the evidence for each edge.
tests: The test files that reach a symbol, or the symbols one test file reaches.

Check

settle: Change impact. The symbols a diff touches and everything indexed that depends on them.
plumb: Checks a claimed list of call sites. Which the index confirms, and which it left out.
unreferenced: Definitions with no indexed caller, with their leads. Candidates, never proof.

Measured, with the misses left in

Checked against a type checker

Every call site in two pinned open-source checkouts went to the language's own type checker. Each osnova edge counted as true when it named the declaration the checker found, and false when it did not.

Measured at 0.8.0. The scripts reproduce every count at 0.10.0.

click Python, 160 files

0 false edges in 2,883

Covers 90.4% of the call sites the checker resolves in the repository

zod TypeScript, 702 files

4 false edges in 21,276

Covers 76.9% of the call sites the checker resolves in the repository

Grep against the graph

The first regex a person types is wrong more often than it looks. Nine call-site sets in five languages were verified line by line. Each cell shows sites found, then precision and recall.

Target	Verified sites	Text search	osnova
`Context.invoke` click, depth 2	13	12 0.92 / 0.85	12 1.00 / 0.92
`getChildNodes` pyright, depth 2	28	5 0.80 / 0.14	28 1.00 / 1.00
`Command.Root` cobra, depth 1	30	30 1.00 / 1.00	30 1.00 / 1.00
`Command.PersistentFlags` cobra, depth 1	12	13 0.92 / 1.00	12 1.00 / 1.00
`Configurator.GetFormatter` humanizer, depth 1	18	19 0.74 / 0.78	18 1.00 / 1.00
`Searcher.line_terminator` ripgrep, depth 1	12	32 0.38 / 1.00	12 1.00 / 1.00
`LineTerminator.as_byte` ripgrep, depth 1	26	26 1.00 / 1.00	26 1.00 / 1.00
`JsonReader.beginObject` gson, depth 1	10	29 0.34 / 1.00	10 1.00 / 1.00
`TypeToken.getRawType` gson, depth 1	27	43 0.63 / 1.00	27 1.00 / 1.00

The graph never returned a site that was not a call of the target. The frozen records are in benchmarks/results.

What osnova does not do

No type inference. Edges come from syntax: calls, imports, name references, written heritage and framework routes. Resolution is heuristic, and every edge says how it was resolved.
No semantic search. ground ranks definitions by their words. It is fast and explainable, and it will not match a paraphrase.
No proof of safety. An empty caller list means the index found no caller, not that none exists.
No cost claims. Agent trials so far show the same correctness with and without the graph on small tasks.