jarvis

Local-first code intelligence for coding agents. Precomputed SCIP navigation (go-to-definition, find-references, call hierarchy, document symbols), Zoekt lexical search, cross-repo blast radius, and semantic search — exposed as MCP tools to Claude Code, Cursor, or any MCP client.

Runs as a single stdio process reading local SQLite files. No server, no auth, no network, nothing leaves your machine.

One indexing CLI writes up, one stdio runtime reads down — the storage seam in ~/.jarvis is the only contract between them.

Quick Start

# 1. External indexer binaries (scip, zoekt, per-language indexers)
curl -fsSL https://raw.githubusercontent.com/jarvis-intelligence/jarvis-index/main/setup.sh | sh

# 2. jarvis itself
uv tool install jarvis-mcp

# 3. Index a repo (slug defaults to the directory name)
jarvis index /path/to/your/repo

4. Register the MCP server. Using Claude Code, install the plugin and it registers itself:

/plugin marketplace add jarvis-intelligence/jarvis-index
/plugin install jarvis@jarvis

Any other MCP client (or Claude Code without the plugin) registers manually:

claude mcp add jarvis --scope user -- jarvis-server

That's it — ask your agent "find all references to AuthService" and it will call findReferences instead of grepping.

{
  "mcpServers": {
    "jarvis": {
      "command": "jarvis-server"
    }
  }
}

git clone https://github.com/jarvis-intelligence/jarvis && cd jarvis
uv sync
claude mcp add jarvis --scope user -- uv --directory "$(pwd)" run jarvis-server

MCP tools

Every nav tool takes repo (the slug from jarvis index) plus a tool-specific symbol or path. All tools report failure the same way — a {"error": "..."} payload rather than a transport-level error, so a query bug never kills the stdio server.

Requirements and limits

Read this before installing — jarvis is deliberately narrow.

• macOS and Linux only. Windows is not supported.

• One language per repo. Language is detected by extension plurality across git-tracked files; a polyglot monorepo gets indexed as whichever language has the most files. Multi-language merge is out of scope. Override with --language.

• SCIP navigation (goToDefinition, findReferences, etc.) covers four language families: TypeScript/TSX, Python, Java/Kotlin, Swift. jarvis index --search-only additionally covers Go, Ruby, Rust, C, C++, C#, PHP, Scala, shell, and SQL for searchCode/semanticSearch only — no navigation.

• Navigation and search only — jarvis never edits code. If you want an agent that can perform semantic renames and refactors, you want Serena; the two are complementary.

• Indexing is a separate, explicit step. Nothing is live-analyzed. Run jarvis index (or jarvis watch) to publish an index before querying.

• Requires external binaries that setup.sh installs:

  Purpose	Binary	Source
  SCIP → SQLite conversion	scip	prebuilt, pinned v0.9.0 (minimum — older versions silently drop occurrence ranges)
  Lexical search	zoekt-index · zoekt-webserver	cross-compiled by our CI — upstream publishes no binaries
  TypeScript indexing	scip-typescript	npm install -g
  Python indexing	scip-python	npm install -g
  Swift indexing	scip-swift	prebuilt, macOS arm64 only
  Java/Kotlin indexing	scip-java	detect-only — Docker image, asks before pulling

  Options: --only <name> to install one dependency, --force to reinstall, --help for usage. Re-running is safe: anything already present is skipped.

Optional extras:

uv tool install "jarvis-mcp[watch]"      # + watchdog, for `jarvis watch`
uv tool install "jarvis-mcp[semantic]"   # + lancedb/sentence-transformers/tree-sitter, for semanticSearch

Why it's built this way

Storage is the seam. The runtime half only ever reads down into it; the indexing half only ever writes up into it; the two share no other contract:

Three things worth reading the diagram for:

• The runtime path never writes. Queries open a published index-<sha>.db read-only (mode=ro&immutable=1). Index files are never mutated in place.
• Publishing is atomic. A reindex writes a new versioned .db, populates the package graph, and runs zoekt-index — only once all of that succeeds does os.replace (POSIX rename(2)) flip the small current pointer. A query already reading the old file keeps working; there is no downtime window, and a failure anywhere leaves the previously published index live.
• The package graph is rebuilt, not accumulated. Each reindex clears that repo's own outgoing edges before recomputing them, so a removed dependency's edge is retracted — blastRadius always reflects each repo's last index run.

Editable source: docs/assets/jarvis-layers.dot (Graphviz). Layer-by-layer detail, the full index pipeline, and the semantic path are in docs/system-architecture.md.

Core query/search logic is ported from an internal reference implementation; the enterprise shell (FastAPI, Postgres, hosted-git auth, Cloud Build) is dropped in favor of a single stdio process reading local SQLite files.

Indexing a repo

jarvis index /path/to/your/repo            # slug defaults to the directory name
jarvis index /path/to/your/repo --slug foo # or pick one explicitly
jarvis index /path/to/your/repo --scheme MyScheme # Swift repo with an ambiguous Xcode scheme
jarvis index /path/to/your/repo --language python # force the language instead of detecting it from git-tracked files
jarvis index /path/to/your/repo --semantic-include vendor/generated # force-include a path the generated-file filter would otherwise skip
jarvis index /path/to/your/repo --search-only # skip SCIP indexing; publish only Zoekt + semantic search
jarvis index /path/to/your/repo --fallback-search-only # opt in: if the indexer fails mid-build, degrade to search-only (status `degraded`) instead of failing; the next reindex retries the full build
jarvis list
jarvis status foo
jarvis reindex foo
jarvis forget foo

status (as shown by both list and status) is usually indexed or failed, but can also be partial: the index published real symbols but no navigable positions (an indexer/converter bug) — check the stderr warning from jarvis index for details.

--semantic-include is repeatable — pass it once per path prefix to force-include several. Like --scheme and --language, once set there is no flag to clear it; change it by re-running jarvis index with the new value(s).

Language detection counts source files by extension across git-tracked files and picks the winner — one language per index:

Ties break by fixed priority (.ts → .tsx → .py → .java → .kt → .swift). .git, node_modules, .venv, __pycache__, dist, and build are skipped. Reading git rather than walking the filesystem is deliberate: a walk also counts gitignored scratch directories, which can outnumber a repo's own code and pick a language it doesn't use.

The pipeline then runs: chosen indexer → scip expt-convert → populate the package dependency graph (packages/edges tables in registry.db) → zoekt-index into ~/.jarvis/.zoekt → copy to ~/.jarvis/scip/_/<slug>/_/index-<sha>.db → atomic current pointer flip → registry update.

The scip/_/<slug>/_/ path shape reuses the vendored IndexConnectionCache's (project, repo, branch) 3-tuple layout with the outer two pinned to _ (see src/jarvis/config.py). It is not a user-facing contract — only <slug> matters when calling tools.

Swift indexing works end-to-end. It requires scip >= v0.9.0: older converters cannot read scip.proto's typed_range oneof, which is the only range encoding scip-swift emits, and silently produce an index with no navigable positions. jarvis index refuses an older scip rather than publishing one.