Frigg

Frigg is a local-first MCP server for code understanding. It is the default agent surface for code discovery, navigation, exact code search, and bounded source reads across Rust, PHP, Blade, TypeScript / TSX, Python, Go, Kotlin / KTS, Java, Lua, Roc, and Nim.

Frigg builds a synchronized SQLite repository model for broad discovery, exact source windows, document outlines, symbols, definitions, references, implementations, callers, structural queries, optional semantic recall, and optional SCIP-backed precision.

During normal indexing, Frigg is source read-only. It stores its own state under .frigg/, but it does not edit project source files as part of ordinary search and navigation.

What You Get

• one local MCP service that can serve multiple adopted repositories
• local SQLite state for manifests, search projections, semantic rows, navigation data, and provenance
• Tree-sitter-backed symbol, document outline, and structural search for supported languages
• hybrid discovery that blends lexical matches, path and surface witnesses, graph evidence, optional semantic recall, and code-aware reranking
• bounded read_file and read_match output so agents inspect smaller source slices instead of repeatedly reading whole files
• optional SCIP artifact ingestion and best-effort generation for precise definitions, references, implementations, and call navigation
• built-in watch mode behind frigg serve for changed-only refreshes while sessions are active

Quickstart

Install Frigg with the Unix installer on macOS or GNU/glibc Linux:

curl --fail --location --proto '=https' --tlsv1.2 --silent --show-error \
  https://raw.githubusercontent.com/bnomei/frigg/main/scripts/install.sh \
  | FRIGG_VERSION=0.5.0 sh

FRIGG_VERSION accepts 0.5.0 or v0.5.0. When it is unset, the installer resolves the latest GitHub Release. The installer downloads the matching frigg-v<VERSION>-<TARGET>.tar.gz archive, verifies its .sha256, and installs only the frigg binary.

Alternative installs:

brew install bnomei/frigg/frigg
cargo install frigg

From a local checkout:

git clone https://github.com/bnomei/frigg.git
cd frigg
cargo build --release -p frigg

Prepare a repository from the repository root:

frigg init
frigg verify
frigg reindex
frigg serve

When commands run inside a repository root, Frigg uses the current directory as the workspace root. From another directory, pass --workspace-root /absolute/path/to/repo.

MCP Service

frigg serve listens on loopback HTTP by default:

http://127.0.0.1:37444/mcp

The service can start with zero startup roots, so clients can adopt repositories as needed. To make repositories globally known at startup, pass them explicitly:

frigg serve \
  --workspace-root /absolute/path/to/repo-a \
  --workspace-root /absolute/path/to/repo-b

Connect Claude Code:

claude mcp add --transport http frigg http://127.0.0.1:37444/mcp

Connect Codex:

codex mcp add frigg --url http://127.0.0.1:37444/mcp

Other JSON-configured clients:

{
  "mcpServers": {
    "frigg": {
      "transport": "streamable_http",
      "url": "http://127.0.0.1:37444/mcp"
    }
  }
}

The exact config file and field names vary by client. The important part is that the client connects to the running Frigg service. The MCP client is not expected to spawn frigg serve.

Agent Workflow

The normal first-use loop is:

1. Call workspace_attach for the repository.
2. Check workspace_current when you need freshness, precise-generator, or runtime status.
3. Start broad questions with search_hybrid.
4. Open source with read_match when a search result returned result_handle and match_id.
5. Pivot to search_symbol, document_symbols, go_to_definition, find_references, find_implementations, incoming_calls, outgoing_calls, or search_structural when you need exact navigation.

Use Frigg for repository-aware workflows:

• broad natural-language discovery across many files
• canonical repository-relative paths and bounded source reads
• definitions, declarations, references, implementations, callers, and callees
• document outlines and Tree-sitter structural queries
• source-backed answers that need fewer manual file hops
• multi-repository context from one shared service

Use shell tools for non-code files, git and filesystem inspection, and trivial one-off checks where a direct command is faster and does not replace code discovery or bounded source reads.

Workspace State

For each indexed repository, Frigg creates and maintains:

• .frigg/storage.sqlite3: local SQLite state for manifests, snapshot-scoped retrieval projections, search state, navigation data, semantic data, and provenance

Frigg can also read:

• source files under configured workspace roots
• optional .frigg/scip/*.scip or .frigg/scip/*.json artifacts for precise navigation
• optional .frigg/precise.json generator configuration

By default, workspace_attach uses index_mode=ensure: it adopts the repository, refreshes stale or missing lexical and semantic state when possible, waits up to 30 seconds, and reports index_lifecycle.

Attach is not side-effect free. It can create or update .frigg/storage.sqlite3, record session/provenance state, report repository health, and schedule precise-generator discovery or generation when a generator applies.

Optional Semantic Search

Semantic retrieval is off by default. When enabled, it improves recall for natural-language queries, but Frigg still grounds answers in local lexical, path, graph, symbol, and structural evidence.

OpenAI:

export FRIGG_SEMANTIC_RUNTIME_ENABLED=true
export FRIGG_SEMANTIC_RUNTIME_PROVIDER=openai
export OPENAI_API_KEY=<API_KEY>

Google:

export FRIGG_SEMANTIC_RUNTIME_ENABLED=true
export FRIGG_SEMANTIC_RUNTIME_PROVIDER=google
export GEMINI_API_KEY=<API_KEY>

Local:

export FRIGG_SEMANTIC_RUNTIME_ENABLED=true
export FRIGG_SEMANTIC_RUNTIME_PROVIDER=local

The local provider runs embeddings on this machine with the default model all-MiniLM-L6-v2. Zero-cloud semantic behavior applies only when provider=local; OpenAI and Google semantic providers call their external embedding APIs.

Prepare local model artifacts explicitly before serving or semantic reindexing:

frigg prepare-semantic-model

Optional SCIP Artifacts

Frigg can consume external SCIP artifacts for more precise definitions, references, implementations, and call navigation. It can also automatically detect and invoke supported generator tools during workspace_attach and MCP workspace_reindex flows for Rust, Go, TypeScript / JavaScript, Python, PHP, and Kotlin.

Manual artifacts belong in:

.frigg/scip/

Optional repository-local precise config lives at .frigg/precise.json:

{
  "precise": {
    "disabled_generators": ["python"],
    "generation_excludes": ["vendor/**", "generated/**"],
    "ingest_excludes": ["**/python-tests.scip"],
    "generator_extra_args": {
      "python": ["--target-only", "src/app"]
    }
  }
}

Without SCIP data, Frigg still works with heuristic and source-backed navigation plus path and AST-derived retrieval summaries.

Configuration

Precedence is CLI flag > env var > default.

Flag / Env	Default	Meaning
--workspace-root	utility commands default to current directory; serving mode can start empty	Limits what Frigg can read and index. Repeatable.
--max-file-bytes / FRIGG_MAX_FILE_BYTES	2097152	Maximum file size Frigg will read.
--watch-mode / FRIGG_WATCH_MODE	stdio off, HTTP auto	Controls the built-in watch worker.
--mcp-http-port	37444 for frigg serve, unset otherwise	Enables HTTP transport on the given port.
--mcp-http-host	127.0.0.1 when HTTP is enabled	Host bind address for HTTP transport.
--allow-remote-http	false	Required for non-loopback HTTP serving.
--mcp-http-auth-token / FRIGG_MCP_HTTP_AUTH_TOKEN	unset	Bearer token for HTTP mode. Required for non-loopback HTTP.
--lexical-backend / FRIGG_LEXICAL_BACKEND	auto	Lexical backend: auto, native, or ripgrep.
FRIGG_MCP_TOOL_SURFACE_PROFILE	extended	MCP tool surface profile: extended or core.
--semantic-runtime-enabled / FRIGG_SEMANTIC_RUNTIME_ENABLED	false	Enables optional semantic retrieval.
--semantic-runtime-provider / FRIGG_SEMANTIC_RUNTIME_PROVIDER	unset	Semantic provider: openai, google, or local.
--semantic-runtime-model / FRIGG_SEMANTIC_RUNTIME_MODEL	provider default	Optional embedding model override.
--semantic-runtime-strict-mode / FRIGG_SEMANTIC_RUNTIME_STRICT_MODE	false	Converts semantic provider failures into user-visible errors instead of graceful fallback.

Safety And Boundaries

• Frigg indexes source files only inside configured workspace roots.
• Frigg keeps primary state locally in SQLite.
• Frigg avoids editing source files during normal indexing.
• Optional semantic search may call an external embedding provider if you enable it.
• Optional precise generators may write .frigg/scip/ artifacts, execute repo-local or PATH-discovered tools, or apply generator-specific compatibility patches.
• Workspace and index maintenance tools such as workspace_prepare and workspace_reindex are confirm-gated and operate on Frigg state.
• Session adoption and watcher leases are runtime/session state.

Frigg’s product boundary is intentionally narrow: local code evidence over MCP, not a full IDE, hosted code intelligence platform, or framework runtime.

Source Anchors

• ../frigg/README.md
• ../frigg/docs/operator-runbook.md
• ../frigg/skills/frigg-mcp-search-navigation/