"It edited the obvious file."
Nearby text is not the same as the right implementation path. Satori gives the agent a way to inspect the code it is about to rely on.
Satori helps AI coding agents investigate real repo context before they edit. It searches code, opens exact symbols, suggests runnable next steps, follows callers/callees, and warns when repo context is stale.
AI agents can grep files. Real repos need more: exact symbols, runnable next steps, callers, callees, freshness checks, and bounded evidence before an edit.
Nearby text is not the same as the right implementation path. Satori gives the agent a way to inspect the code it is about to rely on.
A change can look small until another function depends on it. Satori exposes callers and callees when call graph data is ready.
Active repos move while agents work. Satori checks freshness and returns explicit reindex guidance instead of silently trusting old data.
Satori returns file paths, symbols, spans, warnings, and fallback navigation so agent decisions are easier to inspect.
Search results can include suggested follow-up actions: read the exact symbol, inspect the outline, or trace callers and callees.
One compact demo is enough: ask for a change, inspect real repo context, then edit with fewer blind spots.
The agent searches a few nearby files, guesses which function matters, edits from partial context, and leaves you to discover what it missed.
The agent asks the repo, follows returned next actions, reads the exact implementation span, and checks caller/callee context before proposing an edit.
Natural-language search over indexed code returns grouped results, warnings, freshness state, and runnable next actions.
The agent uses deterministic file outlines and symbol spans instead of copying the nearest text chunk into a prompt.
When the sidecar is ready, call graph traversal shows surrounding code paths. When it is not ready, Satori returns a runnable navigation fallback.
Satori does not promise bug-free changes. It reduces blind edits by giving agents specific repo evidence first.
For indie devs and vibe coders using Claude Code, Codex, MCP clients, or Cursor-style agent workflows where the repo is too large to paste into chat.
Keep the agent moving, but make investigation part of the workflow before it touches important files.
Mixed docs, tests, generated files, stale indexes, and renamed paths are normal. Satori treats those as first-class states.
Results point to real files, symbols, line spans, warning states, and exact next tool calls.
Satori does not expose source-code write tools. It gives agents search, navigation, and read evidence; edits stay in your normal editor or host workflow.
Search can start from a subdirectory inside an indexed repo, while Satori keeps the root identity and navigation paths consistent.
Satori is MIT/open source. Zilliz and VoyageAI may offer free allowances suitable for a trial; provider limits can change.
Index once, then let the agent investigate through a small MCP surface: search, outline, graph, read, sync, and lifecycle management.
Satori chunks code, stores embeddings, builds sidecar metadata, and tracks fingerprints so incompatible indexes do not look ready.
Your MCP-compatible client calls Satori tools instead of relying on ad hoc file search alone.
Search results tell the agent whether to read the exact symbol, inspect the outline, or trace caller/callee context next.
Requires-reindex, backend timeout, missing sidecar, and noisy-result states return explicit guidance instead of silent degradation.
Satori does not just help your agent find code. It helps your agent decide what to inspect next, while staying honest about what static evidence can and cannot prove.
Open the symbol or file range that matters instead of dumping broad context into the model.
Depth-bounded call graph context helps the agent see nearby code relationships before changing a function.
Search results include suggested follow-up actions: open the exact symbol, inspect the outline, or trace callers and callees.
Debug active branches faster with changed files, changed symbols, and direct callers surfaced from call graph metadata.
Find static references from test-like files to the symbol under investigation without claiming false coverage.
When build artifacts appear in context, Satori reminds agents to verify the generated file directly.
Fingerprint gates and freshness decisions stop old indexes from pretending to be current.
Stable sorting, warning codes, and fallback payloads make results easier to replay and debug.
The six MCP tools stay small. The outcomes are what matter during a coding session.
search_codebase searches by intent and exact terms
with runtime, docs, or mixed scope, then returns grouped results
with navigation hints and next actions.
file_outline maps symbols and resolves exact labels or
IDs without guessing on ambiguity.
call_graph traverses callers and callees when graph
support is ready for the symbol.
read_file opens files, line ranges, or exact symbols
with optional outline metadata.
Search results can suggest the next move: open the exact symbol, inspect the outline, or trace callers and callees.
Satori can surface static references from test-like files to the symbol under investigation — useful hints, not fake coverage claims.
list_codebases and search freshness states show what
is ready, indexing, failed, or requires reindex.
manage_index handles create, sync, reindex, status,
and clear with explicit destructive-action semantics.
Start with one repo and one MCP client. Add providers later. Use the CLI installer first; open manual config only when you need to wire a client yourself.
npx -y @zokizuan/satori-cli@0.3.2 install --client codex
npx -y @zokizuan/satori-cli@0.3.2 install --client claude
npx -y @zokizuan/satori-cli@0.3.2 install --client all --dry-run
npx -y @zokizuan/satori-cli@0.3.2 doctor
The installer writes managed client config and copies the
first-party satori-search,
satori-navigation, and
satori-indexing skills. The doctor command checks
provider and Milvus setup without starting an MCP client.
[mcp_servers.satori]
command = "npx"
args = ["-y", "@zokizuan/satori-mcp@4.10.1"]
startup_timeout_ms = 180000
env = { EMBEDDING_PROVIDER = "VoyageAI", EMBEDDING_MODEL = "voyage-4-large", EMBEDDING_OUTPUT_DIMENSION = "1024", VOYAGEAI_API_KEY = "your-api-key", VOYAGEAI_RERANKER_MODEL = "rerank-2.5", MILVUS_ADDRESS = "your-milvus-endpoint", MILVUS_TOKEN = "your-milvus-token" }"satori": {
"command": "npx",
"args": ["-y", "@zokizuan/satori-mcp@4.10.1"],
"timeout": 180000,
"env": {
"EMBEDDING_PROVIDER": "VoyageAI",
"EMBEDDING_MODEL": "voyage-4-large",
"EMBEDDING_OUTPUT_DIMENSION": "1024",
"VOYAGEAI_API_KEY": "your-api-key",
"VOYAGEAI_RERANKER_MODEL": "rerank-2.5",
"MILVUS_ADDRESS": "your-milvus-endpoint",
"MILVUS_TOKEN": "your-milvus-token"
}
}
MILVUS_TOKEN is only needed for authenticated
Milvus or Zilliz endpoints; local unauthenticated Milvus only
needs MILVUS_ADDRESS.
The landing page stays simple. The technical depth is still here: deterministic ranking, sync-on-read search, fingerprint gates, completion-proof checks, and timeout-safe lifecycle recovery.
Stat-first hash-on-change updates changed files instead of re-embedding the whole repo on every sync.
Dense semantic search can be paired with BM25 keyword retrieval and reciprocal-rank fusion, so concepts and exact tokens both matter.
Supported languages are split around real code structure, so search results are less likely to cut through function or class boundaries.
scope=runtime excludes docs/tests, docs
targets documentation, and mixed includes everything.
TypeScript, JavaScript, and Python get the strongest graph/outline support. Other languages still search, but unsupported graph states return explicit fallback guidance.
Cloud and local providers use different search budgets and rerank policies, so Ollama-style local workflows stay responsive.
Cloud collections repair local ready state only after marker, path, and fingerprint validation.
Indeterminate Milvus/Zilliz delete or validation timeouts are returned as backend state, not repo failure.
Deterministic tie-break chain:
score desc -> file asc -> start_line asc -> symbol label asc -> symbol id ascThe architecture page keeps the deeper system view: open architecture.html.
If context is not safe to trust, Satori says so and gives the next recovery step.
Any requires_reindex response includes
hints.reindex with the exact path to repair before
retrying the original call.
manage_index({ action: "reindex", path: <hints.reindex.args.path> })
// then retry the original tool call
If hints.noiseMitigation appears, apply the
suggested .satoriignore patterns, wait one debounce
window when provided, then rerun search.
If generated files like dist, build,
or .output appear in search context,
hints.verification.generatedArtifacts points to
direct artifact reads. Source matches do not prove generated
output is current.
If call_graph returns not_ready, search
results still include navigationFallback with a
runnable read span and optional file outline window.
If Zilliz/Milvus times out during collection validation or deletion, Satori returns retryable backend guidance and preserves local state unless remote absence is verified.
Zilliz free tier limits collections.
manage_index create can return guided text naming a
collection to drop. Retry with zillizDropCollection.