Configuration reference

Frigg has no general runtime configuration file. Process behavior comes from CLI flags, environment variables, and source defaults. The repository-local .frigg/precise.json file configures only optional precise generation and ingest.

Precedence

When a setting has both a flag and environment variable, Frigg resolves it in this order:

CLI flag
environment variable
source default

HTTP host, port, and remote permission are flag-only. Provider credentials and the environment-only settings below have no CLI peer.

Flag and environment pairs

Flag	Environment	Default
`--max-file-bytes`	`FRIGG_MAX_FILE_BYTES`	`2097152`
`--full-scip-ingest`	`FRIGG_FULL_SCIP_INGEST`	`true`
`--mcp-http-auth-token`	`FRIGG_MCP_HTTP_AUTH_TOKEN`	unset
`--semantic-runtime-enabled`	`FRIGG_SEMANTIC_RUNTIME_ENABLED`	`false`
`--semantic-runtime-provider`	`FRIGG_SEMANTIC_RUNTIME_PROVIDER`	`local` when semantic runtime is enabled
`--semantic-runtime-model`	`FRIGG_SEMANTIC_RUNTIME_MODEL`	provider default
`--semantic-runtime-strict-mode`	`FRIGG_SEMANTIC_RUNTIME_STRICT_MODE`	`false`
`--semantic-runtime-openai-compat-endpoint`	`FRIGG_SEMANTIC_RUNTIME_OPENAI_COMPAT_ENDPOINT`	required for `openai_compat`
`--watch-mode`	`FRIGG_WATCH_MODE`	transport-aware
`--watch-debounce-ms`	`FRIGG_WATCH_DEBOUNCE_MS`	`2000`
`--watch-retry-ms`	`FRIGG_WATCH_RETRY_MS`	`5000`
`--watch-manifest-fast-concurrency`	`FRIGG_WATCH_MANIFEST_FAST_CONCURRENCY`	`1`
`--watch-semantic-followup-concurrency`	`FRIGG_WATCH_SEMANTIC_FOLLOWUP_CONCURRENCY`	`1`
`--lexical-backend`	`FRIGG_LEXICAL_BACKEND`	`auto`
`--ripgrep-executable`	`FRIGG_RIPGREP_EXECUTABLE`	PATH lookup

See CLI reference for accepted values and validation rules.

Environment-only settings

Environment variable	Default	Contract
`FRIGG_MCP_TOOL_SURFACE_PROFILE`	`extended`	Select `core` or `extended`. Without the compile-time `playbook` feature, both expose the same product tools. Unknown values fall back to `extended`.
`FRIGG_SQLITE_BUSY_TIMEOUT_MS`	`30000`	Positive SQLite writer wait in milliseconds. Zero and invalid values are rejected.
`FRIGG_CONTEXT_EFFICIENCY_LOG`	false	Truthy values append local context-efficiency events to `.frigg/context.jsonl`. Empty, `0`, `false`, `no`, and `off` disable it.
`FRIGG_ROUTING_STATS`	false	`1`, `true`, `yes`, or `on` records process-local routing counters. Set before `frigg serve`.
`FRIGG_SEMANTIC_MODEL_CACHE`	platform cache	Override the root for local semantic model artifacts.
`OPENAI_API_KEY`	unset	Credential for `provider=openai`; fallback bearer credential for `openai_compat`.
`FRIGG_OPENAI_COMPAT_API_KEY`	unset	Preferred bearer credential for `provider=openai_compat`.
`GEMINI_API_KEY`	unset	Credential for `provider=google`.
`FRIGG_SKILL_SOURCE`	workspace skill tree	Source directory, or `SKILL.md`, used by `frigg adopt --skill-provider`.
`FRIGG_STARTUP_TRACE`	absent	Emit early startup trace lines when the variable is present. Presence enables it even if the value is `false`.
`HF_ENDPOINT`	Hugging Face default	Override the download endpoint used while preparing the local model.

HF_HOME is not a supported Frigg cache override. If it is set and local model loading reports a cache mismatch, unset it so FRIGG_SEMANTIC_MODEL_CACHE or Frigg’s platform default controls artifact placement.

Default local model cache roots are:

Platform	Path
macOS	`~/Library/Caches/frigg/models`
Linux with `XDG_CACHE_HOME`	`$XDG_CACHE_HOME/frigg/models`
Linux without `XDG_CACHE_HOME`	`~/.cache/frigg/models`
Windows	`%LOCALAPPDATA%\frigg\models`

