Operational documentation

Satori Docs

Satori helps coding agents investigate real repos before editing: intent search, file outlines, exact reads, caller/callee context when supported, freshness checks, and recovery steps when context is stale.

Install the MCP Server

Satori runs as an MCP server. The easiest path is the CLI installer: it writes managed client config and concise workflow guidance without adding new MCP tools.

Recommended public setup: npx -y @zokizuan/satori-cli@latest install --client all, then npx -y @zokizuan/satori-cli@latest doctor. Restart the MCP client after install.

Codex

npx -y @zokizuan/satori-cli@latest install --client codex

Writes the Satori MCP entry to ~/.codex/config.toml and a managed guidance block to ~/.codex/AGENTS.md. Add --install-guidance-hook only when you also want an opt-in session reminder in ~/.codex/hooks.json.

Claude

npx -y @zokizuan/satori-cli@latest install --client claude

Writes the Satori MCP entry to ~/.claude.json.

OpenCode

npx -y @zokizuan/satori-cli@latest install --client opencode

Writes the Satori MCP entry to ~/.config/opencode/opencode.json and a managed guidance block to ~/.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 guidance. Run npx -y @zokizuan/satori-cli@latest doctor to check every supported client's applied runtime without starting an MCP client. The table shows configuration status, profile, embedding provider/model/dimension, reranker, vector store, and whether the values come from the managed launcher or client config. It never prints credentials or local artifact paths. Repository-backed development launchers retain the outside-managed-store warning while still reporting the profile they actually apply.

Test a Repository Build, Then Restore the Published Runtime

From a Satori checkout, the development installer builds and preflights the local Core, MCP, and CLI, then points the stable launcher at that checkout. It does not replace a globally installed published CLI. 

pnpm dev:install-local-mcp -- --client opencode --runtime offline --reranker lateon

This selects OpenCode, Potion embeddings, LanceDB, and LateOn. Supported development options are:

  • --client opencode|codex|claude|all (default: opencode).
  • --runtime offline|voyage; omission preserves the managed selection, or starts offline when no launcher exists.
  • --reranker lateon|none, available only with the offline runtime.
  • --ollama-model <id> to select Ollama instead of Potion for offline embeddings.
  • --vector-store lancedb|milvus; offline requires LanceDB and Milvus requires Voyage.
  • --no-build, --home <path>, and --node <path> for existing-build or isolated testing.

Restore OpenCode to the published runtime with:

npx -y @zokizuan/satori-cli@latest install --client opencode --runtime offline --reranker lateon
npx -y @zokizuan/satori-cli@latest doctor

Restart OpenCode after either switch. If the latest CLI is already installed globally, the equivalent restore command starts with satori install instead of npx -y @zokizuan/satori-cli@latest install.

Upgrade Satori

satori upgrade

This updates the globally installed CLI, then stages and verifies that release's exact MCP and Core runtime before switching the stable launcher. Restart running coding agents after a successful runtime upgrade.

If you did not install the CLI globally, run npx -y @zokizuan/satori-cli@latest upgrade. Upgrade does not rewrite client configuration, indexes, hooks, or repository profiles.

Satori follows the exact MCP/Core versions declared by the latest CLI package; it does not mix independently selected latest package versions.

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.

Codex Runtime Env

The installer stores the selected runtime in ~/.satori/bin/satori-mcp.js. The generated ~/.codex/config.toml entry forwards optional credentials and operational overrides; it does not duplicate a second provider/model selection. Install and uninstall commands show a concise summary by default; use --format json before the command for the complete machine-readable receipt.

Claude Runtime Env

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.

OpenCode Runtime Env

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.

Startup Model

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.

Managed Files

  • Codex config: ~/.codex/config.toml.
  • Codex guidance: ~/.codex/AGENTS.md.
  • Optional Codex hook: ~/.codex/hooks.json.
  • Claude config: ~/.claude.json.
  • OpenCode config: ~/.config/opencode/opencode.json.
  • OpenCode instructions: ~/.config/opencode/AGENTS.md.

The installer refuses to overwrite unmanaged Satori entries. If you already have one, remove or align it before rerunning install.

Repo Config and Profiles

satori.toml is a repository-local index policy file. It is separate from installer-managed client config and from provider runtime environment variables.

