jarvis: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

Personal, local-first code intelligence MCP server. SCIP-backed navigation (go-to-definition, find-references, call/type hierarchy, document symbols) + Zoekt-backed lexical search, exposed as MCP tools over stdio — no HTTP server, no auth, no network.

Commands

uv sync                              # install deps
uv sync --extra watch                # + watchdog, needed for `jarvis watch`
uv sync --extra semantic             # + lancedb/sentence-transformers/tree-sitter, needed for semanticSearch

uv run pytest                        # all tests
uv run pytest -m "not integration"   # unit only — no external binaries required
uv run pytest -m integration         # integration only — runs real scip-python/scip/zoekt-git-index
uv run pytest tests/test_query.py::test_go_to_definition_returns_location   # single test

uv run jarvis index /path/to/repo [--slug name] [--scheme name] [--language name] [--semantic-include path]
uv run jarvis list
uv run jarvis status <slug>
uv run jarvis reindex <slug>
uv run jarvis forget <slug>
uv run jarvis watch /path/to/repo [--debounce 5] [--scheme name] [--language name] [--semantic-include path]   # foreground, not a daemon

uv run jarvis-server              # MCP stdio entry point
claude mcp add jarvis --scope user -- uv --directory /path/to/jarvis run jarvis-server

Required on PATH for anything beyond unit tests: one language indexer per repo (scip-typescript / scip-python / scip-java / scip-swift), scip (for scip expt-convert), and zoekt-git-index / zoekt-webserver. Integration tests are gated on these and skip cleanly if absent.

Architecture

Three engines sit behind the MCP server, each backed by its own storage:

• Query (query.py + index_reader.py + scip_decoder.py) — SCIP nav ops via raw SQL against the scip expt-convert SQLite schema (documents/chunks/global_symbols/mentions). scip_decoder.py is the only module importing scip_pb2/zstandard — an isolation seam so future SCIP proto version bumps localize to one file. symbols.py is the same kind of isolation seam for the SCIP symbol string grammar: it owns parsing (parse_symbol()) and bare-name resolution (resolve(), a two-rung ladder of exact match then dotted-suffix match) end to end, so goToDefinition/findReferences/callHierarchy/typeHierarchy accept a bare or qualified name instead of requiring the full, version-pinned SCIP string. Caveat: scip-swift emits clang USR strings (e.g. c:@CM@UIKit@@objc(cs)UIView(im)centerXAnchor) as its symbol names, so bare-name resolution has no practical value in Swift repos — it works for Python/TypeScript/Java/Kotlin.
• Search (search.py) — searchCode via a real httpx client to zoekt-webserver. ZoektLifecycle lazily spawns the webserver on first call (pidfile-tracked, killed at exit); never spawn it elsewhere. base_url_if_running() is the non-spawning variant, used by getIndexStatus's coverage check so a status call never starts a server as a side effect.
• Graph (graph.py + registry.py) — package dependency graph (packages/edges in registry.db) driving blastRadius (2-hop BFS). populate_graph_for_repo() clears a repo's outgoing edges before recomputing — rebuild-not-accumulate, so retracted dependencies don't linger.
• Semantic (chunker.py + embeddings.py + semantic.py + symbol_search.py) — tree-sitter chunking → sentence-transformers embeddings → a per-repo LanceDB table under ~/.jarvis/lancedb/. semanticSearch fuses vector hits with Zoekt hits and SCIP symbol-definition matches (via symbol_search.py, reusing symbols.py's name-map machinery) via reciprocal rank fusion. Gated behind the optional semantic extra; the indexing stage is non-fatal in jarvis index (a failure there never blocks the SCIP/Zoekt publish). A LanceDB table only ever holds vectors from one model+revision — the model-identity rule.