multipi

Multi-agent orchestration for open-source LLMs in pi

Route reasoning, architecture, coding, and review to the models that excel at them — with web search for every endpoint.

---

Table of Contents

• Why This Exists
• Research & Rationale
  • The "No Best Model" Paradigm
  • Context Engineering: Why Isolation Wins
  • State Machines for Verified Software Engineering
  • Local-First AI & Privacy Economics
• What It Does
• Architecture
• Quick Start
• Capabilities Deep Dive
• Model Configuration
• Testing
• Who This Is For
• Comparison with Other Frameworks
• Tmux Integration
• License

---

Why This Exists

If you're using local open-source models via Ollama, you face a problem that Claude Pro and GPT-4 users don't:

No single model does everything well.

Model Size	Excels at	Struggles with
3B–8B	Fast lookups, narrow tasks	Architecture, research synthesis, review depth
70B	General coding	Long-context reasoning, state-machine planning
123B	Architecture docs, structured output	Real-time cost, narrow scouts
1T	Deep reasoning, citation fidelity	Speed, token cost per call

An 8B model codes OK but hallucinates architecture. A 1T model reasons brilliantly but burns tokens on boilerplate. A 70B model is mediocre at both. You need a team, not a person.

The Pi Gap

Pi ships with no subagents by design — valid for closed APIs where one model can wear many hats. But for Ollama users this creates five real problems:

1. Context Pollution Asking one model to "research pgvector HNSW tuning, design a schema, write the migration, then review it" buries the code in research citations. The model forgets the architecture by the time it reaches tests.

2. No Native Web Search Claude and Gemini can browse. Local models can't. If your model runs on 127.0.0.1:11434, you need external tools for current docs, benchmarks, and API references.

3. No Tool Propagation Even if you add fetch_url to pi, a subagent spawned with --tools read,bash won't inherit it. The parent can search; the child can't. Chain breaks at the first link.

4. Zero Visibility A long-running research agent might be stuck on a failed fetch, burning GPU hours. You have no idea until it returns — or times out.

5. Project-Specific Lock-In Hardcoding paths, invariants, and architecture into agent prompts means rewriting agents for every project.

multipi solves all five by adding capability-based model routing, web tools with local SearXNG, automatic tool propagation, live tmux visibility, and project-aware generic agents.

---

Research & Rationale

The "No Best Model" Paradigm

The AI industry reached an inflection point in early 2026: between February 16–19, 2026, Qwen 3.5, Claude Sonnet 4.6, and Gemini 3.1 Pro all shipped within the same week—each leading on completely different benchmarks. Gemini dominated abstract reasoning (ARC-AGI-2: 77.1%), Sonnet led on expert knowledge (GDPval-AA Elo: 1633), and they tied on agentic coding (SWE-bench ~80%).

The conclusion from industry analysis is clear: "Best" depends entirely on what you're doing. The data makes that irreducible. No single model fills the radar chart. Each has peaks and valleys. Locking into one provider means accepting suboptimal performance on entire categories of tasks.

This isn't just a benchmark curiosity—it has profound economic implications. Routing 60% of suitable traffic from a $15/Mtok model to a $0.60/Mtok model drops daily inference costs by ~46% with zero quality loss on those tasks. The smartest teams stopped asking "which model?" and started asking "how do I route each request to the right model automatically?"

multipi operationalizes this insight for local/Ollama users. Instead of treating your ollama pull as a single-model decision, you compose a capability map:

Agent	Purpose	Routes To	Why
orchestrator	State-machine conductor, gate enforcement	kimi-k2.6 (1T)	Tracks S0→S6 pipeline, enforces invariants, makes routing decisions
research	Deep technical investigation, citations	kimi-k2.6 (1T)	256K context for synthesis; cites primary sources with URLs + dates
planner	Architecture, schema DDL, phased plan	devstral-2 (123B)	Strong structured output; designs DB schemas without forgetting constraints
implementer	Code, tests, Docker, Makefile	devstral-2 (123B)	Purpose-built for implementation; can fan out parallel instances
reviewer	Adversarial QA, red-team checklist	deepseek-v4-flash	Fast, cheap, adversarial — catches corner cases in budget
scout	Narrow lookups, codebase recon	gemini-3-flash	Sub-second latency; answers one question with evidence and stops
worker	General-purpose executor, fallback tasks	glm-5.1	Full tool access; handles utility work outside the main pipeline