Local state paths

Path	Meaning
`.frigg/storage.sqlite3`	Local SQLite repository model, manifests, semantic rows, vectors, and projections.
`.frigg/scip/`	Optional generated or supplied SCIP artifacts.
`.frigg/precise.json`	Optional precise-generator and ingest configuration.
`.frigg/context.jsonl`	Opt-in context-efficiency event log.
`.frigg/tmp/precise-generation/`	Temporary filtered workspaces used by precise generators.

Treat .frigg/ as regenerable runtime state rather than source. It may contain source-derived content, so do not publish or share it as an unreviewed artifact.

Semantic providers

Semantic retrieval is disabled by default. Enabling it without a provider selects local.

Provider	Default model	Required configuration
`local`	`all-MiniLM-L6-v2`	No credential; prepares model artifacts in the local cache.
`openai`	`text-embedding-3-small`	`OPENAI_API_KEY`
`openai_compat`	`text-embedding-3-small` protocol default	Full embeddings POST URL plus `FRIGG_OPENAI_COMPAT_API_KEY` or `OPENAI_API_KEY`
`google`	`gemini-embedding-001`	`GEMINI_API_KEY`

Example for an OpenAI-compatible local or gateway endpoint:

export FRIGG_SEMANTIC_RUNTIME_ENABLED=true
export FRIGG_SEMANTIC_RUNTIME_PROVIDER=openai_compat
export FRIGG_SEMANTIC_RUNTIME_OPENAI_COMPAT_ENDPOINT=http://127.0.0.1:1234/v1/embeddings
export FRIGG_OPENAI_COMPAT_API_KEY=<TOKEN_OR_DUMMY>
export FRIGG_SEMANTIC_RUNTIME_MODEL=<BACKEND_MODEL_ID>
frigg index

The endpoint must be an absolute HTTP(S) URL. Set the actual backend model ID when it differs from the protocol default. After changing provider or model, run a full frigg index.

HTTP serving

Flag-only serving controls:

Flag	Default	Contract
`--mcp-http-port`	`37444` for `frigg serve`	HTTP port. Supplying it with no subcommand also selects HTTP.
`--mcp-http-host`	`127.0.0.1`	Bind address.
`--allow-remote-http`	false	Required for a non-loopback host.

The token may come from --mcp-http-auth-token or FRIGG_MCP_HTTP_AUTH_TOKEN.

FRIGG_MCP_HTTP_AUTH_TOKEN='replace-me' \
frigg serve --mcp-http-host 0.0.0.0 --allow-remote-http

Loopback may run without a token. Non-loopback requires both remote permission and a nonblank token. Authentication applies to /mcp and /stats/routing.

Watch settings

Watch refreshes update .frigg/storage.sqlite3; there is no sidecar watch index.

Transport and setting	Resolved behavior
Stdio with no explicit watch flag	`off`
Stdio with explicit `auto` or `on`	enabled
Loopback HTTP with `auto`	enabled while active sessions hold watcher leases
Remote HTTP with `auto`	disabled; use `on` to opt in
Any transport with `off`	disabled

Debounce, retry, and both concurrency settings must be greater than zero.

.frigg/precise.json requires a top-level precise object:

{
  "precise": {
    "disabled_generators": ["typescript"],
    "generation_excludes": ["vendor/**", "node_modules/**"],
    "ingest_excludes": ["generated/**"],
    "generator_extra_args": {
      "rust": ["--features", "docs"]
    }
  }
}

Invalid JSON falls back to precise defaults and emits a warning. Precise generators are optional accelerators and may execute repository-local or PATH-discovered tools.

Source Anchors

../frigg/README.md
../frigg/crates/cli/src/cli_args.rs
../frigg/crates/cli/src/cli_runtime/config_resolution.rs
../frigg/crates/cli/src/settings/frigg_config.rs
../frigg/crates/cli/src/settings/semantic_runtime.rs
../frigg/crates/cli/src/settings/watch.rs
../frigg/crates/cli/src/http_runtime.rs
../frigg/crates/cli/src/storage/db_runtime.rs
../frigg/crates/cli/src/context_efficiency.rs
../frigg/crates/cli/src/mcp/routing_stats.rs
../frigg/crates/cli/src/mcp/tool_surface.rs
../frigg/crates/cli/src/embeddings/local_model.rs
../frigg/crates/cli/src/mcp/server/precise_graph.rs
../frigg/crates/cli/src/mcp/server/precise_graph/config.rs