Config Shape

[index]
profile = "minimal"

Missing config defaults to default. Invalid index.profile values fail closed with an explicit profile error.

default

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.

minimal

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.

all-text

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.

Minimum Runtime Setup

Select the runtime through the installer before indexing. Provider, model, dimension, reranker projection, and vector-store identity are compatibility inputs; changing an incompatible selection requires a reindex. Restart every Satori MCP client after changing the managed launcher.

Offline Potion

npx -y @zokizuan/satori-cli@latest install --runtime offline

Uses the bundled Potion embedding runtime with LanceDB. Qualified Linux x64/WSL2 installs default to LateOn reranking; add --reranker none to disable neural reranking.

Offline Ollama

npx -y @zokizuan/satori-cli@latest install --runtime offline --ollama-model nomic-embed-text --reranker none

Uses the selected loopback Ollama model with LanceDB. On qualified Linux x64/WSL2, --reranker lateon is also supported.

Connected Voyage + LanceDB

VOYAGEAI_API_KEY=your-api-key \
npx -y @zokizuan/satori-cli@latest install --runtime voyage --vector-store lancedb

Uses Voyage Code 3 embeddings and local LanceDB storage.

Connected Voyage + Milvus

VOYAGEAI_API_KEY=your-api-key \
MILVUS_ADDRESS=your-milvus-endpoint \
MILVUS_TOKEN=your-optional-token \
npx -y @zokizuan/satori-cli@latest install --runtime voyage --vector-store milvus

Uses Voyage Code 3 embeddings with Milvus or Zilliz. Milvus is not accepted with the offline runtime.

Index the First Repo

Satori only returns repo context after a codebase has been indexed. Start with one absolute repository path (relative paths are rejected), confirm it appears in the codebase list, then search with runtime-first defaults.

1 Connect

Run list_codebases in your MCP client to verify the server starts and can see its local state.

2 Create

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. Create returns after accepting the operation; while the same runtime is active, poll manage_index action="status" until its process-lifetime operation phase reaches completed, failed, or blocked. Phase, progress, and error are process-lifetime state and are not reconstructed after restart; status then reports the durable current Publication state.

3 Search

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.

4 Navigate

Use file_outline, call_graph, and read_file to lock exact spans before editing.

Search Workflow

The default agent path starts with plain-English discovery, then narrows to exact code evidence. Search points to the next useful step: inspect an outline, open a symbol, read a line range, or check caller/callee context when supported.

1 Search

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.

2 Outline

Use file_outline to lock symbol spans before reading or editing. Exact mode resolves symbolInstanceId and reports ambiguity instead of guessing.

3 Graph

Use call_graph with the returned callGraphHint.symbolRef. On symbol-owned flows, symbolRef.symbolId carries the exact symbolInstanceId. Treat the output as nearby context, not a complete impact guarantee.

4 Read

Use read_file with open_symbol or the returned navigation fallback. Use result fallbacks when graph context is unsupported. Ordinary file reads use the configured line bound and return continuation hints; an exact symbol request returns the exact span resolved by file_outline.

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.

Seven Tools

Satori keeps the public MCP surface small. The tools move an agent from repo discovery to exact evidence without adding edit commands.

list_codebases

Lists indexed repositories in deterministic buckets: ready, indexing, requires reindex, and failed.

manage_index

Creates, syncs, checks status, reindexes, or clears indexes. Create and reindex return a kickoff response; poll status for the current Publication state and any process-lifetime mutation projection still available in this runtime. Status includes health diagnostics when available.

search_codebase

Semantic search with runtime/docs/mixed scopes, path operators, must/exclude filters, grouped output, and debug metadata. Runtime includes source and test evidence (tests demoted unless test intent is explicit); docs is documentation-only; mixed includes all. Search is the freshness-aware read path and returns structured warnings, recommended actions, and navigation fallbacks.

continue_search

Returns the next groups from a frozen grouped-search result set without query embedding, retrieval, or reranking. Handles are process-local; callers pass the exact next offset, making an identical retry safe. Expiry or authority drift fails closed.

file_outline

Reads Publication symbol outlines and resolves exact symbols without guessing when matches are ambiguous.

call_graph

Traverses caller/callee relationships with depth limits when graph support is ready for the returned symbol reference.