This mirrors what the vLLM project calls a "Semantic Router" and what production AI gateways implement at the enterprise layer—but multipi brings it to your local stack, with zero API spend and full data sovereignty.

Context Engineering: Why Isolation Wins

Anthropic's research on context engineering establishes a critical principle: context must be treated as a finite resource with diminishing marginal returns. As context length increases, a model's ability to capture pairwise attention relationships gets stretched thin. Studies on "needle-in-a-haystack" benchmarking have uncovered the concept of context rot: as tokens accumulate, the model's ability to accurately recall information from that context decreases.

Every new token introduced depletes the model's "attention budget." When you ask a single model to research, architect, code, and review in one conversation, you're forcing it to attend to:

• Dozens of research citations and URLs
• Schema definitions and migration plans
• Implementation files and test cases
• Review checklists and corner-case analysis

All simultaneously. This isn't just slow—it's lossy. The model begins conflating research prose with code logic, or drops architectural constraints when generating tests.

multipi's architecture solves this by giving each cognitive role its own isolated context window. Research lives in the research agent. Code lives in the implementer. Review lives in the reviewer. Each window contains only the tokens relevant to that role. This mirrors what Anthropic's multi-agent researcher demonstrates: "many agents with isolated contexts outperformed single-agent, largely because each subagent context window contains only the information it needs."

The orchestrator doesn't carry implementation details in its window—it carries state (S0→S6) and gate outcomes (PASS/BLOCK). The scout doesn't carry architecture—it carries one grep result. This is just-in-time context injection at the agent level, not the token level.

State Machines for Verified Software Engineering

Unstructured LLM code generation suffers from a fundamental reproducibility problem: ask the same model to "build a pgvector service" twice, and you'll get two different architectures. Without enforced stages, models skip testing, forget schema constraints, or hallucinate requirements.

multipi treats the software engineering lifecycle as a finite state machine:

S0_INTAKE → S1_RESEARCH → S2_PLANNING → S3_IMPLEMENTATION → S4_REVIEW → S5_ITERATE | S6_DONE

State	Agent	Output	Gate
S1	research	research_dossier.md	Sections complete, citations valid, matrices measurable
S2	planner	architecture.md, schema.sql, phased_plan.md, risk_register.md	Architecture matches locked artifacts
S3	implementer	Working repo	Tests pass, lints clean, replay idempotent
S4	reviewer	review_gate<N>.md	One BLOCK kills the gate; orchestrator re-dispatches
S5	orchestrator	—	Routes BLOCK + required-changes back to producer
S6	orchestrator	Deliverables checklist	Every gate PASSed

This isn't bureaucratic overhead. It's verified output generation. The reviewer agent is adversarial by design—it assumes the producing agent cut corners. It red-teams for: service dies mid-batch, 10× volume spikes, duplicate data injection, PII leaks, license ambiguity. It returns PASS or BLOCK with ordered required changes.

Industry research on autonomous red teaming shows that multi-agent adversarial systems dramatically improve output quality by making the generation process self-correcting. multipi bakes this into the state machine: no state transition without gate clearance. A BLOCK at S4 forces a return to S3 (or S2, if the review reveals architectural flaws). The orchestrator tracks this, re-dispatches, and logs every transition.

Local-First AI & Privacy Economics

Enterprise spending on LLM APIs doubled to $8.4 billion in 2025, yet 44% of organizations cite data privacy and security as the top barrier to adoption. Every prompt sent to a cloud API touches external servers. For healthcare, finance, legal, defense, or any organization handling PII, this is a compliance dealbreaker.

Self-hosting via Ollama solves the privacy problem completely:

