pi-fleet

Pi Fleet — Multi-Model Subagent Router for Pi

Cut your AI coding costs by ~70% by routing the right task to the right model — while keeping Opus as your architect.

The Problem

You're using Claude Code (or Pi) with Opus at $75/M tokens. Every file edit, every boilerplate refactor, every README update burns premium tokens on a model that's overqualified for 80% of the work.

That's like hiring a senior architect to write boilerplate.

The Solution

Pi Fleet is a subagent delegation system that turns Pi into a fleet orchestrator. You (Opus) plan and review. Specialist agents on cheaper models implement. The cost drop is dramatic:

How It Works

You (Opus $75/M) ──plan──→ Specialist Agent ($0.10-$15/M) ──code──→ Files
       ↑                                                                 │
       └────────────────────── review ──────────────────────────────────┘

1. You plan — Opus reads the codebase, designs the approach, writes a complete plan
2. Agent implements — a cheaper model executes the plan precisely
3. You review — Opus verifies quality, catches issues, approves

The architect never writes implementation code. The builders never make architectural decisions.

The Fleet

Agents

Chains (Multi-Agent Pipelines)

Pipelines that automatically flow through scout → plan → implement → review:

Quick Start

1. Install Pi

npm install -g @mariozechner/pi-coding-agent

2. Clone and install fleet config

# Clone this repo
git clone https://github.com/maddefientist/pi-fleet.git
cd pi-fleet

# Run the setup script (copies agents, chains, extensions, and config into ~/.pi/agent/)
./setup.sh

3. Set up API keys

# Required for Qwen models via Alibaba Cloud DashScope
export DASHSCOPE_SG_API_KEY="your-key-here"

# Required for Ollama cloud models (MiniMax, GLM-5, Kimi)
# Either local Ollama or a remote instance
export OLLAMA_BASE_URL="http://localhost:11434"
# Or point to a remote Ollama instance:
# export OLLAMA_BASE_URL="http://your-server:11434"

# Required for GPT Codex (coder-gpt agent)
export OPENAI_API_KEY="your-key-here"

4. Start using the fleet

In your Pi session, delegate instead of implementing:

# Backend feature — full pipeline
{ chain: "build", task: "Add user authentication with JWT tokens" }

# Quick fix — single agent
{ agent: "coder-quick", task: "Refactor the config loader to use Zod validation" }

# Frontend work
{ agent: "designer", task: "Build a responsive dashboard layout with the design system" }

# Documentation
{ chain: "document", task: "Write README for the new auth module" }

# Already wrote the plan? Just execute
{ chain: "implement", task: "<paste your plan here>" }

Architecture Deep Dive

The Golden Rule

Any code >20 lines or touching >2 files → delegate.

The architect (you, Opus) makes decisions. The builders (cheap models) implement. This is enforced by AGENTS.md:

• Plan completely — specialists can't ask questions
• Specify every file, function, import — no ambiguity
• Review after delegation — read files, verify correctness

Why This Works

1. Opus is 37x more expensive than Qwen. Routing implementation to Qwen saves ~$73/M tokens on coding work.
2. Qwen 3.6 Plus has 1M context. It can hold an entire codebase in a single session.
3. MiniMax is nearly free at $0.10/M. Documentation, summaries, bulk operations cost pennies.
4. The architect pattern is natural. Senior engineers plan and review; juniors implement. Same principle.

Provider Extensions

Pi Fleet includes custom provider extensions that plug into Pi's provider system:

• alibaba-qwen — Connects to Alibaba Cloud DashScope for Qwen models (3.6 Plus, 3 Max, Coder Plus/Flash, Turbo, VL)
• context-tracker — TUI widget showing project, branch, task, and modified files

These are loaded by Pi automatically from ~/.pi/agent/extensions/.

Agent Definition Format

Each agent is a Markdown file with YAML frontmatter that Pi reads:

---
name: coder
description: Primary coding workhorse on Qwen 3.6 Plus
model: dashscope-us/qwen3.6-plus-2026-04-02
thinking: medium
defaultReads: context.md, plan.md
defaultProgress: true
---

You are a senior implementation engineer...

Key fields:

• model — which model to use (format: provider/model-id)
• thinking — reasoning depth (none, low, medium, high)
• defaultReads — files the agent auto-reads at start
• defaultProgress — whether to track progress in progress.md

Chain Definition Format

Chains are Markdown files defining sequential agent pipelines:

---
name: build
description: Full architect→implement pipeline
---

## scout
output: context.md

Analyze the codebase for {task}...

## coder
reads: context.md, plan.md
progress: true

Execute the implementation plan...

## reviewer
reads: context.md, plan.md, progress.md
model: google-antigravity/gemini-3-pro-high

Review the implementation...

Each step can specify: model (override), output (file to write), reads (files to read from previous steps), progress (track progress).

Customization

Adding Your Own Models

Edit config/settings.json to add models to the enabledModels list. Pi supports any OpenAI-compatible endpoint through provider extensions.

Adding Your Own Agents

Create a new .md file in agents/:

---
name: my-specialist
description: What this agent does
model: provider/model-id
---

System prompt instructions here...

Adding Your Own Chains

Create a new .chain.md file in chains/:

---
name: my-pipeline
description: What this chain does
---

## step-one
output: context.md
Instructions for step one...

## step-two
reads: context.md
model: provider/model-id
Instructions for step two...

Changing the Model Routing

Edit config/AGENTS.md — the routing table maps task types to agents. Change models, swap agents, or add new rows.

Requirements

• Pi ≥ 0.65.2
• pi-subagents ≥ 0.11.0
• API keys for your chosen providers (at minimum: DashScope for Qwen)
• Ollama (local or remote) for MiniMax, GLM-5, and local models

Included Providers

License

MIT — use it, fork it, share it.

Credits

Built by MadDefientist using Pi — an open-source Claude Code alternative.

The fleet pattern was born from a simple insight: senior architects don't write boilerplate, and neither should $75/M models.