Satori

Start

Beta. Satori supports Linux only for now (x64, including WSL2 on Windows). macOS and native Windows are not supported yet.

Needs Node.js 22.13+ on Linux x64 or WSL2.

npx -y @satori-code/cli@latest install
npx -y @satori-code/cli@latest doctor

install sets up Codex, Claude Code, and OpenCode (Antigravity with --client agy). Restart your agent and say:

Index /absolute/path/to/repo with Satori, then find where auth refresh is handled.

That's it. No account, no API key.

Or let your agent do the setup. Paste this:

Install Satori by following the "For AI agents" section of
https://github.com/ham-zax/satori, then index this repository.

Related MCP server: code-search

For AI agents

If you are a coding agent setting up or using Satori, follow these steps.

Install

1. Check the platform: node -v must be 22.13 or newer, on Linux x64 or WSL2. Native Windows and macOS are not supported; on Windows, run inside WSL2.

2. Run npx -y @satori-code/cli@latest install, then npx -y @satori-code/cli@latest doctor.

3. If install reports no supported client, rerun it with --client codex, claude, opencode, agy, or all.

4. Tell the user to restart you. The Satori MCP tools load only at agent startup.

Use

1. Call list_codebases. If the repository is not indexed, call manage_index with action="create" and the repository's absolute path. Indexing runs in the background; check it with action="status".

2. Start every "where is…", "what owns…", or "what calls…" question with search_codebase. For plain-English questions, pass up to 4 likely code identifiers or terms in alt_terms.

3. Follow recommendedNextAction when it is returned. Use file_outline to pick a symbol, and call_graph or trace_path for relationships.

4. Read the exact code with read_file before you claim anything or edit.

5. After editing files, call manage_index with action="sync" when you need fresh results.

Rules

• Every path is absolute.

• Treat call_graph results as leads to verify, not complete proof.

• Satori is read-only. Make source edits with your own tools.

• The installer also ships a satori skill (~/.agents/skills/satori) with the full workflow.

How it works

You ask a question. Your agent follows the evidence:

search_codebase  →  owner  →  file_outline / call_graph  →  read_file
  by meaning         the         structure and              exact source
  and exact text     symbol      supported relationships    to verify

Satori combines embeddings with BM25 and exact matches, maps hits to the symbols that own them, and keeps every answer on one indexed snapshot of the repository. Edits sync incrementally, and every answer says whether its evidence is still current.

Why use it

• Unfamiliar code. Ask where behavior lives before you know a filename.

• Bugs. Go from an error string to the code that owns it.

• Refactors. See the owner, its structure, and its callers before the first edit.

• Less context waste. Your agent reads symbol-sized evidence, not whole files. Smaller local models benefit most.

• Many agents, one index. Local sessions share one runtime.

Free, local, read-only

• Free and open source under AGPL-3.0. No account and no telemetry upload.

• The default stack runs offline after install: Potion embeddings, BM25, LateOn reranking, and LanceDB.

• Satori never edits your source and adds nothing to AGENTS.md or hooks.

• satori uninstall removes client config; --purge also deletes ~/.satori.

• Connected Voyage and Milvus/Zilliz, or local Ollama, are optional. See the reference.

Benchmarks

The offline stack. Potion is a 16M-parameter static code embedding, fast enough to embed a whole repository on a laptop CPU. BM25 and exact matching catch the identifiers it misses. LateOn is a 17M-parameter late-interaction code model. It is too costly to run over everything, so Satori uses it only to rerank the top candidates (budget 64), together with each candidate's role, callers, callees, and tests.

What reranking adds. 36 owner-finding tasks across 6 repositories, where "owner at 1" means the right symbol comes first:

Tuning-set results, measured on an earlier prompt projection; the held-out run is still pending. Evidence and limits. On the current build (budget 64), baseline reaches 0.44 owner@1 and 0.78 owner@10 across 18 judged real-repo tasks.

On the current default (LateOn reranking plus definition fusion, which runs only with reranking), 19 named-symbol questions across 4 repositories went from 4 to 13 owners at rank 1 against no reranker; owner in the top 10 stayed at 15 either way. Corrected comparison.

Plain-English questions. 46 conceptual questions over React, Polars, and FlatBuffers ("cleanup of useEffect" → commitHookEffectListUnmount). Agents can pass up to 4 code-vocabulary guesses in alt_terms; Satori searches them as separate passes, including definitions, and fuses them with the original question:

Tuning set with seven labels corrected to the pinned commits. Wrong guesses cost more than none; fixes that limited that cost also cost owners with good guesses, so they were rejected. Details.

Search latency. Measured on React (6,918 files, 36,233 chunks) with the offline CPU stack:

Reranking adapts to the machine. LateOn encodes candidates in parallel model sessions sized from the host's CPUs and free memory: 1 session on 1 CPU, 4 single-threaded sessions on 4–6 CPUs, 4 × 2 threads on 8–16 CPUs, up to 8 × 2 on 32 or more (above 16 CPUs the rule is extrapolated, not measured). Scores are bit-identical to the single-session path. On a Ryzen 7 3800X under WSL2 (15 logical CPUs visible):

Each session needs 1 GiB of free memory at worker start, so memory-limited hosts and containers run fewer sessions with more threads. The worker is released after 2 minutes idle.

Against codebase-memory-mcp 0.11.0. Same machine, 5 public repositories; each range spans two runs:

codebase-memory-mcp builds only a graph, so it indexes and answers caller queries faster. Satori also builds embeddings and a vector index, which is what lets it answer plain-English "where is this behavior" questions that a graph cannot. All 5 repositories and the raw results.

Languages

Call graphs for TypeScript, JavaScript, Python, Go, Java, C#, C++, Rust, Scala, Kotlin, and PHP. Symbols and outlines for 88 more languages. Semantic search across about 140. Details.

Commands

Without a global install, prefix commands with npx -y @satori-code/cli@latest.

Learn more

• Docs: setup, tools, and troubleshooting.

• Full reference: runtimes, configuration, index profiles, benchmarks.

• Product guide: how to get the most out of Satori.

Development

pnpm install
pnpm build
pnpm run check

See CONTRIBUTING.md, SECURITY.md, and docs/RELEASING.md.

License

AGPL-3.0-only. Commercial licensing is available: see COMMERCIAL-LICENSING.md.

Copyright (c) 2026 Hamza (@ham-zax).