• Zero data exfiltration: Prompts never leave 127.0.0.1
• No API keys: No vendor accounts, no rate limits, no billing surprises
• Air-gapped viability: Runs entirely on hardware you control
• GDPR/HIPAA alignment: Data sovereignty by architecture, not policy

But self-hosting creates its own gap: local models don't have web search, don't have multi-model coordination, and don't have agentic pipelines. multipi closes that gap by bringing the entire orchestration layer local:

Concern	Cloud API User	Raw Ollama User	multipi User
Data privacy	❌ External servers	✅ Local	✅ Local
Multi-model specialization	❌ One API endpoint	❌ Manual switching	✅ Auto-routing
Web search	✅ Built-in	❌ None	✅ SearXNG local
Agent pipelines	❌ Not native	❌ None	✅ State machine
Context isolation	⚠️ Manual	❌ Single window	✅ Per-agent windows
Live visibility	⚠️ Dashboard	❌ Silent	✅ tmux windows
Cost per token	$$$	Hardware only	Hardware only

The SearXNG integration deserves special mention. It's a self-hosted metasearch engine that queries Google, DuckDuckGo, Brave, and Startpage in parallel, aggregates with deduplication, and returns clean JSON. No API keys. No bot blocks. No query logging. Just a Docker container on your machine giving every local model—even a 3B parameter endpoint—the ability to browse the current web.

---

What It Does

1. Capability-Based Model Routing

Deploy the right model for the right cognitive load:

Agent	Purpose	Routes To	Why
orchestrator	State-machine conductor, gate enforcement	kimi-k2.6 (1T)	Tracks S0→S6 pipeline, enforces invariants, makes routing decisions
research	Deep technical investigation, citations	kimi-k2.6 (1T)	256K context for synthesis; cites primary sources with URLs + dates
planner	Architecture, schema DDL, phased plan	devstral-2 (123B)	Strong structured output; designs DB schemas without forgetting constraints
implementer	Code, tests, Docker, Makefile	devstral-2 (123B)	Purpose-built for implementation; can fan out parallel instances
reviewer	Adversarial QA, red-team checklist	deepseek-v4-flash	Fast, cheap, adversarial — catches corner cases in budget
scout	Narrow lookups, codebase recon	gemini-3-flash	Sub-second latency; answers one question with evidence and stops
worker	General-purpose executor, fallback tasks	glm-5.1	Full tool access; handles utility work outside the main pipeline

Instead of one model doing everything poorly, each task goes to the model that excels at it. Isolated context windows mean no pollution between research prose and code logic.

2. SearXNG: Web Search for Every Model

Two extensions give every model — even 3B param local ones — the ability to browse:

Tool	Backend	Best For
fetch_url	HTTP + jina.ai markdown extract	Reading docs, API references, changelogs
web_search	Local SearXNG (127.0.0.1:8888)	Finding current info, benchmarks, library versions

SearXNG is a self-hosted metasearch engine. It queries Google, DuckDuckGo, Brave, and Startpage in parallel, aggregates with deduplication, and returns clean JSON:

1. Benchmarking Ollama embeddings on MTEB
   URL: https://ollama.com/blog/embedding-models
   Ollama's embedding models evaluated on the Massive Text Embedding Benchmark...

2. Ollama Embedding Models: Performance Analysis
   URL: https://cookbook.chromadb.dev/ollama-embeddings/
   We benchmark bge-m3, nomic-embed-text, mxbai-embed-large...

No API keys. No rate limits. No DuckDuckGo bot blocks. Just a Docker container on your machine.

3. Tool Propagation Across Agent Chains

The subagent extension auto-forwards all parent extension tools to every child:

Parent has:  read, bash, write, edit, fetch_url, web_search, subagent
Child scout declares:  read, grep, ls, bash
Result:  read, grep, ls, bash, fetch_url, web_search
                                        ↑↑↑↑↑↑  auto-propagated

A chain of orchestrator → research → planner → reviewer never loses tools mid-pipeline. The recursion guard filters out subagent so an agent can't accidentally spawn itself.

