# frigg
[](https://crates.io/crates/frigg)
[](https://github.com/bnomei/frigg/actions/workflows/ci.yml)
[](LICENSE)
[](LICENSE)
[](https://discordapp.com/users/bnomei)
[](https://www.buymeacoffee.com/bnomei)
Frigg is a local-first, read-only MCP server built in Rust for code understanding. It scans local repositories, stores synchronized indexes in local SQLite, and gives AI agents fast, source-backed search and navigation across Rust, PHP, Blade, TypeScript / TSX, Python, Go, Kotlin / KTS, Java, Lua, Roc, and Nim, even when the relevant answer lives in another adopted repository.
All supported languages participate in text search, symbol search, structural search, document outlines, and hybrid retrieval. Blade support is source-based and bounded.
It is built for the moment when an agent needs more than `rg/fd/ast-grep`: definitions, references, implementations, callers, structural queries, document outlines, and better answers to “which files matter here?”. **Under the hood Frigg combines deterministic file manifests, Tree-sitter AST parsing, optional SCIP overlays for more precise navigation, and optional semantic retrieval.** It is not a replacement for shell tools or your IDE. It is a context engine that brings more IDE-like code intelligence into MCP.
## What To Use Frigg For
Use Frigg when the question is repository-aware and you want source-backed navigation instead of another raw repo scan.
- jumping from a broad question to real code quickly with source-backed discovery, outlines, definitions, references, implementations, and call relationships
- asking natural-language questions without giving up concrete anchors, matched paths, and navigable files
- keeping one fast local index warm across one or more adopted repositories, so agents can move across shared code, related services, or neighboring projects without rebuilding context from scratch
- getting a more IDE-like flow for agents in the terminal: discover the area, open the file, inspect symbols, and continue navigating from there
## Installation
### Cargo
Published crate:
```bash
cargo install frigg
```
Local checkout:
```bash
cargo install --path crates/cli
```
### Homebrew
```bash
brew install bnomei/frigg/frigg
```
### GitHub Releases
Download a prebuilt archive or source package from GitHub Releases, extract it, and place `frigg` on your `PATH`.
### From source
```bash
git clone https://github.com/bnomei/frigg.git
cd frigg
cargo build --release -p frigg
```
For local performance work, Frigg also ships a small Criterion harness:
```bash
just bench
just bench native_lexical_search
```
## Bundled Skill
Frigg ships a search-and-navigation skill in [skills/frigg-mcp-search-navigation](skills/frigg-mcp-search-navigation/).
Use it as the repo-backed instruction bundle for any assistant that supports local or Git-backed skills. It explains:
- when to use Frigg instead of plain shell reads or scans
- how to adopt repositories and move through search, symbol, and navigation flows
- how to treat lexical-only hybrid results, call-graph answers, and other weaker surfaces
- how to use `read_match`, structural queries, and bounded follow-up tools efficiently
## Quickstart
### 1) Prepare a repository
```bash
cd /absolute/path/to/repo
frigg init
frigg verify
```
Optional prewarm:
```bash
frigg reindex
```
When you run these commands inside the repository root, Frigg now uses the current directory as the default workspace root. If you run them from somewhere else, pass `--workspace-root` explicitly.
### 2) Start the recommended Frigg service
```bash
frigg serve
```
Keep that process running in its own terminal tab or background session. This is the Frigg service your MCP client connects to. `frigg serve` can start with zero startup roots, so you can keep one shared Frigg service running and let clients adopt repositories as needed. The usual flow is:
1. run `frigg init` / `frigg verify` inside each repository you care about
2. keep one `frigg serve` process running
3. point your MCP client at that running Frigg service
If you already know which repositories you want globally known at startup, you can still pass them explicitly:
```bash
frigg serve \
--workspace-root /absolute/path/to/repo-a \
--workspace-root /absolute/path/to/repo-b
```
`frigg serve` defaults to loopback HTTP on `127.0.0.1:37444`. Startup roots become globally known repositories immediately, but watch leases are session-driven and start only after a session adopts a repository. The MCP endpoint is:
`http://127.0.0.1:37444/mcp`
### 3) Add Frigg to your MCP client
Point your MCP client at the loopback HTTP endpoint of the running Frigg service:
`http://127.0.0.1:37444/mcp`
#### Claude Code
```bash
claude mcp add --transport http frigg http://127.0.0.1:37444/mcp
```
#### OpenCode
```bash
opencode mcp add
```
Then choose a remote MCP server and enter:
- name: `frigg`
- url: `http://127.0.0.1:37444/mcp`
#### Codex
```bash
codex mcp add frigg --url http://127.0.0.1:37444/mcp
```
#### Other JSON-configured clients
Example MCP client config for an HTTP / streamable MCP connection:
```json
{
"mcpServers": {
"frigg": {
"transport": "streamable_http",
"url": "http://127.0.0.1:37444/mcp"
}
}
}
```
The exact file name and field names vary by client, but the important part is that the client connects to the running Frigg service at that URL. In other words: this setup assumes `frigg serve` is already running in another terminal or background process. You are connecting to Frigg here, not asking the MCP client to spawn it.
## How Frigg Uses Your Workspace
For each indexed repository, Frigg creates and maintains:
- `.frigg/storage.sqlite3`: the local SQLite database for manifests, snapshot-scoped retrieval projections, search state, navigation data, semantic data, and provenance
Frigg can also read:
- your source files under the configured workspace roots
- optional `.frigg/scip/*.scip` or `.frigg/scip/*.json` artifacts for more precise definitions, references, implementations, and call navigation
Frigg does not modify your source tree during plain session adoption. `workspace_attach` by itself does not create `.frigg` state. Frigg writes `.frigg/storage.sqlite3` only when indexing/preparing/reindexing paths run.
## Showcases
The [showcases/](https://github.com/bnomei/frigg/tree/main/showcases) directory contains 52 public example catalogs for real repositories. Each JSON file records realistic questions and the kinds of paths a good Frigg answer should surface.
## Use Cases
### Standard code search and navigation
Once Frigg is running, the normal workflow is:
1. Let your agent adopt repositories session-locally with `workspace_attach`.
`workspace_attach` reports whether the session attached a fresh workspace or reused an already-adopted one, and it returns a compact precise-index summary for the selected repo. That summary now exposes `state`, `failure_tool`, `failure_class`, `failure_summary`, `recommended_action`, and `generation_action` so clients do not need to parse nested generator detail first.
2. Use `search_hybrid` as the discovery surface for broad questions, then pivot into `read_match`, `read_file`, `document_symbols`, `go_to_definition`, or `search_symbol` when you need precise anchors and deeper navigation.
3. Use `workspace_prepare` or `workspace_reindex` only when you intentionally want to initialize or refresh repository state from inside the client.
4. Use `inspect_syntax_tree` before `search_structural` whenever the tree-sitter node shape is unclear.
`read_file` and `read_match` now default to text-first output: the main MCP content block is the bounded source slice, and `structured_content` only keeps compact identity metadata such as repository, path, and effective line window. When a caller needs the older structured JSON payload with `content`, pass `presentation_mode=json`. In the extended profile, `explore(operation=zoom)` follows the same text-first default, while `explore(operation=probe|refine)` stays structured by default.
`inspect_syntax_tree` and `search_structural` accept `include_follow_up_structural=true` as an opt-in. When enabled, Frigg returns typed `follow_up_structural` suggestions that are replayable `search_structural` invocations derived from the resolved AST focus, not from the user's original query. Omitting the flag keeps the normal response shape unchanged. Phase 1 covers `inspect_syntax_tree` and `search_structural`; phase 2 extends the same contract to `document_symbols`, `find_references`, `go_to_definition`, `find_declarations`, `find_implementations`, `incoming_calls`, and `outgoing_calls`. The phase 2 surfaces require stable `path`, `line`, and `column` anchors, and they omit suggestions when no usable AST focus can be resolved. `search_hybrid` and `search_symbol` remain deferred.
`search_structural` now defaults to one row per Tree-sitter match instead of one row per capture. Use `primary_capture` when your query has helper captures but you want one specific capture to anchor the visible row, or switch to `result_mode=captures` when you want raw capture rows for debugging.
Typical prompts:
- “Where is authentication bootstrapped?”
- “Show me implementations of `ProviderInterface`.”
- “Who calls `handleWebhook`?”
- “Which files are relevant to the checkout flow?”
### 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 and graph evidence.
Once enabled, **semantic refresh participates in reindex and watch-driven updates**, so Frigg may call the configured embedding provider automatically as the workspace changes. That means semantic mode can consume provider tokens over time, not only when you run a manual reindex.
OpenAI:
```bash
export FRIGG_SEMANTIC_RUNTIME_ENABLED=true
export FRIGG_SEMANTIC_RUNTIME_PROVIDER=openai
export OPENAI_API_KEY=...
```
Google:
```bash
export FRIGG_SEMANTIC_RUNTIME_ENABLED=true
export FRIGG_SEMANTIC_RUNTIME_PROVIDER=google
export GEMINI_API_KEY=...
```
Optional model override:
```bash
export FRIGG_SEMANTIC_RUNTIME_MODEL=text-embedding-3-small
```
After enabling semantic search for an existing repository, run one reindex pass:
```bash
frigg reindex
```
### Optional SCIP artifacts (Highly Recommended)
Frigg can consume external SCIP artifacts, and if supported generator tools are installed it will **automatically detect and invoke them during workspace attach/reindex flows** for Rust, Go, TypeScript / JavaScript, Python, PHP, and Kotlin. Java source support is available too, but current JVM auto-generation is intentionally scoped to Gradle/KTS workspaces with Kotlin source files; Java/JVM and other Kotlin/JVM layouts should continue to use manual `.frigg/scip/` artifact drops.
The commands below are only needed if you want to pre-populate artifacts yourself, or if your workspace falls outside Frigg's automatic generation path. Manual artifacts should be placed under:
```text
.frigg/scip/
```
Manual artifact directory:
```bash
mkdir -p .frigg/scip
```
If you want to generate SCIP artifacts yourself, these are good starting points:
- Overview of supported indexers: [Sourcegraph indexers](https://sourcegraph.com/docs/code-search/code-navigation/references/indexers)
- Rust: [rust-analyzer](https://github.com/rust-lang/rust-analyzer)
- PHP: [scip-php](https://github.com/davidrjenni/scip-php)
- Laravel: [scip-laravel](https://github.com/bnomei/scip-laravel)
- TypeScript / JavaScript: [scip-typescript](https://github.com/sourcegraph/scip-typescript)
- Python: [scip-python](https://github.com/sourcegraph/scip-python)
- Kotlin / Gradle, Java / JVM: [scip-java](https://sourcegraph.github.io/scip-java/docs/getting-started.html)
Laravel PHP workspaces prefer repo-local `vendor/bin/scip-laravel` when `bootstrap/app.php` is present; otherwise Frigg keeps using the existing PHP `vendor/bin/scip-php` / `scip-php` lookup.
Frigg distills those artifacts into snapshot-scoped retrieval projections on the next `frigg reindex`. Server startup alone does not change retrieval state. If you do not provide SCIP data, Frigg still works with heuristic and source-backed navigation plus path and AST-derived retrieval summaries.
When generator tools are installed, `repository.health.precise_generators` and `workspace_current.repository.health.precise_generators` report their detected status and any last generation result, and Frigg writes best-effort artifacts under `.frigg/scip/`.
Frigg now disables the normal precise SCIP ingest budgets by default, so oversized monolithic artifacts are ingested without extra configuration. `--full-scip-ingest` and `FRIGG_FULL_SCIP_INGEST=true` are still accepted for explicitness.
Python generation now uses the `scip-python index` subcommand shape directly:
```bash
scip-python index --quiet --project-name <derived-name> --output .frigg/scip/python.scip
```
Optional repository-local precise config lives at `.frigg/precise.json`. Use it to disable a generator for one repo, add generator-specific extra args, or exclude paths from filtered generation workspaces and trigger calculations without compiling repo-specific path rules into Frigg itself.
Example:
```json
{
"precise": {
"disabled_generators": ["python"],
"generation_excludes": ["vendor/**", "generated/**"],
"ingest_excludes": ["**/python-tests.scip"],
"generator_extra_args": {
"python": ["--target-only", "src/app"]
}
}
}
```
Status surfaces are separated on purpose:
- `health.scip` reports raw `.scip` artifact discovery only.
- `health.precise_ingest` reports whether Frigg could actually ingest those artifacts, with coverage mode, discovered or ingested byte counts, and sampled failed artifact reasons.
- `workspace_current.precise` stays as the compact operator summary built on top of that ingest status.
`workspace_attach` and `workspace_reindex` also support `wait_for_precise=true`. By default they remain non-blocking and may return while precise generation is still running. With `wait_for_precise`, the response includes a terminal `precise_lifecycle.phase` when possible and a `last_generation` summary with artifact path details.
## Built-In Watch Mode
Frigg includes a built-in watch worker behind `frigg serve` that keeps indexed repositories fresh with changed-only refreshes.
- watchers activate only while active sessions hold watcher leases for adopted repositories
- refreshes update the same `.frigg/storage.sqlite3` state, not a separate sidecar index
- repository-scoped caches are invalidated only for the repo that changed, so follow-up reads and searches stay warm elsewhere
- if you already run an external watcher, start Frigg with `--watch-mode off` to avoid duplicate work
## Frigg Vs Shell Search
Use shell tools like [`rg`](https://github.com/BurntSushi/ripgrep) for fast literal and regex scans, [`fd`](https://github.com/sharkdp/fd) for quick file and path discovery, and [`ast-grep`](https://github.com/ast-grep/ast-grep) for standalone structural matching in normal repository work.
On macOS and Linux, if `rg` is installed, Frigg can also use it internally as an optional lexical accelerator for `search_text` and the lexical stage of `search_hybrid`. That stays inside Frigg's own candidate scope and falls back to the native scanner automatically when `rg` is missing, disabled, or fails.
Use Frigg when the question is repository-aware:
- definitions
- references
- implementations
- call relationships
- structural queries
- natural-language discovery across many files
- source-backed answers that need fewer manual file hops
Frigg works best when your agent is told to prefer Frigg for repo-aware search and navigation, and plain shell tools for quick text, path, or one-off structural tasks.
## MCP Tools
Frigg exposes the `extended` MCP tool surface by default. Set `FRIGG_MCP_TOOL_SURFACE_PROFILE=core` when you need the restricted stable subset without `explore` or the deep-search tools.
### Core tools
- `list_repositories`: list globally known repositories in the runtime catalog.
- `workspace_attach`: adopt a repository into the current session by `path` or `repository_id`.
- `workspace_detach`: remove a repository adoption from the current session and potentially release a watch lease.
- `workspace_prepare`: confirm-gated workspace/index preparation for an adopted repository.
- `workspace_reindex`: confirm-gated full or changed reindex for an adopted repository.
- `workspace_current`: inspect session-local repository adoption, defaults, compact precise status, health, and runtime status.
- `read_file`: read a file safely inside an adopted repository. Defaults to text-first output; use `presentation_mode=json` for the structured compatibility payload.
- `read_match`: reopen a prior search or navigation hit by `result_handle` plus `match_id`. Defaults to text-first output; use `presentation_mode=json` for the structured compatibility payload.
- `search_text`: run literal or regex text search across repository files.
- `search_hybrid`: broad natural-language search that blends lexical, graph, witness, and optional semantic evidence.
- `search_symbol`: search for symbols such as functions, classes, methods, traits, or modules.
- `find_references`: find references to a symbol or a source location.
- `go_to_definition`: jump to a symbol definition from a symbol or source location.
- `find_declarations`: find declaration sites for a symbol or source location.
- `find_implementations`: find implementing types or members for interfaces, traits, or base symbols.
- `incoming_calls`: find callers of a callable symbol.
- `outgoing_calls`: find callees from a callable symbol.
- `document_symbols`: return a hierarchical outline for a source file.
- `inspect_syntax_tree`: inspect the bounded AST stack around a source location before writing a structural query, with optional `include_follow_up_structural=true` for best-effort replayable follow-up queries.
- `search_structural`: run Tree-sitter structural queries over supported languages, grouped one row per match by default, with optional raw `result_mode=captures`, `primary_capture` anchoring, and per-match best-effort follow-up queries via `include_follow_up_structural=true`.
- Follow-up structural suggestions are opt-in across the phase 1 and phase 2 surfaces above. Phase 1 covers `inspect_syntax_tree` and `search_structural`; phase 2 covers `document_symbols`, `find_references`, `go_to_definition`, `find_declarations`, `find_implementations`, `incoming_calls`, and `outgoing_calls`. `search_hybrid` and `search_symbol` remain deferred.
### Extended profile tools
These tools are available by default in the `extended` profile. Set `FRIGG_MCP_TOOL_SURFACE_PROFILE=core` to hide them:
- `explore`: bounded follow-up exploration for a single artifact after discovery. `zoom` defaults to text-first output; `probe` and `refine` remain structured by default.
- `deep_search_run`: run a deeper multi-step search workflow.
- `deep_search_replay`: replay a prior deep-search trace.
- `deep_search_compose_citations`: build citation payloads from deep-search output.
## Under the Hood
Frigg keeps a **local repository model** for each adopted workspace instead of rescanning from scratch on every question. That model starts with deterministic manifests and SQLite-backed snapshot state, then layers in Tree-sitter AST parsing, symbol extraction, retrieval projections, and optional overlays such as SCIP and semantic embeddings when you enable them.
For broad discovery, Frigg does not just sort raw text hits. `search_hybrid` turns the query into intent, collects evidence from lexical matches, path and surface witnesses, graph facts, and optional semantic recall, then runs a rule-driven reranker and post-selection pass that tries to keep the useful files visible: runtime code, entrypoints, config, tests, build surfaces, and nearby companions. That is the internal “DSL and reranker” story in plain language: query facts come in, scoring rules fire, and the final pass repairs or preserves good pivots so obvious source files are less likely to lose to generic noise.
The built-in watch runtime keeps that model fresh incrementally. Frigg tracks changed paths, refreshes the affected repository state, and invalidates only the repository-scoped caches that need to move.
## 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. In serving mode these roots become the global known-repository catalog. |
| `--max-file-bytes` / `FRIGG_MAX_FILE_BYTES` | `2097152` | Maximum file size Frigg will read. |
| `--full-scip-ingest` / `FRIGG_FULL_SCIP_INGEST` | `true` | Disable precise SCIP ingest budgets. This is the default. |
| `--watch-mode` / `FRIGG_WATCH_MODE` | stdio `off`, HTTP `auto` | Controls the built-in watch worker: `auto`, `on`, or `off`. |
| `--watch-debounce-ms` / `FRIGG_WATCH_DEBOUNCE_MS` | `2000` | Debounce delay before a watch-triggered refresh starts. |
| `--watch-retry-ms` / `FRIGG_WATCH_RETRY_MS` | `5000` | Retry delay after a failed watch refresh. |
| `--mcp-http-port` | unset | Enables HTTP transport on the given port. |
| `--mcp-http-host` | unset | 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 | Auth token for HTTP mode. Required for non-loopback HTTP. |
| `FRIGG_MCP_TOOL_SURFACE_PROFILE` | `extended` | MCP tool surface profile: `extended` by default, or `core` to restrict the public surface to the stable subset. |
| `FRIGG_SEMANTIC_RUNTIME_ENABLED` | `false` | Enables optional semantic retrieval. |
| `FRIGG_SEMANTIC_RUNTIME_PROVIDER` | unset | Semantic provider: `openai` or `google`. |
| `FRIGG_SEMANTIC_RUNTIME_MODEL` | provider default | Optional embedding model override. |
| `FRIGG_SEMANTIC_RUNTIME_STRICT_MODE` | `false` | Tightens query-time semantic failure behavior. |
Provider defaults:
- `openai` -> `text-embedding-3-small`
- `google` -> `gemini-embedding-001`
## Safety And Boundaries
- Frigg does not modify source files. Workspace/index maintenance tools (`workspace_prepare`, `workspace_reindex`) are confirm-gated and operate on Frigg state.
- Frigg only reads inside configured workspace roots.
- Frigg keeps its primary state locally in SQLite.
- Optional semantic search may call an external embedding provider if you enable it.
- External SCIP artifacts improve precision when available, but they are optional.
Session adoption and watcher leases are runtime/session state. `workspace_current.repositories` is session-local, while `list_repositories` is the global known-repository catalog. For repo-aware tools with omitted `repository_id`, Frigg scopes to the session default first, then the remaining adopted repositories.
Frigg has been tested against larger real-world repositories across its supported language set, but the product boundary stays intentionally narrow: local code evidence over MCP, not a full IDE or framework runtime.