Skip to content

Documentation map

Switch models, not context. milk routes each prompt between a cheap primary agent and a deep escalation agent — keeping the whole conversation in sync across both — and layers tools, MCP, multi-agent workflows, persistent memory, and an eval harness on top.

This page is the map of the documentation. Everything published lives in one of four sections below; each section has its own overview page saying what's in it and in what order to read it. If you're new, just follow the sections top to bottom.

Start here

  • Getting started — install milk, wire up your first primary + escalation pair, and complete your first routed turn. The fastest path to a working setup; no specific backend required.

Guides — task-oriented, day to day

Read in order the first time, jump straight to a page afterwards.

  • Providers & configuration — every agent backend (local inference servers, Bedrock, Claude CLI, aider, smolagents, Bearer APIs), auth transports, context/memory tuning.
  • Routing, sessions & workflows — how a prompt gets routed, session states, sticky escalation, the native /workflow engine.
  • Tooling, MCP & tool-agents — built-in tools, agent-as-tool, MCP servers (including OAuth), attachments, machine-readable output.
  • Operations — running milk day to day: memory, observability, loop detection, task tracking, remote oversight.

Reference

  • Evaluation (milk eval) — run scenario prompts against real agent backends, score them with an LLM judge, compare reports.
  • ACP integration — embedding milk in an editor or any client via milk serve --acp (what's implemented today).
  • Specification & CLI reference — the architecture of the whole system and the full CLI surface.

Architecture & decisions

Where do I find…?

I want to… Go to
Install milk and run a first turn Getting started
Add or configure an agent backend Providers & configuration
Understand routing / fix escalation behavior Routing, sessions & workflows
Connect MCP servers or use tools Tooling, MCP & tool-agents
Set up memory, observability, remote oversight Operations
Consume milk's machine-readable output (--output-format stream-json) Tooling & MCP — machine-readable output
Embed milk in an editor/client over ACP ACP integration
Benchmark agents with milk eval Evaluation
Look up a CLI flag or config field Specification & CLI reference
Understand a design decision ADRs

For contributors

Design notes, implementation plans, and analyses live in the source tree under docs/internal/ (deliberately not published on this site). Branch conventions and commit style are in docs/internal/branching-strategy.md.