4. Live Visibility (Tmux)

When pi runs inside tmux, each subagent gets a dedicated window:

0: main*           ← your pi session
1: π-research     ← live tail: "Reading: pgvector docs..."
2: π-scout        ← live tail: "grep -n embedding models..."
3: π-implementer  ← live tail: "writing tests/test_embed.py..."

Watch agents work in real time. Kill stuck ones. A powerline dashboard above the editor shows who's running and which model they're on:

 π-agents │ ⚡1 orchestrator [kimi-k2.6] │ ⚡2 implementer [devstral-2]

5. Project-Aware Generic Agents

The 7 agents are completely generic — no hardcoded project names or paths. They adapt by reading the local directory:

my-project/
├── project.md            ← agent ops manual (connection strings, commands, gotchas)
└── .pi/
    ├── agent_prompts.md  ← project-specific role overrides
    └── artifacts/         ← locked schemas, architecture, contracts

Read order: project.md (immediate context) → .pi/agent_prompts.md (role overrides) → .pi/artifacts/ (locked contracts) → generic defaults.

One multipi install works for every project. No agent rewriting. Just a project.md at the root.

---

Architecture

multipi/
├── agents/                    # Generic subagent definitions
│   ├── orchestrator.md       # S0→S6 state machine conductor
│   ├── research.md           # Deep investigation + citations
│   ├── planner.md             # Architecture, schema, phased plan
│   ├── implementer.md         # Code, tests, Docker
│   ├── reviewer.md            # Adversarial QA gates
│   ├── scout.md               # Narrow read-only recon
│   ├── worker.md              # General-purpose executor
│   └── MODEL_ROUTING.md       # Ollama Cloud capability map
│
├── extensions/                # Pi extensions (TypeScript, hot-reload)
│   ├── fetch_url.ts            # HTTP fetch + jina.ai extract
│   ├── web_search.ts           # SearXNG JSON API client
│   └── subagent/
│       ├── index.ts            # Tool registration + propagation
│       ├── agents.ts           # agent discovery from disk
│       ├── dashboard.ts        # Powerline TUI widget
│       └── tmux.ts            # Tmux window lifecycle
│
├── searxng/                   # Local search infrastructure
│   ├── docker-compose.yml      # Container (port 8888)
│   └── settings.yml            # Engine config (Google, DDG, Brave, Startpage)
│
├── tests/
│   ├── unit/                   # Agent parsing, routing, validation
│   ├── integration/            # End-to-end chain tests
│   └── fixtures/               # Test agent definitions
│
├── bin/
│   └── install-agents.sh      # Manual agent install
│
└── package.json               # Pi package manifest

---

Quick Start

Quick Start

1. Install multipi

# Via npm (preferred)
pi install npm:@chewey182/multipi

# Or from GitHub
pi install git:github.com/Ch3w3y/multipi

# Or local clone
git clone https://github.com/Ch3w3y/multipi.git ~/multipi
cd ~/multipi
pi install .

2. Start SearXNG

npm run searxng:start  # docker compose up -d

# Verify
curl -s 'http://127.0.0.1:8888/search?q=ollama+pgvector&format=json' | jq '.results | length'

3. Start tmux + pi

tmux new-session -s work
pi

4. Dispatch agents

# Single agent with web search
subagent
agent: scout
task: "Search for pgvector HNSW tuning at 100M rows. List 3 key parameters."

# Full orchestrated pipeline
subagent
chain:
  - agent: research
    task: "Research pgvector at scale. Write ~/output/research.md."
  - agent: planner
    task: "Read ~/output/research.md. Write architecture.md + schema.sql."
  - agent: reviewer
    task: "Review both. Return PASS or BLOCK."

---

Capabilities Deep Dive

The Orchestrator State Machine

The orchestrator enforces a strict pipeline where no state is skipped:

S0_INTAKE → S1_RESEARCH → S2_PLANNING → S3_IMPLEMENTATION → S4_REVIEW → S5_ITERATE | S6_DONE

