Introduction

Spec-driven AI agent runner built on fledge.

Merlin is a Rust-based AI agent runner. You give it specs, it writes code that matches them, then it verifies the result before reporting done.

Why Merlin

Most AI coding tools are configured to try harder. Merlin is configured to check itself:

  • Spec-aware: loads relevant module specs at task start and injects their Invariants, Public API, and Error Cases into the system prompt as hard constraints.
  • Fledge-native: fledge lanes run verify runs as a mandatory gate before any task is reported complete. Failures retry up to a configured limit, with the verifier’s output fed back to the LLM for repair.
  • Provider-agnostic: 31 providers pre-configured (Anthropic, OpenAI, OpenRouter, Groq, Together, Ollama Cloud). Swap mid-session with /model <name>.
  • Plugin-driven: every capability is a fledge plugin. Merlin ships a broad set of bundled plugins (core: files, search, shell, git, spec-sync, snapshots, web; media: vision, voice; delegation: merlin-subagent; bridges: discord, telegram) and picks up external plugins automatically.
  • Convention-Aware: Prepend project-specific rules via .gemini/GEMINI.md to ensure the agent follows your local style.
  • Cancellable: Ctrl+C returns control immediately, including dropping the in-flight LLM HTTP request, with a partial summary.

The Stack

LayerToolRole
Specificationspec-syncDefines what correct code looks like
WorkflowfledgeDefines how to build, verify, and ship
AgentmerlinWrites code within those constraints

Quick Tour

$ merlin "add error handling to the parser"

Planning...
  · loaded constraints from spec: parser
  · 12 memories recalled
Executing...
  ▸ files-read {"path":"src/parser.rs"}
  ▸ files-edit {"path":"src/parser.rs", ...}
  ▸ files-edit {"path":"src/main.rs", ...}
  ✓ files-edit
Verifying...
  · fledge lanes run verify
  ✓ Verification passed
✓ Done. (2 files changed: src/main.rs, src/parser.rs)
  · Added Result returns and three error variants. Updated call sites.

Where to Next