Satori gives coding agents repo-aware retrieval through a fixed six-tool MCP surface: index lifecycle, semantic search, symbol outlines, exact reads, and bounded call-graph context.
Satori runs as an MCP server. The easiest path is the CLI installer: it writes managed client config and copies the first-party workflow guidance without adding new MCP tools.
Recommended public setup:
npx -y @zokizuan/satori-cli@0.4.5 install --client all,
then
npx -y @zokizuan/satori-cli@0.4.5 doctor.
Restart the MCP client after install.
npx -y @zokizuan/satori-cli@0.4.5 install --client codex
Writes the Satori MCP entry to ~/.codex/config.toml
and installs the Satori skill in ~/.codex/skills.
npx -y @zokizuan/satori-cli@0.4.5 install --client claude
Writes the Satori MCP entry to
~/.claude.json and installs the Satori skill
in ~/.claude/skills.
npx -y @zokizuan/satori-cli@0.4.5 install --client opencode
Writes the Satori MCP entry to
~/.config/opencode/opencode.json and installs the
Satori workflow instructions in
~/.config/opencode/AGENTS.md.
Use --client all to install every supported client, and
uninstall with the same selector to remove only
Satori-managed config and skills. Run
npx -y @zokizuan/satori-cli@0.4.5 doctor to check
provider and Milvus setup without starting an MCP client.
Use --profile default|minimal|all-text when the current
repository should write or update repo-local
satori.toml. This file controls index policy only; it
is not a place for API keys, model names, Milvus endpoints, or
tokens.
The generated ~/.codex/config.toml entry includes
active env_vars forwarding and an optional commented
[mcp_servers.satori.env] template. Put literal values
outside the managed launcher block if you want reinstall-safe
direct config.
The generated ~/.claude.json entry writes
mcpServers.satori.env with ${VAR:-}
pass-through values. Replace any value with a literal if you want
Claude to own that setting.
The generated OpenCode entry writes
mcp.satori.environment with {env:VAR}
pass-through values. Replace any value with a literal to store it
directly in OpenCode.
The installer resolves the package once, writes the runtime under
~/.satori/mcp-runtime/, creates the stable launcher
~/.satori/bin/satori-mcp.js, and points supported
clients at that launcher with Node.
Do not use resident npx commands for supported
clients; package-manager startup latency is exactly what the
installer avoids.
~/.codex/config.toml.~/.codex/skills.~/.claude.json.~/.claude/skills.~/.config/opencode/opencode.json.~/.config/opencode/AGENTS.md.The installer refuses to overwrite unmanaged Satori entries. If you already have one, remove or align it before rerunning install.
satori.toml is a repository-local index policy file.
It is separate from installer-managed client config and from provider
runtime environment variables.
[index]
profile = "minimal"
Missing config defaults to default. Invalid
index.profile values fail closed with an explicit
profile error.
Safe-broad indexing for source, docs/text, config, scripts,
infra/query files, and known extensionless files such as
Dockerfile, Makefile,
Justfile, Taskfile,
Procfile, Jenkinsfile, and
.dockerignore.
Source plus docs/text only. Use it when you want lower indexing cost and do not need config, scripts, or infra files in the index.
Safe-broad plus unknown UTF-8 text files under the size cap.
SATORI_ALL_TEXT_MAX_BYTES can override that cap.
The hard denylist still applies first.
Index profiles decide what enters the index. Search scope decides
what gets queried. search_codebase still defaults to
scope=runtime, so indexing docs/config does not make
documentation beat implementation code by default.
satori.toml, .gitignore, and
.satoriignore are index-policy control files. Ordinary
changes can converge through search freshness or
manage_index action="sync"; incompatible fingerprints
still return requires_reindex.
Configure the embedding provider and vector backend before indexing. Those values are part of the index fingerprint, so changing provider, model, dimension, or vector-store schema later requires a reindex. Restart every Satori MCP client before mutating indexes after those changes.
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-tokenThis is the recommended first path for quality: VoyageAI embeddings plus Milvus or Zilliz for vector storage.
EMBEDDING_PROVIDER=Ollama
EMBEDDING_MODEL=nomic-embed-text
OLLAMA_HOST=http://127.0.0.1:11434
MILVUS_ADDRESS=localhost:19530
Use this path when you want local embeddings. Keep model and
dimension stable for any repo you have already indexed.
MILVUS_TOKEN is optional auth only and is not a
substitute for MILVUS_ADDRESS.
Satori only returns repo context after a codebase has been indexed. Start with one absolute repository path, confirm it appears in the codebase list, then search with runtime-first defaults.
Run list_codebases in your MCP client to verify the
server starts and can see its local state.
Run
manage_index action="create" path="/absolute/path/to/repo".
Use the repository root for the first index unless you have a
specific subdirectory workflow.
Run a plain-English behavior query, for example
search_codebase path="/absolute/path/to/repo" query="where is authentication flow enforced".
Defaults are scope=runtime,
resultMode=grouped, and
groupBy=symbol.
Use file_outline, call_graph, and
read_file to lock exact spans before editing.
The default agent path starts with plain-English discovery, then narrows to proof. Search groups evidence by owner symbols, outline locks deterministic spans, call graph adds nearby context when supported, and exact reads provide edit context.
Use search_codebase with the user requested path and
a behavior or concept query. Default scope is runtime, grouped by
symbol, with changed-file awareness when the repository supports
it. Prefer recommendedNextAction when present.
Use file_outline to lock symbol spans before reading
or editing. Exact mode resolves symbolInstanceId
deterministically and reports ambiguity instead of guessing.
Use call_graph with the returned
callGraphHint.symbolRef. On symbol-owned flows,
symbolRef.symbolId carries the exact
symbolInstanceId. Treat the output as graph context,
not a complete impact guarantee.
Use read_file with open_symbol or the
returned navigation fallback. Use result fallbacks when graph
confidence is weak or unsupported. Reads are bounded and return
continuation hints when truncated.
If a tool returns requires_reindex, run
manage_index(action="reindex") for the hinted path
before retrying the original call.
If manage_index returns
reason="runtime_owner_conflict", restart all Satori
MCP clients so only one runtime fingerprint/config identity is
active, then retry the mutation. MCP tools never kill processes or
ask interactive cleanup questions.
Satori keeps the public MCP surface fixed. Diagnostics are added through existing tools, not through new product surface area.
Lists indexed repositories in deterministic buckets: ready, indexing, requires reindex, and failed.
Creates, syncs, checks status, reindexes, or clears indexes. Status includes health diagnostics when available.
Semantic search with runtime/docs/mixed scopes, path operators, must/exclude filters, grouped output, and debug metadata. Search is the freshness-aware read path and returns structured warnings, recommended actions, capability confidence, and executable navigation fallbacks.
Reads sidecar symbol outlines and resolves exact symbols without guessing when matches are ambiguous.
Traverses sidecar caller/callee relationships with deterministic depth, limits, and transparency metadata when graph support is ready for the returned symbol reference.
Reads plain text or annotated content. Exact symbol opening delegates to outline resolution.
Lifecycle operations have different meanings. Use sync for ordinary file changes, reindex for fingerprint or sidecar incompatibility, and clear only when you intentionally want to remove a tracked codebase. Create, reindex, sync, and clear are blocked when another live Satori MCP runtime has a different fingerprint, version, or config identity.
manage_index action="sync" is the immediate
convergence lever after normal file edits or ignore-rule changes.
Search also runs freshness checks before returning results.
Successful sync reuses changed-file symbol output, preserves
unchanged registry state, and recomputes relationships globally
without re-splitting unchanged files.
manage_index action="reindex" rebuilds the index.
Use it when a tool returns requires_reindex or a
reindex hint. Do not substitute sync for fingerprint
incompatibility.
If changed-file indexing stops early, navigation state is cleared instead of publishing a mixed generation. That fail-closed path is also a reindex signal.
manage_index action="clear" is destructive. Do not
call it for routine refresh. Use it only when the user explicitly
asks to remove Satori's tracked index for a codebase.
manage_index action="status" answers why a repo is
or is not usable right now.
Satori separates usable degraded output from blocking lifecycle states. Agents should branch on structured statuses and warnings instead of parsing prose.
Warnings are structured objects with a stable code, severity,
blocking flag, message, and action. They mean the result is
usable but degraded unless blocksUse=true.
FILTER_MUST_UNSATISFIED
SEARCH_PARTIAL_INDEX:limit_reached
RERANKER_FAILED
SEARCH_PASS_FAILED:*
requires_reindex is not a warning. It is a blocking
status or remediation hint. Reindex the hinted path, then retry
the original call.
fingerprint_mismatch,
completion_marker_missing,
missing_symbol_registry,
missing_relationship_sidecar,
incompatible_symbol_registry,
incompatible_relationship_sidecar, watcher state,
and sidecar readiness explain why the tool chose a lifecycle
state. Legacy missing_sidecar wording is less
precise and should not be preferred for new public paths.
Use debug=true on search_codebase when
you need ranking, filter, freshness, exact-registry,
tracked-lexical, reranker, or phase-timing explanations. Start
with hints.debugSummary, then drill into
hints.debugSearch only when needed.
Normal search output should stay compact. Use
debug=true when you need to understand ranking, filters,
fallback passes, or exclusions.
Warnings mean usable but degraded; follow each warning action.
Failures and requires_reindex statuses require
remediation before treating results as current.
Prefer status and debug output before guessing. The goal is to make repo state visible enough for the agent to choose the next operation.
Run manage_index(action="create") on the repository
root, then retry search.
Run manage_index(action="reindex"). Do not use sync
as a substitute for fingerprint incompatibility.
Apply suggested ignore patterns through repo
.satoriignore, then run
manage_index(action="sync") for immediate
convergence.
If indexing or search returns
MISSING_PROVIDER_CONFIG, run
npx -y @zokizuan/satori-cli@0.4.5 doctor, set the
missing provider or Milvus values, then retry the same tool call.
It is an active setup failure only when it appears as the tool
response code or reason; inside
search_codebase results it may just be matched code
content.
Follow the returned navigation fallback. Read exact spans and use additional scoped searches to enumerate usages.
For Product Hunt or another public launch, keep the message narrow: Satori is read-only repo retrieval for MCP coding agents. It helps agents inspect evidence before edits; it does not replace tests or code review.
Repo retrieval for MCP coding agents.
npx -y @zokizuan/satori-cli@0.4.5 install --client all
npx -y @zokizuan/satori-cli@0.4.5 doctorProduct Hunt copy, preflight commands, website checks, and launch-day monitoring live in docs/LAUNCH_CHECKLIST.md.
npx setup for supported clients.