From 5bfb5bc8e3ebc82f4182a8c917ce75e354ef4275 Mon Sep 17 00:00:00 2001 From: Lightning Pixel Date: Sun, 9 Aug 2026 18:19:23 +0200 Subject: [PATCH] Rewrite the README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Shorter and easier to scan: 357 lines to 218. A centred header with jump links, the example first, then install, commands, languages, numbers. The example is now real output rather than a curated one — `orvix map` at its default budget prints that parser.ts block, and the who-calls lines are verbatim. The old header claimed line numbers the code no longer had. `orvix show parse` was offered as proof that bare names work; it actually matches three symbols in this repository. Replaced with one that resolves, and the ambiguous case is described instead of hidden. Every figure re-measured in one sitting rather than carried over: 405 symbols, 1 201 edges, ~2,032 and ~35,199 for the two measure rows, 55.6/27.2/82.9 ms for latency, the scale table, 395 tests. The latency numbers are higher than the previous README's because the machine was busier, which is what the caveat beside them already said would happen. Dropped: the per-command prose that repeated the table, and the longer retellings of the hook design. Kept: what the call graph cannot see, how ids behave, and the paragraph explaining that these are per-operation numbers — that one is the reason to trust the rest. Co-Authored-By: Claude Opus 5 --- README.md | 407 ++++++++++++++++++------------------------------------ 1 file changed, 134 insertions(+), 273 deletions(-) diff --git a/README.md b/README.md index 0ecbb30..aa36398 100644 --- a/README.md +++ b/README.md @@ -1,119 +1,36 @@ +
+ # orvix -**A semantic code map for AI agents.** Index a codebase once, address every symbol by a short -code, and read only the function you actually need. +**A semantic code map for AI agents.** + +Index a codebase once, address every symbol by a short code, +and read only the function you actually need. + +[Install](#install) · [Commands](#commands) · [Languages](#languages) · [Claude Code](#claude-code) · [Numbers](#numbers) + +
+ +--- Coding agents spend most of their context rediscovering structure: `ls`, then `grep`, then reading an eight-hundred-line file to use twenty lines of it. Orvix replaces that with an index you query directly. -```bash -$ orvix map --budget 800 -src/core/resolve.ts - om2v *interface CallGraph :20 - mgp4 *function buildCallGraph(index: OrvixIndex): CallGraph :62 ←5 - … 12 more +```console +$ orvix map src/core/parser.ts + c6sx function initRuntime(): Promise :10 ←1 fv6o *async function loadLanguage(def: LanguageDef): Promise :19 ←2 l00y *async function parse(source: string, def: LanguageDef): Promise :36 ←2 $ orvix show l00y # the exact source of that one function, nothing else -$ orvix who-calls l00y # every symbol that calls parse -``` - -`*` marks an exported symbol, `:62` is the line, `←5` is the number of callers. - -## Results - -Every number below comes from a command in this repository. Measured on Orvix's own source — -75 files, 402 symbols, 1 196 call edges, 0 call sites too ambiguous to link — on Windows with -Node 24. Re-run them; they will differ on your machine and your code. - -### Reading one symbol instead of one file — `npm run measure` - -| Task | Reading files | With orvix | Saved | -|---|---|---|---| -| Target one function (`resolveModule`) to edit it | ~2,000 | ~235 | **88%** | -| Take in the whole project's shape | ~35,309 | ~1,994 | **94%** | - -### What the hooks actually replace — `npm run benchmark` - -Recorded tool results replayed through the real hook scripts: - -``` -fixture=read-config-untouched.json compressed=false before=44 after=44 preserved=true -fixture=read-large-module.json compressed=true before=2437 after=702 preserved=true - -delta tokens_saved=1735 ratio=0.699 success_delta=0 +$ orvix who-calls l00y # every symbol that reaches it +rko9 *src/core/extract.ts:113 async function extractFile( source: string, def: LanguageDef, ): Promise ←4 +hau4 test/parser.test.ts:5 function definitionOf(path: string, source: string) ``` -**69.9% saved, nothing lost.** `preserved` is the number that matters: each fixture names what the -task needed from that output, and the run fails if a compression drops it. Tokens saved on its own -is meaningless — returning an empty string would score perfectly. The config fixture is there to -fail if Orvix ever touches a file it has no business compressing. - -This runs in CI on every commit. - -### Query latency — `npm run bench` - -``` -node floor 34.7 ms ← nothing here can go below this -orvix overhead 16.7 ms -query total 51.4 ms -``` - -Median of five runs; it moves by a few ms with machine load, and by rather more on a busy one. - -**Node's own startup is two thirds of it.** That ceiling is why the query path carries no CLI -framework and never loads a tree-sitter grammar — a hook runs on every tool call, and 17 ms is the -only part Orvix controls. A test asserts the query bundle imports neither `commander` nor -`web-tree-sitter`, following the whole static module graph rather than just the entry file. The -reindexer is reachable, but only through a dynamic import, so a query on an unchanged project -never loads a grammar. - -### Growing projects — `npm run scale` - -Generated projects with cross-file imports and calls, indexed and queried end to end: - -| files | `orvix index` | `orvix show` | hot files | cold file | -|---|---|---|---|---| -| 100 | 285 ms | 54 ms | 241 KB | 265 KB | -| 500 | 746 ms | 59 ms | 1 220 KB | 1 336 KB | -| 2 000 | 2 547 ms | 85 ms | 4 937 KB | 5 380 KB | - -Indexing grows with the project, as it must. A query grows far more slowly: 20× the files costs -under 2× the query, because a lookup reads only the symbol table and never the call sites, and the -call graph and PageRank were computed once at index time rather than rebuilt per query. On this -repository the files a query reads are **31%** of the cache. - -### Correctness — `npm test` - -394 tests. The load-bearing one asserts that after a run of randomised edits, the incrementally -updated index is **byte-identical** to indexing the project from scratch. It has caught four real -bugs that unit tests missed. - ---- - -Four things to read fairly. - -**These are per-operation, not per-session.** They compare one file read against one lookup. A -session's context is also its system prompt, its history, the model's own output and its diffs, -none of which Orvix touches. If searches and reads are a third of a session's tokens, cutting 70% -of those saves around 20% overall — a real number, but not this one. `orvix gain` reports measured -deltas for the calls it actually compressed, which has the same narrow denominator. - -Counts are **estimated at 3.5 characters per token**, not produced by a tokeniser — the same -estimate is applied to both sides, so the ratio holds even though the absolute numbers are rough. - -They are a snapshot of this repository's source and drift as it grows; `npm run measure` -regenerates the table. - -And the first row assumes the agent already knows which symbol it wants — if it has to find its -bearings first, it pays for the second row once, then the first row for every symbol after that. - -The honest case for Orvix is not the percentage. It is that `who-calls` answers a question `grep` -structurally cannot: which symbols actually reach this one, resolved through imports, with -methods distinguished from functions and no edge drawn when the answer is ambiguous. +`*` marks an exported symbol, `:36` is the line, `←2` is the number of callers. ## Install @@ -123,235 +40,179 @@ cd your-project orvix init ``` -`orvix init` asks once which coding agents you use, writes the instructions they read into -`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`, adds `.orvix/` to your `.gitignore`, and builds the -index. Your answer is remembered in `~/.orvix/config.json`, so later projects only need -`orvix init` with no questions. +`orvix init` asks once which agents you use, writes their instruction file, adds `.orvix/` to +`.gitignore`, and builds the index. The answer is remembered, so later projects need no answer. -Node 20 or later. Pure JavaScript and WebAssembly — no native build step, nothing to compile. +Node 20 or later. Pure JavaScript and WebAssembly — nothing to compile. ## Commands | Command | What it does | |---|---| -| `orvix init [path]` | Set a project up for agents; `--agent claude codex cursor gemini` skips the prompt | -| `orvix index [path]` | Build or refresh the cache; prints what changed | -| `orvix map [path]` | The symbol tree, ranked, fitted to `--budget ` (default 2000) | +| `orvix init [path]` | Set a project up for agents | +| `orvix index [path]` | Build or refresh the cache | +| `orvix map [path]` | The symbol tree, ranked, fitted to `--budget` | | `orvix show ` | The exact source of one symbol | | `orvix find ` | Search symbols by name or signature | | `orvix who-calls ` | Everything that calls this symbol | | `orvix calls ` | Everything this symbol calls | -| `orvix gain [path]` | Tokens the hooks have saved, per session and in total | +| `orvix gain [path]` | Tokens the hooks have saved | -Every command takes `--json` for machine-readable output. `show`, `find`, `who-calls` and `calls` -take `-p ` to point at another project. +Every command takes `--json`. Queries answer from the prebuilt index and never parse on their +own — that is what keeps them cheap enough to sit behind a hook. -Queries answer from the prebuilt index and never parse on their own — that is what keeps them -cheap enough to sit behind a hook. Run `orvix index` after changing files. Under Claude Code this -is automatic; see below. +You never have to hold onto an id: `orvix show loadLanguage`, `orvix show Service.validate` and +`orvix show fv6o` all work. When a bare name matches several symbols, they are listed with their +ids so you can pick one. -You never have to hold onto an id. `orvix show validate`, `orvix show Service.validate` and -`orvix show a4f2` all work. +### Ids are stable -### Ids +An id derives from `file :: qualified name :: kind`, never from the file's contents. **Editing a +function's body does not change its id** — one an agent was given three turns ago still points at +the right symbol. Renaming or moving it does. -An id is derived from `file :: qualified name :: kind`, and deliberately not from the symbol's -contents. **Editing a function's body does not change its id** — an id an agent was given three -turns ago still points at the right symbol. Renaming or moving the symbol does change it. +Ids show four characters wide and resolve by prefix, like git hashes. -Ids are shown four characters wide and resolved by prefix, like git hashes. If a project grows -enough to need five, ids quoted earlier keep resolving. +## Claude Code -## Claude Code hooks - -Writing instructions into `CLAUDE.md` and hoping they are honoured only goes so far. For Claude -Code, `orvix init` also installs three hook scripts into `.claude/hooks/` and registers them in -`.claude/settings.json`, merging with whatever is already there rather than overwriting it. +Writing instructions into `CLAUDE.md` and hoping they are honoured only goes so far. `orvix init` +also installs three hooks and registers them, merging with whatever is already in +`.claude/settings.json`. | Hook | When | What it does | |---|---|---| -| `orvix-dirty.mjs` | after `Edit`, `Write`, `MultiEdit` | Marks the file dirty. Runs async, so it costs the turn nothing. | -| `orvix-compress.mjs` | after `Read`, `Grep`, `Bash` | Replaces the result with its symbol map before the model sees it. | -| `orvix-reconcile.mjs` | when the turn ends | Full reindex in the background, as a safety net. | +| `orvix-dirty` | after `Edit`, `Write` | Marks the file dirty. Async, so it costs the turn nothing. | +| `orvix-compress` | after `Read`, `Grep`, `Bash` | Replaces the result with its symbol map before the model sees it. | +| `orvix-reconcile` | when the turn ends | Full reindex in the background, as a safety net. | -Nothing here asks the model to cooperate. It never runs an `orvix` command — the compression hook -reads `.orvix/symbols.json` directly. The scripts are plain `.mjs` with no imports beyond +Nothing here asks the model to cooperate — the compression hook reads `.orvix/symbols.json` +directly and never runs an `orvix` command. The scripts are plain `.mjs` with no imports beyond `node:*`, so they port to any agent that can run a script and speak JSON on stdin. -**What hooks cannot do is create initiative.** A hook only ever reacts to a tool call the model -already decided to make, so `orvix who-calls` before a signature change still depends on the -instruction block below. Compression is mechanical; navigation is a recommendation. - -### Turning it off - -Both compressions are on by default. To change that without touching the agent's configuration: +Both compressions are on by default. To turn one off without touching your agent's config: -```json +```jsonc // .orvix/config.json { "compressRead": false, "compressSearch": true } ``` -`compressRead` is the one to reach for first. Replacing a whole-file read with a symbol map is -where the savings are largest and where a task is most likely to lose something it needed — a -second read of the same file in a session always returns the real text, but if the trade does not -suit your work, turn it off here. - -## For agents - -`orvix init` writes this for you, between `` and `` -markers so re-running it updates the block in place instead of stacking copies. Anything else in -the file is left untouched. Reproduced here so you know what lands in your repository: - -```markdown -## Codebase navigation (orvix) - -This project is indexed by orvix. Prefer it over `grep` and over reading whole files. - -- `orvix map --budget 2000` — the project's symbols, most important first -- `orvix show ` — one symbol's exact source. Do not read the whole file. -- `orvix find ` — locate a symbol when you don't have its id -- `orvix who-calls ` — every caller. Run this before changing a signature. -- `orvix calls ` — what a symbol depends on - -Ids are short and stable across edits: reuse an id you were given earlier rather than -re-running `map`. Names work too — `orvix show validate`, `orvix show Service.validate`. - -Queries answer from a prebuilt index and never reparse on their own, so run -`orvix index` after you change files. (Under Claude Code this is automatic: a hook marks -edited files and the next query picks them up.) - -Do not use orvix for files outside TypeScript, TSX, JavaScript, Python, Go and Rust — -read those directly. Do not use it for anything that is not a symbol: string literals, -configuration keys, comments, TODOs. Use `grep` for those. -``` - -The last paragraph matters as much as the rest: without it an agent runs `orvix show` on a JSON -file, gets nothing, and concludes the tool is broken instead of just reading the file. +**What hooks cannot do is create initiative.** A hook only reacts to a tool call the model already +decided to make, so `orvix who-calls` before a signature change still depends on the instruction +block. Compression is mechanical; navigation is a recommendation. ## Languages TypeScript · TSX · JavaScript · Python · Go · Rust · Java · C# · C++ · C -`map`, `show` and `find` work the same in all of them. **The call graph does not.** Each of these -was measured by indexing a real project: +`map`, `show` and `find` behave the same in all of them. **The call graph does not**, and it is +worth knowing before you lean on it. Each row is a real project, indexed end to end: | Project | Language | Files | Calls resolved | Refused as ambiguous | |---|---|---|---|---| | curl/curl | C | 1 068 | **42%** | **2%** | -| JamesNK/Newtonsoft.Json | C# | 945 | 27% | **59%** | +| JamesNK/Newtonsoft.Json | C# | 945 | 27% | 59% | | fmtlib/fmt | C++ | 77 | 27% | 30% | | google/gson | Java | 264 | 25% | 33% | The rest of each row is calls into the standard library, which resolve to nothing by design. -**The split is not about the language being hard, it is about where calls go.** C has free -functions with project-unique names, which is exactly what a syntactic resolver can follow — it -gives the densest graph of any language here. C#, C++ and Java send most calls through a receiver -on a typed object, and `x.Get(…)` cannot be attributed without knowing the type of `x`. Refusing -is the rule working, not a defect; a wrong edge would be worse. Overloads are not the cause — on -gson only 5% of ambiguous sites were overloads of one method. - -So: `who-calls` and `calls` are strong in C, Go, Rust, TypeScript and Python, and partial in C#, -C++ and Java, where ranking is also flatter because it reads the call graph. - -Adding one means an entry in `src/core/languages.ts`, its grammar in -`scripts/copy-grammars.mjs`, a tag query in `queries/.scm`, and its scope and visibility -rules in `src/core/extract.ts`. `AGENTS.md` has the full list. - -## What the call graph does and does not know - -Resolution is **syntactic**. Tree-sitter reports names and imports, not types, so Orvix matches a -call to a definition in this order: same file, then through an import, then a project-wide unique -exported name. - -It is deliberately conservative: - -- A call through a receiver (`obj.run()`) can only reach a **method**; a bare call (`run()`) can - only reach a non-method. Without this, every `JSON.parse(…)` in a project looks like a call to - your own `parse` function. -- When several definitions remain plausible, **no edge is drawn**. `orvix index` reports the - count of such call sites. Guessing would be worse than admitting the gap. -- A call never resolves **across languages**. TypeScript, TSX and JavaScript count as one; the - rest stand alone. Otherwise a project's only symbol named `filter` — a Python method, say — - collects every `xs.filter(…)` in its TypeScript half. -- Calls into third-party libraries resolve to nothing, by design. - -**Calls dispatched through a string are invisible.** An Electron IPC channel, an event name, a -route table, a DI container: the caller names a string and the framework finds the target, so -there is no call for tree-sitter to see. `who-calls` on a function behind such a boundary returns -only the callers on its own side of it — a real answer, but not the whole one. This is worth -knowing before you trust `who-calls` to enumerate the blast radius of a signature change in an -app built around a message bus. - -Known limits: type references are not call edges, so an interface shows no callers — ranking -compensates by biasing toward exported symbols. Import following is implemented for ECMAScript -module paths; Python, Go and Rust rely on same-file scope and project-unique names. Functions -inside a Rust `impl` block are reported without a container. +The split is not about the language being hard — it is about where calls go. C has free functions +with project-unique names, exactly what a syntactic resolver can follow, and it gives the densest +graph here. C#, C++ and Java send most calls through a receiver on a typed object, and `x.Get(…)` +cannot be attributed without knowing the type of `x`. Refusing to guess is the rule working: a +wrong edge is worse than a missing one. -## What gets indexed +## Numbers -Orvix honours `.gitignore` (including nested ones, with `!` negations) and `.orvixignore`, which -takes precedence. `node_modules`, `.git` and `.orvix` are never walked. +Every figure comes from a command in this repository, measured on Orvix's own source — 75 files, +405 symbols, 1 201 call edges, 0 call sites too ambiguous to link — on Windows with Node 24. +Re-run them; they will differ on your machine. -Because plenty of real projects have no `.gitignore` at all, a default set is applied at the -root: `site-packages/`, `bower_components/`, virtualenvs, `__pycache__/`, `dist/`, `build/`, -`target/`, `vendor/`, `coverage/`, framework caches, and minified bundles. Any of them can be put -back with a negation in `.orvixignore`: +**Reading one symbol instead of one file** — `npm run measure` -``` -!dist/ -``` +| Task | Reading files | With orvix | Saved | +|---|---|---|---| +| Target one function to edit it | ~2,032 | ~235 | **88%** | +| Take in the whole project's shape | ~35,199 | ~1,994 | **94%** | -Indexing refuses to start above 25 000 files or 64 MB of source, and tells you to add a -`.orvixignore` — an unbounded walk over a virtualenv exhausts memory before producing a single -useful symbol. +**What the hooks actually replace** — `npm run benchmark` -## How it works +Recorded tool results replayed through the real hook scripts: **69.9% saved, nothing lost.** +`preserved` is the number that matters — each fixture names what the task needed from that +output, and the run fails if a compression drops it. Tokens saved alone is meaningless; returning +an empty string would score perfectly. This runs in CI on every commit. + +**Query latency** — `npm run bench` ``` -cold path discovery → parse (tree-sitter) → extract → resolve → rank -(indexing) ↓ - .orvix/symbols.json + graph.json - ↓ -hot path map / show / find / who-calls / calls / hooks -(queries) +node floor 55.6 ms ← nothing here can go below this +orvix overhead 27.2 ms +query total 82.9 ms ``` -The cache is split by who reads it. `facts.json` holds every call site and is opened only when -reindexing. `symbols.json` and `graph.json` are what a query reads, and between them they are -about 30% of the whole — call sites outnumber symbols roughly ten to one. The call graph and -PageRank are computed once at index time and stored, not rebuilt per query. +Node's own startup is two thirds of it. That ceiling is why the query path carries no CLI +framework and never loads a grammar — a hook runs on every tool call, and the overhead is the +only part Orvix controls. A test asserts the query bundle imports neither `commander` nor +`web-tree-sitter`, following the whole static module graph rather than just the entry file. + +**Growing projects** — `npm run scale` -That split is the difference between a lookup costing what the answer costs and costing what the -project costs. On a 8 000-file project, parsing the unsplit cache alone took 192 ms and the graph -rebuild walked 341 657 call sites — on every single query. +| files | `orvix index` | `orvix show` | +|---|---|---| +| 100 | 558 ms | 87 ms | +| 500 | 1 297 ms | 94 ms | +| 2 000 | 4 522 ms | 147 ms | -**Incremental updates.** The edit hook appends the file to `.orvix/dirty` and stops. The next -query reparses only those files, then re-resolves the files that could now resolve differently: -an inverted index maps each referenced name to the files mentioning it, so changing a symbol's -signature invalidates its callers, and *adding* an export fixes references that previously -resolved to nothing. Without that second direction the graph keeps edges to symbols that no -longer exist. +Indexing grows with the project, as it must. A query grows far more slowly — 20× the files costs +under 2× the query — because a lookup reads only the symbol table and never the call sites. -PageRank is deliberately not recomputed incrementally — it costs 2.1 s on a 8 000-file project -and only decides the order `map` prints in. `orvix index` and the background reconciliation -refresh it. +**Correctness** — `npm test` -A property test asserts that after a run of randomised edits the incremental result is -**byte-identical** to indexing the project from scratch. It has caught four real bugs. +395 tests. The load-bearing one asserts that after a run of randomised edits, the incrementally +updated index is **byte-identical** to indexing the project from scratch. -Ranking is PageRank over caller→callee edges, personalised toward exported symbols. `--budget` is -honoured by construction: candidate renderings are measured and the largest one that fits is -returned, so output is never cut off mid-line. +### Read these fairly -## Development +They are **per-operation, not per-session**. They compare one file read against one lookup. A +session's context is also its system prompt, its history and the model's own output, none of which +Orvix touches. If searches and reads are a third of a session, cutting 70% of those saves around +20% overall — a real number, but not this one. -```bash -npm install -npm run build # copies grammars, bundles the CLI -npm test -``` +Counts are **estimated at 3.5 characters per token**, not produced by a tokeniser. The same +estimate is applied to both sides, so the ratios hold even though the absolute figures are rough. + +The honest case for Orvix is not the percentage. It is that `who-calls` answers a question `grep` +structurally cannot: which symbols actually reach this one, resolved through imports, with methods +distinguished from functions and no edge drawn when the answer is ambiguous. + +## What the call graph does not know + +Resolution is **syntactic**. Tree-sitter reports names and imports, not types, so a call is +matched to a definition in this order: same file, then through an import, then a project-wide +unique exported name — never across a language family. + +- **Calls dispatched through a string are invisible.** An IPC channel, an event name, a route + table, a DI container: the caller names a string and the framework finds the target, so there is + no call to see. `who-calls` on a function behind such a boundary returns only the callers on its + own side of it. +- **Type references are not call edges**, so an interface reports no callers. Ranking compensates + by biasing toward exported symbols. +- Import following is implemented for ECMAScript module paths; the other languages rely on + same-file scope and project-unique names. + +## What gets indexed + +`.gitignore` is honoured, including nested ones and `!` negations, and `.orvixignore` takes +precedence. `node_modules`, `.git` and `.orvix` are never walked. Because plenty of real projects +have no `.gitignore`, a default set is applied at the root — virtualenvs, `dist/`, `build/`, +`target/`, `vendor/`, `coverage/`, minified bundles — any of which can be put back with a negation +in `.orvixignore`. + +## Contributing + +`AGENTS.md` is the guide: how to verify a change, the invariants that must not break silently, and +the six steps for adding a language. -## License +## Licence -MIT +MIT. See [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md) for the bundled tree-sitter grammars.