Switch models, not context.

Start cheap. Go deep when you need it. Switch mid-workflow — the full conversation goes with you.

Each prompt is routed through a decision chain:

1. Explicit flags (--escalate, --primary) override everything
2. Session state — if the escalation agent asked a follow-up question, the next turn goes directly back to it
3. Rules layer — hard thresholds (token length, keywords) then a weighted signal scorer
4. Primary model classifier — the primary model decides local or escalate when the scorer is inconclusive
5. Default: local

When the primary model cannot handle a task, it calls escalate(reason) and milk reformats the primary conversation history as context for the escalation agent, which orients itself without a separate reformulation step.

Both the primary and escalation agents support the same set of backends: llama.cpp, Ollama, LM Studio, AWS Bedrock, OpenRouter, Together.ai, Groq, any OpenAI-compatible server (provider: "" or "local"), the Claude Code CLI (provider: "claude-cli"), aider (provider: "aider-cli"), and generic subprocess agents (provider: "subprocess"). Either role can use any backend; there is no backend tied exclusively to primary or escalation.

If no agent is configured, milk starts in setup mode. Use /agent add to configure a backend interactively.

For a reference setup (NVIDIA GPU, Ubuntu/WSL2, llama.cpp from source) see docs/setup.md. For provider-specific setup (Bedrock, OpenRouter, Groq, Copilot, Azure, etc.) see docs/providers.md.

curl -fsSL https://raw.githubusercontent.com/scoutme/milk/main/install.sh | sh

Downloads a pre-built binary for your OS/arch and installs it to ~/.local/bin/milk. No Go required.

To install a specific version:

MILK_VERSION=v0.2.0 curl -fsSL https://raw.githubusercontent.com/scoutme/milk/main/install.sh | sh

irm https://raw.githubusercontent.com/scoutme/milk/main/install.ps1 | iex

Installs to %LOCALAPPDATA%\milk\bin\milk.exe and adds it to your user PATH.

Requires Go 1.21+ and Git.

curl -fsSL https://raw.githubusercontent.com/scoutme/milk/main/install-from-source.sh | sh

Or with go install:

go install github.com/scoutme/milk/cmd/milk@latest

Native Windows is not yet fully supported. The recommended path is WSL2 (Windows Subsystem for Linux), which gives you a full Linux environment where milk runs without modification.

1. Install WSL2 and a Linux distribution (Ubuntu 22.04 or 24.04 recommended)
2. Inside a WSL2 terminal, follow the Linux installation steps above

Known limitations on native Windows (without WSL2):

• go build ./... compiles, but the bash local-agent tool hard-codes sh -c and will fail
• install.sh requires a POSIX shell; there is no .ps1 equivalent yet
• scripts/llama-serve.sh has no PowerShell equivalent

See docs/setup.md for the full Windows/WSL2 setup walkthrough.

milk

Starts an interactive session. The status bar shows the current routing state, active agent, and availability.

Slash commands:

Tab completion: / completes slash commands; @ completes file paths from the current directory (e.g. @src/main.go). Tab cycles forward through matches entry by entry — within a command's variants first, then to the next command. Shift+Tab cycles backward. The hint panel below the transcript shows all matches with the active entry highlighted. Completion works on the token under the cursor, not just at end of line.

Keyboard shortcuts:

All navigation, editing, history search, and undo/redo work while an agent turn is in progress. Only Enter (submit) is blocked until the turn completes.

Input history is persisted per session (~/.milk/sessions/<id>.history) and globally (~/.milk/input_history). Navigation defaults to session history; use /history global to switch.

milk [flags] <prompt>

# Interactive session
milk

# Simple shell automation — routed to primary (local) model
milk "list all Go files modified in the last week"

# Force escalation agent for architecture decisions
milk --escalate "design a caching layer for this service"

# Named session for a specific feature
milk --session auth-refactor "what does the current middleware do?"

# Continue after escalation agent asks a follow-up
milk "yes, use Redis"

# Force back to primary agent
milk --primary "grep for TODO comments"

# Inspect all active sessions
milk --list --all

milk reads ~/.milk/config.json on startup, falling back to defaults if absent.

{
  "agent": "my-local",
  "agents": [
    {
      "name": "my-local",
      "url": "http://localhost:8080",
      "model": "qwen2.5-coder"
    },
    {
      "name": "haiku",
      "url": "https://bedrock-runtime.eu-central-1.amazonaws.com",
      "model": "arn:aws:bedrock:...",
      "provider": "bedrock",
      "aws_region": "eu-central-1"
    },
    {
      "name": "openrouter",
      "url": "https://openrouter.ai/api/v1",
      "model": "meta-llama/llama-3-70b-instruct",
      "provider": "bearer",
      "api_key": "sk-or-..."
    },
    {
      "name": "claude",
      "provider": "claude-cli"
    }
  ],
  "escalation_agent": "claude",
  "default_route": "local",
  "otel": {
    "enabled": true,
    "traces": true,
    "metrics": true,
    "warn_mb": 50,
    "max_mb": 200,
    "metrics_flush_minutes": 5
  },
  "rules": {
    "escalate_above_tokens": 2000,
    "local_below_tokens": 30,
    "escalate_keywords": ["architect", "refactor entire", "design", "explain why", "analyze", "describe", "summarize"],
    "escalate_threshold": 6,
    "local_threshold": -4,
    "local_verb_weight": -3,
    "escalate_verb_weight": 4,
    "path_ref_weight": -2,
    "code_block_weight": -2,
    "open_question_weight": 3,
    "classifier_fallback": "local"
  }
}

agent names the active primary backend. escalation_agent names which backend handles escalated turns — any entry in agents, not necessarily the Claude CLI. Use /agent switch <name> as primary|escalation to change roles at runtime.

Supported provider values:

For Azure OpenAI, use provider: "" (or omit it) and add {"api-key": "<key>"} under headers.

milk config — print the effective configuration (merged defaults + ~/.milk/config.json).

Sessions persist under ~/.milk/sessions/. By default, milk resumes the most recent session for the current directory. Multiple named sessions can coexist in the same directory.

milk maintains a persistent Percept store at ~/.milk/memory/. Percepts are atomic natural-language assertions with a confidence weight that decays each session and rises when reinforced. At session end, NREM consolidation runs: decay → prune → promote high-weight Percepts to the global store.

OTel signal files are written to ~/.milk/otel/:

Use /otel to inspect sizes and /otel trim to archive and reset. Use /metrics to see the latest metric values inline.

The primary agent has access to these built-in tools:

Side-effecting tools (bash, write_file, edit_file, http_get) require user approval on first use per project. Grants persist to ~/.milk/permissions/<project-hash>.json. Use /skip-permissions on to bypass all prompts.

Two opt-in flags in ~/.milk/config.json capture raw protocol streams to disk:

Both flags default to false. The file extensions reflect content format: .ndjson is valid Newline-Delimited JSON (pipe through jq -c); .log is mixed SSE framing text with data: / event: prefixes and blank separators.

• docs/setup.md — full setup guide and local testing procedure
• docs/spec.md — full architecture and design spec
• docs/providers.md — provider configuration guides
• docs/memory-design.md — memory system design and phases
• docs/observability-design.md — OTel observability strategy
• docs/adr/README.md — architecture decision records
• docs/branching-strategy.md — branch and commit conventions