Local-first semantic code search for coding agents

Ask your codebase. Follow the evidence

Ask in plain English. Your agent gets the function that owns the behavior, who calls it, and what to read next. Free, open source, and local.

Try it on a repo
npx -y @satori-code/cli@latest install
Watch it find the right code in Ollama (34 s)
Ask

Where is auth refresh handled, what owns it, and what should I read first?

  1. Search
  2. Owner
  3. Trace
  4. Source
  • src/auth/refresh.tssemantic + lexical
  • src/session/store.tssemantic
  • src/http/middleware.tslexical
  • config/security.tsconfig key
Owner, rank 1
AuthRefreshCoordinator.refresh src/auth/refresh.ts:84-146
outlinecallersexact source
Freshness: current One coherent Publication
Works with
  • Codex
  • Claude Code
  • OpenCode
  • Antigravity
  • Any MCP client
No account. Beta: Linux x64 and WSL2.

Agents write fast. They search badly.

In a large project, an agent greps, opens whole files, and edits before it reaches the part that matters. Satori is the map it checks first.

Without Satori

  • A keyword search returns dozens of matches.
  • Whole files fill the agent’s context.
  • It edits after reading half a function.
  • It misses code that depends on the old behavior.

With Satori

  • One question in plain English.
  • The owning function, ranked near the top.
  • That function in full, with its file outline.
  • Its callers, before the edit.

Satori is the colleague who has read the whole project: “That lives here. These places use it. Read this first.”

One question. Four layers. One repository state.

Every answer comes from one Publication, a single indexed snapshot of the repository. Search, owners, calls, and source always agree.

Search

Semantic + lexical retrieval

Meaning, BM25, exact paths, identifiers, and configuration keys.

find intent without losing literals
Owners

Symbols + structural spans

Parser-derived functions, classes, file outlines, and exact spans.

rank evidence around real owners
Trace

Supported relationships

Callers, callees, imports, and exports, only when the parser can prove them.

advisory, conservative, fail-closed
Truth

Freshness + Publication authority

Source checkpoints, runtime compatibility, and atomic swaps to the next snapshot.

know which repo state answered

From a human question to source evidence.

No exact identifier needed. Satori narrows the search in stages, and each stage points at real source.

Real run on ollama/ollama: 1,138 files indexed offline in 30 seconds. Asked where the 5-minute keep-alive default is set, Satori found envconfig.KeepAlive(), its caller, and the source. A grep-driven edit landed in the wrong place. Indexing is sped up.
See semantic code search in an agent

Less reading. Better answers.

A few simple tools, backed by the code-intelligence stack your MCP host would otherwise rebuild.

Fast exact lookups

14-65ms p50

Exact symbol lookup on five pinned repositories, fully offline.

Offline after install

Embeddings, search, storage, and reranking run on your machine. No model API key.

Reranking that finds owners

LateOn puts the owning code first, locally. It doubled first-hit accuracy in our 36-task test. See how ranking works.

Parser-derived repository structure

Symbols, exact spans, and call navigation in nine production languages, plus Kotlin and PHP.

Token-efficient by design

Exact spans instead of whole files, so context goes to the code that matters.

One coherent Publication

Search, symbols, structure, and calls go live together. Ambiguous relationships fail closed.

  1. search
  2. symbols
  3. structure
  4. calls

Built to put the owning code first.

If the right file comes back at rank seven, your agent reads six wrong files first. Satori ranks for the code that owns the behavior.

  1. Retrieve three ways Embeddings, BM25, and exact symbols, so paraphrases and identifiers both land.
  2. Search the agent’s guesses Up to four alt_terms from the agent, each searched and fused with the question.
  3. Vote for definitions Code that defines a symbol outranks code that only mentions it.
  4. Rerank with context Up to 64 candidates, with role, callers, callees, and tests. LateOn on your CPU, or Voyage in the cloud.
  5. Return exact evidence The owning span, its file outline, and call paths to follow.

0.19 0.39

Owner ranked first with LateOn. 36 tasks, 6 repositories.

16 34

Owners in the top 10 with agent alt_terms. 46 questions. Median 2.7 s to 2.9 s.

4 13

Named symbols at rank 1 with definition fusion and LateOn, against no reranker. 19 questions, 4 repositories.

1.86 s 1.22 s

LateOn on 64 candidates, adaptive session pool, 8-core Ryzen 7 3800X. Identical scores.

Choose a reranker

LateOn default, offline

Runs on your CPU. Code stays local. 13 of 28 owners first, median search 2.40 s.