read_file

Reads bounded plain or annotated file windows. Exact symbol opening delegates to outline resolution and returns the resolved symbol span rather than applying the ordinary file-window cap.

Sync, Reindex, and Clear

Lifecycle operations have different meanings. Use sync for ordinary file changes, reindex for runtime or Publication-navigation 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.

Sync

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.

Reindex

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.

Clear

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.

Status

manage_index action="status" answers why a repo is or is not usable right now. It is also the observation path after create or reindex accepts an asynchronous operation.

  • Index state and remediation reason.
  • Current Publication proof.
  • Current runtime compatibility.
  • Publication navigation readiness and stale-state signals.
  • Watcher state and indexed file/chunk counts.

Reindex recovery

manage_index action="reindex" rebuilds an index when the current Publication is missing, incompatible, or unprovable. Use action="sync" for ordinary source divergence.

Warnings and Status

Satori separates usable degraded output from blocking lifecycle states. Agents should branch on structured statuses and warnings instead of parsing prose.

Stable Warnings

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:*

Blocking Status

requires_reindex is not a warning. It is a blocking status or remediation hint. Reindex the hinted path, then retry the original call.

Diagnostic Causes

Current Publication state, missing_symbol_registry, missing_relationship_navigation, incompatible_symbol_registry, incompatible_relationship_navigation, watcher state, and Publication navigation readiness explain why the tool chose a lifecycle state. Incompatible or unsupported pre-clean-break index state requires a fresh index or reindex.

Debug Payloads

Use debugMode=full 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.

Debugging Search

Normal search output should stay compact. Use debugMode=summary|ranking|freshness|full when you need to understand ranking, filters, fallback passes, or exclusions.

Debug payload

  • Filters applied in deterministic order.
  • Candidate counts before and after filtering.
  • Exact-registry hit, miss, ambiguity, or registry-unavailable state.
  • Phase timings for freshness, registry lookup, semantic search, lexical recovery, rerank, grouping, and navigation validation.
  • Reranker attempt and usage state.
  • Freshness mode and changed-file boost state.
  • Relaxed search pass usage when grouped output underfills.
  • Tracked lexical and live path-scoped evidence when exact lookup supplements semantic chunks.

Warnings vs failures

Warnings mean usable but degraded; follow each warning action. Failures and requires_reindex statuses require remediation before treating results as current.

Troubleshooting

Prefer status and debug output before guessing. The goal is to make repo state visible enough for the agent to choose the next operation.

Not indexed

Run manage_index(action="create") on the repository root, then retry search.

Requires reindex

Run manage_index(action="reindex"). Do not use sync as a substitute for fingerprint incompatibility.

Noisy results

Apply suggested ignore patterns through repo .satoriignore, then run manage_index(action="sync") for immediate convergence.

Missing provider config

If indexing or search returns MISSING_PROVIDER_CONFIG, run npx -y @zokizuan/satori-cli@latest 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.

Unsupported graph

Follow the returned navigation fallback. Read exact spans and use additional scoped searches to enumerate usages.

Generated output in context

If generated files such as dist, build, or .output appear in search context, verify the generated artifact directly. Source matches do not prove generated output is current.

Partial index

If a full index hits a limit, search may still return partial chunks, but navigation may be unavailable or incomplete. Treat the warning as evidence to narrow scope, sync, or reindex before relying on related-code navigation.

Backend timeout

If Milvus or Zilliz times out during validation or deletion, Satori returns retryable backend guidance and preserves local state unless remote absence is verified.

Collection limit reached

Some Zilliz tiers limit collections. Follow the returned manage_index guidance for the named collection, then retry the original lifecycle action.

Operational Boundaries

Satori provides context, navigation, reads, warnings, and recovery guidance. It does not replace the developer's normal editing, testing, or review workflow.

Not a source-code write server

Satori does not expose source-code write tools through MCP. Edits stay in the user's editor or agent host.

Not an agent framework

Satori works alongside coding agents and MCP clients. It is focused on repository context, not orchestration.

Not a test replacement

Static evidence helps agents investigate, but runtime behavior still needs tests, typechecks, review, and developer validation.

Not hosted SaaS yet

Satori is currently local-first and open source. Hosted indexing experiments and team workflows are roadmap items.