Local-first semantic code search for coding agents
Your AI coding agent must find the right code before it can change it. Satori finds it: ask in plain English, and the agent gets the function that owns the behavior, who calls it, and what to read next. Free, open source, and it runs on your machine.
npx -y @satori-code/cli@latest install
src/auth/refresh.tssemantic + lexicalsrc/session/store.tssemanticsrc/http/middleware.tslexicalconfig/security.tsconfig keysrc/auth/refresh.ts:84-146
AI coding agents write code fast. Their weak step is finding where to make the change. In a large project they search for a word, open whole files, and often stop reading before they reach the part that matters. Satori is the search and map service that the agent calls before it edits.
Think of a smart new colleague on day one who does not yet know where anything is. Satori is the colleague who has read the whole project and says: “That lives here. These places use it. Read this first.”
Satori is not just semantic search. One Publication binds retrieval, ownership, structure, relationships, freshness, and exact source to the same repository generation, so an agent can move from a vague question to verifiable code without rebuilding context from scratch.
Behavior by meaning, BM25, exact paths, identifiers, configuration keys, and literal evidence.
find intent without losing literals
Parser-derived functions, methods, classes, file outlines, and bounded source ownership.
rank evidence around real owners
Qualified callers, callees, imports, and exports when the language backend can prove them.
advisory, conservative, fail-closed
Source checkpoints, runtime compatibility, policy, navigation readiness, and atomic replacement generations.
know which repo state answered
The agent does not need a perfect identifier up front. Satori narrows the search in stages and keeps each stage tied to repository evidence.
envconfig.KeepAlive(), its caller, and the exact source, while a grep-driven edit landed in the wrong place.
Indexing is shown sped up.
The public surface stays small. Behind it, Satori gives a generic MCP harness the code-intelligence stack it would otherwise have to rebuild.
14-65ms p50
Exact symbol lookup measured across five pinned repositories on the offline Potion + LanceDB + LateOn runtime.
Potion embeddings, BM25 search, LanceDB storage, and managed local retrieval need no model API key and make no Satori runtime network requests after installation.
LateOn reranks a bounded candidate set locally to put the owning code first. In our 36-task test it doubled first-hit accuracy, from 0.19 to 0.39. On 46 plain-English questions, the agent’s own alt_terms lifted owners in the top 10 from 16 to 34. Switch to Voyage with one command when you want the strongest ranking. See how ranking works.
Parser-backed symbols, structural evidence, exact spans, and qualified CALLS v0 navigation ship across nine production languages, plus Kotlin and PHP.
Exact symbols and bounded reads keep broad file dumps out of the prompt, so repository discovery spends context on the code that matters.
Search, symbols, structural evidence, and qualified calls activate together. Unsupported or ambiguous relationships fail closed.
When the right file comes back at rank seven, your agent reads six wrong files first. Satori ranks for the code that owns the behavior, then hands the agent the exact span to read.
alt_terms. Satori searches each one as a separate pass, including a definition lookup, and fuses the results with the original question.
0.19 to 0.39
Owner found first, with LateOn reranking. 36 tasks on 6 repositories.
16 to 34
Owners in the top 10 when the agent adds its own alt_terms. 46 plain-English questions. Median request 2.7 s to 2.9 s.
4 to 13
Named-symbol questions answered at rank 1 with definition fusion and LateOn, against no reranker. 19 questions on 4 repositories.
1.86 s to 1.22 s
LateOn rerank of 64 candidates with the adaptive session pool on an 8-core Ryzen 7 3800X. Scores are bit-identical.
Runs on your CPU. Code stays on the machine and needs no API key. 13 of 28 owners first, median search 2.40 s. Linux x64 and WSL2.
satori reranker use lateonVoyage AI by MongoDB
18 of 28 owners first with rerank-3-lite, median search 1.04 s. The command asks for your VOYAGEAI_API_KEY with hidden input, saves it to ~/.satori/.env, and makes one test call before it switches. Each account gets 200 million free tokens per model, about 8,000 searches or months of daily use, and you need no credit card to start. Queries and code excerpts go to Voyage.
satori reranker use voyage
satori reranker statusRetrieval order only. About 200 ms per search on React, with 36,233 chunks.
satori reranker use none
Measured on 28 plain-English questions over React, Polars, and FlatBuffers with the same index for every reranker. Restart your agent after a switch. If Voyage fails during a search, Satori returns retrieval order and reports RERANKER_FAILED. Use npx -y @satori-code/cli@latest in place of satori if the CLI is not installed globally.
Ask where a behavior lives, identify the owning symbol, inspect the file structure, then read the implementation instead of browsing the tree at random.
“What owns billing retries?”
Start from an error or behavior, then follow owner and relationship evidence toward the exact code.
Find the owner, nearby structure, bounded source, and supported call paths before changing a subsystem.
Flash and local models are cheap and quick, but they read less. A small model may edit a function after it reads only the first part, and it cannot afford to read the repository to find the right one. Satori does the discovery work: hybrid search, the model’s own alt_terms, and owner-aware reranking put the owner near the top, then the model reads one exact span and follows qualified call paths. With LateOn, the whole stack runs offline, so a fully local setup stays local.
“Where is the cleanup of useEffect?” → commitHookEffectListUnmount
Compatible local sessions attach to one managed runtime and current repository intelligence while keeping independent MCP sessions.
The questions worth asking before you install anything that reads your code.
AGENTS.md or hook files and never overwrites files it did not write.~/.satori/. Your agent does not download anything again on startup.satori uninstall removes client config and the shared skill. Add --purge to also delete the runtime, models, and indexes.Two commands to install, one sentence to your agent. It is in beta and runs on Linux only for now (x64 and WSL2), fully offline after installation, with no account and no API key.
npx -y @satori-code/cli@latest install
npx -y @satori-code/cli@latest doctorIndex /absolute/path/to/repo with Satori, then find where auth refresh is handled.npx -y @satori-code/cli@latest reranker use voyageCreate the repository Publication and wait until status is ready.
Ask for the behavior, owner, or source area the agent needs to understand.
Open the exact symbol, bounded source, outline, or qualified call path returned by Satori.
No model API key is required for the qualified managed offline path after installation. Connected Voyage and Milvus/Zilliz remain optional advanced runtimes.
If Satori helps, fails, or feels confusing in a real repository, I want the case. Send the language, repo size, MCP client, and what you were trying to understand.
ahmed@hamza.my.id