State	Agent	Output	Gate
S1	research	research_dossier.md	Sections complete, citations valid, matrices measurable
S2	planner	architecture.md, schema.sql, phased_plan.md, risk_register.md	Architecture matches locked artifacts
S3	implementer	Working repo	Tests pass, lints clean, replay idempotent
S4	reviewer	review_gate<N>.md	One BLOCK kills the gate; orchestrator re-dispatches
S5	orchestrator	—	Routes BLOCK + required-changes back to producer
S6	orchestrator	Deliverables checklist	Every gate PASSed

Each transition is status-line logged:

[S1→S2] planner produced architecture.md (1.2k lines) — gate passed

Research Agent

The research agent doesn't just search — it cites:

• Primary > secondary > blog
• Every benchmark: dataset name, hardware, date
• Sources >18 months old flagged "STALE — verify"
• URL + accessed YYYY-MM-DD on every citation
• Uses fetch_url to verify claims older than training data

Target: 4–10K words, structured sections, decision matrices with measurable axes (ms, $/M tokens, GB RAM, MTEB score).

Reviewer Agent

The reviewer is adversarial by design — it assumes the producing agent cut corners:

• Checklists per gate with evidence citations (file:line, command output)
• Red-team checklist: service dies mid-batch, 10× volume spike, duplicate data, PII leak, license ambiguity
• Returns PASS or BLOCK with ordered required changes
• Uses fetch_url to verify external claims (licenses, benchmark numbers, API docs)
• Token budget matters — the reviewer reads, doesn't write prose

Parallel Implementer Fan-Out

Within S3, the orchestrator can dispatch parallel implementers for disjoint paths:

- docker/db/** + Alembic migrations
- services/common/**
- services/embed_worker/**
- services/extract_worker/**
- services/ingest/sources/{pubmed,who_don}.py
- tests/**

Each implementer runs in isolation on its own model (devstral-2). No single context pollution. Merge at review time.

Web Search Architecture

Pi process
  → web_search tool
    → fetch → http://127.0.0.1:8888/search?q=...
      → SearXNG container
        → parallel queries to Google, DDG, Brave, Startpage
        → aggregates, deduplicates, scores, returns JSON
      ← JSON results
    ← formatted results
  ← model receives structured search output

Tool Propagation Architecture

Parent pi (has fetch_url, web_search, subagent)
  → subagent dispatch: agent = scout, task = "..."
    → subagent extension reads parent tools via pi.getAllTools()
    → filters builtins, keeps extensions (fetch_url, web_search)
    → filters subagent itself (recursion guard)
    → builds --tools read,grep,ls,fetch_url,web_search
    → spawns child pi process
      → child pi auto-discovers extensions from ~/.pi/agent/extensions/
      → --tools allowlist permits fetch_url + web_search
      → scout agent has full web capability
    ← child returns result
  ← result to parent

---

Model Configuration

Ollama Cloud (optional)

If you have Ollama Cloud access, subagents route there automatically:

export OLLAMA_CLOUD_BASE_URL="https://cloud.ollama.ai/v1"
export OLLAMA_CLOUD_API_KEY="your-key"

The subagent extension generates a temporary provider override for each child process.

Local Ollama (fallback)

If no cloud env vars are set, subagents fall back to http://127.0.0.1:11434/v1.

Custom model maps

Edit ~/.pi/agent/agents/MODEL_ROUTING.md to add your own mappings. The CAPABILITY_MODEL_MAP in extensions/subagent/index.ts is the source of truth:

const CAPABILITY_MODEL_MAP: Record<string, string> = {
    orchestrator: "ollama/kimi-k2.6:cloud",
    research:    "ollama/kimi-k2.6:cloud",
    planner:     "ollama/devstral-2:123b-cloud",
    implementer: "ollama/devstral-2:123b-cloud",
    reviewer:    "ollama/deepseek-v4-flash:cloud",
    scout:       "ollama/gemini-3-flash-preview:cloud",
};

---

Testing

# Unit tests (no Docker, no tmux, no pi needed)
node --test tests/unit/*.test.ts

# Integration tests (needs Docker + SearXNG running)
./tests/integration/run.sh

# Acceptance test (full pipeline: research → planner → reviewer)
pi -p "Run the acceptance test in ~/.pi/agent/ACCEPTANCE_TEST.md"

# Start SearXNG
npm run searxng:start

---

Who This Is For

You are...	multipi helps because...
Running local models (Ollama, llama.cpp)	No model does everything. Route by capability.
Hitting context limits	Research, architecture, code live in separate windows. No pollution.
Using models without web search	SearXNG gives Google/DuckDuckGo/Brave access to any endpoint.
Building complex systems	Orchestrator enforces gates. Reviewer blocks bad output. No silent failures.
Working across multiple projects	Generic agents + per-project project.md. One install, infinite projects.
On air-gapped or privacy-sensitive hosts	SearXNG + Ollama run entirely local. No data leaves your network.

---

Comparison with Other Frameworks

Feature	multipi	CrewAI	LangChain	LiteLLM Router
Designed for	Local/Ollama + Pi IDE	General task automation	Chains & RAG	API routing
Subagent isolation	Full process per agent	Shared context or threads	Shared context	N/A (single-call)
Context isolation	✅ Separate windows	⚠️ Configurable	⚠️ Manual	N/A
Web search	✅ SearXNG (local)	❌ External APIs	✅ External tools	N/A
Tool propagation	✅ Automatic	⚠️ Manual wiring	⚠️ Manual wiring	N/A
State machine gates	✅ Built-in S0→S6	❌ Manual	❌ Manual	N/A
Adversarial review	✅ Native reviewer agent	❌	❌	N/A
Tmux visibility	✅ Live windows	❌	❌	❌
Air-gapped viable	✅ Fully local	⚠️ Needs cloud APIs	⚠️ Needs cloud APIs	❌ Cloud only
Cost model	Hardware only	API costs	API costs	API costs
Pi IDE integration	✅ Native	❌	❌	❌

When to use what:

• multipi: You're coding in Pi, running local models, and want a complete software engineering pipeline with state enforcement, web search, and zero API spend.
• CrewAI: You need general-purpose agent teams for business tasks (research reports, social media, email drafting) and are comfortable with cloud APIs.
• LangChain: You're building RAG applications or sequential LLM chains and need maximum library ecosystem support.
• LiteLLM: You're running production API traffic and need unified billing, load balancing, and failover across GPT-4, Claude, and Gemini.

---

Tmux Integration

When pi runs inside tmux, each subagent spawns a π-{agent} window for live visibility. Outside tmux, subagents run normally without windows.

Starting tmux + pi

tmux new-session -s work
pi

# Or detached — attach later
tmux new-session -d -s work "cd ~/my-project && pi"
tmux attach -t work

Window naming

Agent	Window	Example
scout	π-scout	Narrow lookup
research	π-research	Deep technical research
orchestrator	π-orchestrator	Chain step 1
orchestrator-2	π-orchestrator-2	Chain step 2 (numbered)

Windows auto-close when the subagent finishes.

Dashboard widget

A powerline-style status bar above the pi editor:

 π-agents │ ⚡1 orchestrator [kimi-k2.6] │ ⚡2 implementer [devstral-2]

Works in both tmux and non-tmux modes.

Troubleshooting

"Subagents work but no windows appear"

echo $TMUX       # If empty, start tmux first
tmux new-session -s pi

"Tmux windows from two pi sessions collide" Use separate sessions:

tmux new-session -s work1 "cd /project/a && pi"
tmux new-session -s work2 "cd /project/b && pi"

Optional: auto-tmux wrapper

# ~/.bashrc or ~/.zshrc
pi() {
    if [ -z "$TMUX" ]; then
        tmux new-session -s multipi "$@" ";"
    else
        command pi "$@"
    fi
}

---

License

MIT — by Ch3w3y

---

Built on pi. Powered by Ollama. Researched with SearXNG.