Configuration

All Merlin configuration lives under the [merlin] section of your project’s fledge.toml. There is no separate config file.

Minimal Example

[merlin]
default_provider = "claude"
verify_before_complete = true
max_retries = 3

[merlin.providers.claude]
type = "anthropic"
api_key_env = "ANTHROPIC_API_KEY"
model = "claude-sonnet-4-6"

Local overlay — fledge.local.toml

When you want a setting different from the checked-in fledge.toml on your own machine — for example bumping max_retries or swapping default_provider for local experiments without committing the change — drop a fledge.local.toml next to it. The two files are deep-merged at load time: every field in the overlay wins, every field absent from the overlay keeps its value from the base.

fledge.local.toml is gitignored, so it doesn’t get committed or fight with teammates’ overrides.

Project Instructions — .gemini/GEMINI.md

For project-specific conventions and instructions that should apply to every agent task (e.g., “always use async/await”, “prefer anyhow for error handling”), create a .gemini/GEMINI.md file in your project root.

Merlin automatically discovers this file and prepends its content to the system prompt. This allows you to steer the agent’s behavior at the project level without needing to modify the global persona or the fledge.toml.

Diagnostic Tool — merlin doctor

Use merlin doctor to verify your environment and configuration. It performs a comprehensive check of:

• Required tools (cargo, fledge, git, etc.)
• fledge.toml validity and project root resolution
• External and internal plugin registration
• API key availability (env vars and OS keychain)
• Project-specific instructions (.gemini/GEMINI.md)

merlin doctor

Top-Level Keys

Providers

Register one or more providers under [merlin.providers.<name>]:

[merlin.providers.claude]
type = "anthropic"
api_key_env = "ANTHROPIC_API_KEY"
model = "claude-sonnet-4-6"

[merlin.providers.openai]
type = "openai"
api_key_env = "OPENAI_API_KEY"
model = "gpt-4.1-mini"

[merlin.providers.ollama]
type = "ollama"
api_key_env = "OLLAMA_API_KEY"
model = "qwen3-coder:480b"
base_url = "https://api.ollama.com"

Switch providers at the command line:

merlin --provider ollama "explain this function"

Or mid-session with the /model slash command:

> /model
  active: anthropic (claude-sonnet-4-6)
  claude (anthropic, model: claude-sonnet-4-6)
  ollama (ollama, model: qwen3-coder:480b)

> /model ollama
  ✓ Switched to ollama (model: qwen3-coder:480b)

Configured providers (default fledge.toml)

31 providers ship in the repo’s default fledge.toml — direct Anthropic

• OpenAI (12 SKUs), OpenRouter (×5 vendors with one key), Groq, Together, and 11 Ollama Cloud models. Set the matching env var in .env (or via merlin keys set <NAME>) to enable each.

Additional Provider Fields

Memory

[merlin.memory]
ephemeral_ttl_days = 7

See Memory & AlgoChat for tier semantics (ephemeral, mutable, permanent).

AlgoChat

[merlin.algochat]
network = "localnet"
auto_respond = true

Session

[merlin.session]
ttl_days = 30
enabled = true

CLI Overrides

Several config values can be overridden on the command line:

Project Discovery

Merlin walks up from the current directory looking for fledge.toml and treats the directory containing it as the project root. If no fledge.toml is found, Merlin falls back to built-in defaults (no fledge.toml required to run merlin from any directory — just set an API key env var).