Mithril — Getting Started & Architecture Guide

Goal

Set up Mithril with multiple Gemini models as a multi-agent backend, then connect Junie to it. Junie sees "one model" but behind it you have specialized Gemini agents working together.

Step 1: Install Mithril

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/GiacomoSaccaggi/mithril/main/install.sh | bash

# Or Docker
docker pull ghcr.io/giacomosaccaggi/mithril:latest

Step 2: Get a Gemini API Key

# Get your key from https://aistudio.google.com/apikey
mithril config set gemini "AIzaSy..."  

Step 3: Create a Multi-Agent Fellowship

# Create .mithril/fellowship.yaml in your project:

name: "gemini-multi"
description: "Multi-agent Gemini team"

controller:
  provider: local
  model: qwen-1.5b     # Free local router

agents:
  - name: coder
    provider: gemini
    model: gemini-2.5-flash
    role: "Fast coder — implements features quickly"
    when: "coding tasks, implementations, bug fixes"
    can_call: [reviewer]
    tools: ["*"]

  - name: reviewer
    provider: gemini
    model: gemini-2.5-pro
    role: "Senior reviewer — catches bugs and architecture issues"
    when: "code review, complex logic analysis"
    can_call: []
    tools: ["read_psi", "grep_files", "git_diff"]

  - name: researcher
    provider: gemini
    model: gemini-2.5-flash
    role: "Researcher — searches web and documentation"
    when: "questions about APIs, libraries, documentation"
    can_call: []
    tools: ["web_search", "fetch_page"]

Step 4: Start Mithril

mithril serve
# Output:
#   Server http://localhost:16180
#   Fellowship: gemini-multi (coder, reviewer, researcher)

Step 5: Connect Junie

In your JetBrains IDE with Junie:

1. Open Settings → Junie → AI Provider
2. Select Ollama as the provider type
3. Set URL: http://localhost:16180
4. Click "Refresh Models" — you'll see gemini-multi:latest
5. Select it as your model
6. Done! Junie now uses your multi-agent Gemini team

What Happens When You Ask Junie Something

1. Junie sends your request to http://localhost:16180/api/chat
2. Mithril's GGUF classifier reads it (~100ms, free)
3. Routes to the right agent:
   • "Fix this bug" → coder (Gemini Flash)
   • "Review this PR" → reviewer (Gemini Pro)
   • "How does this API work?" → researcher (Gemini Flash + web)
4. Agent can use tools (read files, search web, etc.)
5. Agent can delegate: coder writes code → hands to reviewer → reviewer approves
6. Response streams back to Junie

Docker Alternative (for teams)

# docker-compose.yml already included in repo
# Just set your Gemini key:
echo "MITHRIL_KEY_GEMINI=AIzaSy..." > .env

docker compose up -d
# → http://localhost:16180 ready for all team members

The Request Flow

1. Client sends chat request to /api/chat
2. API Layer deserializes Ollama/OpenAI format
3. GGUF Classifier — tiny local model decides which agent (~100ms, free)
4. Agent executes with its provider + available tools
5. Tool Loop — agent calls tools as needed
6. Delegation — agent can hand off via NEXT/TASK
7. Response streams back to client

Three Provider Types

• Local GGUF: Free, private, used for routing. llama.cpp inference.
• Cloud API: Gemini, OpenAI, Anthropic, Groq. Pay-per-token via HTTP.
• CLI Tools: Kiro, Junie, any CLI with chat mode. Subprocess calls.