Getting Started

This page walks you through installing Merlin, building the internal plugins, configuring a provider, and running your first task.

Prerequisites

Requirement	Why
Rust 1.75+ stable	Build the workspace
`fledge` on `PATH`	Required runtime. Merlin shells out to fledge for plugin invocation, lanes, and spec-check
One LLM API key	`OPENROUTER_API_KEY` (easiest, one key gets 5 providers), `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or others
`git`	Used by the `git-*` plugins

Install

Merlin is a CorvidLabs internal project — the source isn’t publicly available. If you have access, clone the repository and build the workspace:

cd merlin
cargo build --workspace --release

Initialize Merlin in this project (builds plugin binaries, symlinks them into the fledge data directory, and registers them with fledge):

cargo run -p merlin-cli -- init

What this does

Builds all plugins under plugins/ in release mode.

Copies each plugin’s plugin.toml to the fledge data dir (~/Library/Application Support/fledge/plugins/<name>/ on macOS, ~/.local/share/fledge/plugins/<name>/ on Linux).

Symlinks plugin binaries into the fledge bin shim directory.

Appends new plugins to plugins.toml registry.

Best-effort starts localnet and generates AlgoChat keys (skip-tolerant).

Configure a Provider

Set an API key. Pick one of three methods:

# Option 1: OS keychain (recommended, works globally, no .env needed)
merlin keys set OPENROUTER_API_KEY

# Option 2: Environment variable
export OPENROUTER_API_KEY="sk-or-..."

# Option 3: .env file (project-local)
cp .env.example .env
# Edit .env and paste your key

Confirm Merlin sees it:

merlin keys           # shows all keys and their source
merlin health         # tests all configured providers

See Configuration for the full [merlin] config block, including how to register multiple providers and switch between them at runtime.

Run Your First Task

One-shot mode. Pass the task on the command line:

cargo run -p merlin-cli -- "list rust files under crates/"

You’ll see the agent transition through Planning → Executing → Verifying → Reporting → Idle, with streaming text deltas, tool calls, and a final summary listing any files changed.

Interactive REPL

Drop into the REPL by running with no task:

cargo run -p merlin-cli

Inside the REPL:

> /help
  /model [name]     -- List or switch provider/model
  /memory <query>   -- Search memory
  /contacts         -- List AlgoChat contacts
  /status           -- Show agent status
  /verify           -- Run verify lane
  /quit             -- Exit

> add docstrings to crates/merlin-core/src/agent.rs
Planning...
  ...

See Slash Commands for the full reference.

Cancellation

Press Ctrl+C mid-task. The in-flight LLM HTTP request is dropped, any files already modified are listed, and the agent returns to Idle.

What’s Next

Configuration: providers, retries, memory TTL, AlgoChat networks.
Spec-aware Planning: how Merlin selects and injects relevant specs.
Plugin Authoring: write your own fledge-v1 plugin.