Start
Beta. Satori supports Linux only for now (x64 and ARM64 with glibc, including WSL2 on Windows). macOS and native Windows are not supported yet.
Needs Node.js 22.22+ on Linux x64, Linux ARM64 with glibc, 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.
For AI agents
If you are a coding agent setting up or using Satori, follow these steps.
Install
- Check the platform:
node -v must be 22.22 or newer, on Linux x64, Linux ARM64 with glibc, or WSL2. Native Windows and macOS are not supported; on Windows, run inside WSL2.
- Run
npx -y @satori-code/cli@latest install, then npx -y @satori-code/cli@latest doctor.
- If install reports no supported client, rerun it with
--client codex, claude, opencode, agy, or all.
- Tell the user to restart you. The Satori MCP tools load only at agent startup.
Use
- 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".
- 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.
- Follow
recommendedNextAction when it is returned. Use file_outline to pick a symbol, and call_graph or trace_path for relationships.
- Read the exact code with
read_file before you claim anything or edit.
- After editing files, call
manage_index with action="sync" when you need fresh results.
Rules
- Every
path is absolute.
manage_index action="status" can start or join an automatic rebuild for an incompatible tracked root. Check roots serially on memory-constrained hosts.- Treat
call_graph results as leads to verify, not complete proof.
- Satori is read-only. Make source edits with your own tools.
satori install --skill also installs the optional 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.
| Tool | What it does |
|---|
manage_index | Create, sync, inspect, cancel, reindex, or clear the index. |
search_codebase | Find behavior by meaning and exact evidence. Start here. |
architecture_overview | Summarize areas, boundaries, and hotspots. |
continue_search | Page through a result set without searching again. |
file_outline | List the symbols and spans in one file, with the current span next to the published span when it was proven. |
call_graph | Callers, callees, imports, and exports where supported. |
trace_path | Shortest relationship path between two symbols. |
find_references | Exact textual occurrences of one symbol. |
detect_changes | Map a Git diff to affected symbols and callers. |
read_file | Read one symbol or a bounded source span. |
list_codebases | List indexed repositories and their readiness. |
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. For Claude Code, install adds one read-only SessionStart hook that reports index state and never indexes.
satori uninstall removes client config; --purge also deletes ~/.satori.- Connected Voyage and Milvus/Zilliz 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:
| Stack | Owner at 1 | Owner at 3 | MRR |
|---|
| Potion + BM25 + exact | 0.19 | 0.36 | 0.29 |
| + LateOn reranking (depth 32) | 0.39 | 0.64 | 0.50 |
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.
Choosing a reranker. LateOn is the local default. Voyage is an opt-in online reranker (satori reranker use voyage); it works with the offline Potion index and sends each query and its candidate code excerpts to Voyage AI, a MongoDB company. Each Voyage account gets 200 million free tokens per model, about 4,600 searches at the measured rate. 28 plain-English questions over React, Polars, and FlatBuffers, same Potion index for every row:
| Reranker | Right answer first | In top 5 | In top 10 | MRR | Rerank median |
|---|
| LateOn (local, default) | 13/28 | 22/28 | 24/28 | 0.566 | 2.58 s |
Voyage rerank-3-lite (Voyage default) | 23/28 | 27/28 | 27/28 | 0.881 | 1.03 s |
Voyage's canonical projection sends about 60% more input bytes than the native document, so it uses the free quota faster. Three runs per row on one WSL2 laptop; times are the median reranker time. Measured at fb125738, before the default-on cleanup → destroy bridge (9abe9006); the bridge moves r1 to rank 1 on the 28-question rerank-3 run, and the rerank-3-lite row is not re-measured. How to choose, and the limits of these numbers.
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:
alt_terms | Owner at 1 | Owner in top 10 | Median request |
|---|
| None | 8 | 16 | 2.7 s |
| The agent's own guesses | 16 | 34 | 2.9 s |
| Another question's guesses (stress test) | 1 | 8 | 2.8 s |
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:
| Phase / Mode | Median latency | Notes |
|---|
| Fast retrieval (Potion + BM25) | 178 ms | Dense vector search and lexical candidate fusion |
| + LateOn reranking (budget 64, CPU FP32) | 2.5–3.1 s | Full cross-attention reranking of top 64 code passages, one model session |
Fast mode (--reranker none) | ~200 ms | Disables LateOn; pure embedding + BM25 search |
| Cold query with filesystem watcher | < 1 s | Bounded watcher settle; avoids recursive directory stat scan |
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):
| Measurement | One session (1 × 8 threads) | Adaptive pool (4 × 2) |
|---|
| Rerank 64 candidates (median of 3 runs) | 1.86 s | 1.22 s |
| Plain-English question to ranked owners (46 questions, median) | 2.63 s | 2.24 s |
| Rerank phase of those requests (median) | 2.12 s | 1.68 s |
| Peak reranker memory | 0.53 GB | 1.64 GB |
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:
| Repository | System | Full index | Symbol lookup (p50) | Callers (p50) | One-file edit |
|---|
| ripgrep (Rust) | Satori | 5.8 s | 8–9 ms | 136–146 ms | 3.3 s |
| CBM 0.11 | 2.8–2.9 s | 13 ms | 13 ms | 2.1–2.2 s |
| trufflehog (Go) | Satori | 42–55 s | 22–23 ms | 29–30 ms | 19 s |
| CBM 0.11 | 8.9–9.2 s | 17–18 ms | 15 ms | 24–32 s |
| satori (TypeScript) | Satori | 42–46 s | 11 ms | 21–24 ms | 13 s |
| CBM 0.11 | 20 s | 29–30 ms | 20 ms | 13 s |
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
| Command | Does |
|---|
satori install | Install the runtime and configure your agents. |
satori doctor | Check the installation. |
satori upgrade | Upgrade to the latest verified release. |
satori terminate | Stop running Satori servers. |
satori uninstall | Remove client config (--purge removes everything). |
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).
