Configuration

Overview

Guardian offers configuration options to tailor the application to your workflow. This guide covers all configurable settings.

Accessing Settings

Click the gear icon (⚙️) in the header to open the Settings modal.

Provider Configuration

Selecting a Provider

Choose your AI provider from the dropdown:

Provider	API Key Required	Local Option
Ollama	No (Local) / Yes (Cloud)	Yes (http://localhost:11434)
OpenAI	Yes	No
Anthropic (Claude)	Yes	No
Google Gemini	Yes	No
GitHub Models	Yes	No

Model Selection

After selecting a provider, choose a model. Available models are fetched automatically from the provider.

Choosing a model:

Prefer a faster model for day-to-day monitoring and quick Guru questions.
Use a deeper model when you need higher-quality architectural analysis.
For Ollama, pick a model you already pulled locally (for example: ollama pull <model>).

API Key Management

For providers requiring API keys:

Obtain your API key from the provider dashboard
Enter the key in the "API Key" field
Click Save to store securely
Click Clear to remove stored key

Security: API keys are stored in platform-native secure storage (Keychain, Credential Manager, or Secret Service).

Theme Settings

Toggle between Light and Dark themes:

Click the theme toggle in the Settings modal
Or use the theme toggle in the header

Scan Scope

Scan Scope controls which files Guardian includes during monitoring (cost vs coverage).

Open Settings > General > Scan Scope and choose:

Profile	What you get
Source (default)	Code-focused monitoring. Skips docs/tests/scripts/lockfiles by default.
Extended	Adds infra and security surfaces (Docker/CI/workflows/config/shell/locks). Still skips docs/tests by default.
Full	Most text files (including docs/tests/scripts/workflows). Highest coverage and highest cost.

Changes apply the next time monitoring starts (restart monitoring to apply).

Web Search (Tavily)

Enable AI-powered web search for Guru:

Get an API key from tavily.com
Enter the key in the "Tavily API Key" field
Guru can now search the web for context

Search Depth

In Settings > Web Search, you can control how deep the search should go:

Auto: Picks a sensible depth based on the query.
Basic: Good default for most questions.
Advanced: Higher recall (slower, more expensive).
Fast / Ultra-fast: Faster, smaller result sets.

URL Extract

If your question includes a URL, Guru will prefer URL extraction to pull the most relevant chunks from that page (instead of doing a broad search first).

Per-Message Overrides

You can force web search for a single question by adding:

/web prefix (for example: /web explain the latest Node.js LTS changes)
@web tag anywhere in the question

This works even if Web Search is off, but it still requires a Tavily key.

Best Practices

Keep web queries short and specific (Guardian truncates Tavily queries to ~400 characters).
Use site:example.com when you already know the best source domain.
Prefer a URL + a clear instruction when you want one page summarized (Extract is tighter than broad Search).

Updates

Check for Updates

Guardian checks for updates automatically. You can also:

Click Check Now in Settings
View current version information

Update Feed URL

Advanced users can configure a custom update feed URL for self-hosted update servers via the GUARDIAN_UPDATE_FEED_URL environment variable.

Configuration Storage

Guardian stores configuration in platform-specific locations:

Platform	Location
macOS	`~/Library/Application Support/Guardian/`

guardian.lock

The guardian.lock file ensures reproducible scans across different machines and time periods.

What It Does

Pins rules version (hash)
Records workspace ID
Tracks Guardian version
Ensures scan consistency

Lock File Location

your-project/
├── guardian.lock          # Auto-generated
├── .guardian/
│   ├── AGENT_INSTRUCTIONS.md
│   ├── baseline.json
│   ├── critiques.json
│   ├── critiques.md
│   ├── history.jsonl
│   ├── agent_queue.jsonl
│   ├── chat.md
│   ├── chat_queue.md
│   ├── STALL              # Only while stalled
│   └── undo/              # Only after applying a fix
└── .agent/rules/

Lock Schema

{
  "schema_version": 1,
  "created_at": "2026-02-10T12:00:00Z",
  "updated_at": "2026-02-10T12:00:00Z",
  "guardian_version": "1.2.3",
  "workspace_id": "sha256-hash",
  "rules_hash": "abc123...",
  "rules_source": ".agent/rules"
}

CLI Enforcement Modes

When using guardian-cli, you can enforce lock compliance:

# Warn mode (default): Warn on mismatch but continue
 guardian-cli scan --root . --lock-mode warn

# Strict mode: Fail scan on any mismatch
guardian-cli scan --root . --lock-mode strict

# Off mode: Ignore lock file
guardian-cli scan --root . --lock-mode off

Migration

If upgrading from older releases (before guardian.lock existed):

Open your project in Guardian Desktop
Run a scan (lock file auto-created)
Recreate baseline via UI
See Migration Guide for details

Semantic Index Settings

Configure semantic search behavior:

Embedding Provider

Choose how code embeddings are generated:

# Environment Variables
GUARDIAN_EMBED_MODE=auto            # "auto", "openai", "ollama", "local"
GUARDIAN_EMBED_MODEL=text-embedding-3-small
GUARDIAN_EMBED_MODEL_OLLAMA=nomic-embed-text
GUARDIAN_OFFLINE=1                  # Forces local hash mode

Auto mode behavior

If a valid OpenAI key exists, auto mode prefers OpenAI.
If no OpenAI key exists, auto mode skips OpenAI entirely and starts with Ollama, then local hash fallback.

Mode	Quality	Latency	Offline
OpenAI	⭐⭐⭐	~500ms	❌
Ollama	⭐⭐	~200ms	✅
Local Hash	⭐	~10ms	✅

Similarity Thresholds

Guardian filters semantic matches at a minimum similarity score of 0.72.

Best Practices

Backup Configuration: Export a PDF snapshot before major changes
Secure API Keys: Never share or commit API keys
Test After Changes: Verify Guru works after changing providers
Keep Updated: Enable automatic update checks
Commit guardian.lock: Include in version control for team consistency
Use Strict Mode in CI: Enforce lock compliance in CI/CD pipelines