satori reranker use lateon

best ranking, free tier

Voyage AI by MongoDB

18 of 28 owners first with rerank-3-lite, median search 1.04 s. 200 million free tokens per model, about 8,000 searches, with no credit card. Queries and code excerpts go to Voyage.

The command asks for your VOYAGEAI_API_KEY (hidden), saves it to ~/.satori/.env, and tests it before it switches.

satori reranker use voyage
satori reranker status

None fastest

Retrieval order only. About 200 ms per search on React (36,233 chunks).

satori reranker use none

28 questions on React, Polars, and FlatBuffers, same index for every reranker. Restart your agent after a switch. If Voyage fails, Satori returns retrieval order and reports RERANKER_FAILED. No global CLI? Use npx -y @satori-code/cli@latest in place of satori.

Read the reranker docs See the full benchmark

Use Satori when the repository is larger than the prompt.

Walk into an unfamiliar codebase with a map.

Ask where a behavior lives. Get the owner and its file outline, then read the code.

“What owns billing retries?”

Turn a symptom into source.

Start from an error. Follow owners and callers to the exact code.

Plan before the first edit.

See the owner, its structure, and its call paths before you touch a subsystem.

Give a fast model the context it would skip.

Flash and local models are cheap but read less. Satori does the discovery: hybrid search, the model’s own alt_terms, and reranking put the owner on top, so the model reads one exact span. With LateOn, a fully local setup stays local.

“Where is the cleanup of useEffect?” → commitHookEffectListUnmount

Share repository intelligence, not the prompt.

Local agent sessions share one runtime and index, and each keeps its own MCP session.

Free, local, read-only.

What to ask before you install anything that reads your code.

Is it really free?
Yes. Open source under AGPL-3.0, with no account or paid tier. The offline runtime needs no API key, so nothing bills you.
Does my code leave my machine?
Not by default. Embedding, storage, search, and telemetry make no network requests after install. Voyage and Milvus/Zilliz are opt-in.
Will it change my repository?
No. Satori only reads source. Install adds nothing to AGENTS.md or hooks, and never overwrites files it did not write.
What does install download?
The runtime and about 100 MB of models, once, into ~/.satori/. Nothing downloads again on startup.
Which languages?
Symbol navigation for TypeScript, JavaScript, Python, Go, Java, C#, C++, Rust, and Scala, plus Kotlin and PHP. Search covers about 140 languages.
How do I remove it?
satori uninstall removes client config and the shared skill. Add --purge to also delete the runtime, models, and indexes.

Try it on one repo.

Two commands, then one sentence to your agent. Beta on Linux x64 and WSL2.

Install supported clients 
npx -y @satori-code/cli@latest install
npx -y @satori-code/cli@latest doctor
Then restart your agent and tell it 
Index /absolute/path/to/repo with Satori, then find where auth refresh is handled.
Optional: stronger ranking with a free Voyage API key 
npx -y @satori-code/cli@latest reranker use voyage

  1. Index

    Index the repository and wait until status is ready.

  2. Ask

    Ask what owns a behavior, in plain English.

  3. Follow evidence

    Open the exact span, outline, or call path that Satori returns.

Open setup docs View source on GitHub

The index keeps itself fresh.

Default offline stack

  • Potionlocal semantic embeddings
  • BM25lexical + exact evidence
  • LateOnlocal query-time reranking
  • LanceDBlocal Publication storage

No model API key needed after install. Voyage and Milvus/Zilliz are optional.

Freshness and repair

  1. Source changedIncremental sync builds a replacement Publication.
  2. Sync runningThe last proven Publication stays readable, with freshness info.
  3. Rebuild required, managed offlineSatori starts or joins one background reindex.
  4. Remote, failed, or unsafeYou run reindex explicitly.
  5. ClearAlways manual.
  • Read-only source. Satori does not modify repository files.
  • Conservative graph. Absent edges are not proof of no caller.
  • Open source. AGPL-3.0-only.
Read maintenance docs Inspect the architecture

Build with it. Break it. Tell me.

If Satori helps, fails, or confuses you in a real repository, I want the case.

ahmed@hamza.my.id
Integration Bug report Workflow feedback Launch feedback
Repo
language and approximate size
Client
Codex, Claude, OpenCode, or another MCP host
Task
bug hunt, refactor, onboarding, or evaluation

Tried it? Tell me what happened.

Release notes, every two weeks.

What shipped, what broke, and what users found. Unsubscribe in one click.