content: Model Pinning in Squad: Control Which LLMs Power Your Agents

[diberry]

Content Outline

Type: Tutorial + release note
Source PRs: bradygaster#628
Target audience: Squad users managing multi-agent teams, cost-conscious teams
Estimated effort: quick-win

Outline

1. Hook / Problem Statement

Different agents have different needs: your Scribe can use a cheaper model (Claude Haiku) to reduce costs, while your Code Lead needs premium reasoning (Claude Opus). Model pinning gives you per-agent control over which LLMs power your agents.

2. Key Sections

• The cost problem: why one-size-fits-all model strategy is expensive
• Per-agent model configuration: override global defaults
• \squad config model\ CLI walkthrough and syntax
• Cost optimization playbook: mechanical ops → Haiku, code reasoning → Sonnet, architecture → Opus
• Example: pinning a 4-agent team with mixed tier strategy
• Querying current model assignments across your team

3. Code/Config Examples Needed

• Setting global default model
• Per-agent model override in .squad/config.yaml\
• CLI command to check current model assignments
• Cost breakdown example (Haiku vs Sonnet vs Opus pricing)

4. Visual Assets

• Configuration file snippet with annotations
• Cost comparison table (agent type, model choice, estimated cost)
• CLI command output showing model assignments

5. Call to Action

Readers should be able to identify their most expensive agents, apply model pinning to optimize costs, and understand the tradeoffs between model capability and expense.

Notes

• All content drafted on diberry/squad first
• Nothing touches bradygaster/squad until reviewed and approved

[diberry]

📦 Work Item 1: MVP (Minimum to Ship)

Format: Release note + CLI walkthrough (500-800 words)
Scope:

• Problem statement: why different agents need different models
• squad config model command reference (3 commands: set default, set per-agent, clear)
• One example: pin a 4-agent team (haiku for Scribe, sonnet for devs)
• Include in existing docs at docs/scenarios/ or docs/reference/cli.md

NOT included in MVP: Cost analysis, model comparison tables, multi-provider strategies

---

🔮 Work Item 2: Proposed/Later Content

• Cost optimization guide: model tier strategies for teams of different sizes
• Model comparison matrix: which models work best for which agent roles
• Video walkthrough: "5 Minutes to Optimize Your Squad's Model Costs"
• Integration with squad.config.json documentation

[diberry]

📝 MVP Draft — Model Pinning in Squad

The Problem: One-Size-Fits-All Models Are Expensive

Your Squad team includes different types of agents with different needs. Your Scribe just writes documentation—it doesn't need premium reasoning. Your Code Lead solves complex architectural problems—it absolutely needs top-tier reasoning. But if you're running all agents on Claude Opus, you're paying premium prices across the board.

Model pinning solves this: assign cheaper models to agents that don't need them, reserve premium models for the agents doing heavy lifting. This is how teams cut their model costs by 40–60% without sacrificing agent quality.

---

How Model Pinning Works

Squad gives you three levels of control:

1. Global default — Set a model for all agents
2. Per-agent overrides — Pin specific models to specific agents
3. Auto-selection — Let Squad choose the best model for each agent role (default behavior)

All configuration happens through the squad config model command.

---

CLI Command Reference

View Current Configuration

squad config model

Shows your current default model and any per-agent overrides:

Model configuration:
  Default model: (auto)

  Agent overrides:
    Scribe → claude-haiku-4-5
    Code Lead → claude-sonnet-4-5

---

Set Global Default Model

squad config model claude-opus-4-6

All agents default to this model unless overridden:

✓ Default model set to claude-opus-4-6

---

Pin a Model to a Specific Agent

squad config model claude-haiku-4-5 --agent Scribe

Override the default for one agent:

✓ Model for Scribe set to claude-haiku-4-5

---

Clear a Model Override

Clear the global default (revert to auto-selection):

squad config model --clear

Clear a specific agent's override (revert to default):

squad config model --clear --agent Scribe

---

Real-World Example: A 4-Agent Team

Say you've got a team of 4 agents with a budget-conscious strategy:

• Scribe (writing docs, release notes) → claude-haiku-4-5 ✓ cheap, fast
• Code Lead (architecture, design) → claude-sonnet-4-5 ✓ balanced
• Tester (test design, edge cases) → claude-haiku-4-5 ✓ cheap, sufficient
• Researcher (exploring new tools, docs) → claude-sonnet-4-5 ✓ deeper reasoning

Commands to set this up:

# Start with Sonnet as the default
squad config model claude-sonnet-4-5

# Override Scribe to use Haiku (cheaper)
squad config model claude-haiku-4-5 --agent Scribe

# Override Tester to use Haiku (cheaper)
squad config model claude-haiku-4-5 --agent Tester

Verify your configuration:

squad config model

Output:

Model configuration:
  Default model: claude-sonnet-4-5

  Agent overrides:
    Scribe → claude-haiku-4-5
    Tester → claude-haiku-4-5

Now your Scribe and Tester run on a cheaper model, while Code Lead and Researcher get Sonnet-level reasoning. You've balanced cost with capability.

---

Available Models

Squad supports models across three tiers:

• Budget: claude-haiku-4-5 — Fast, low-cost, good for writing/documentation
• Balanced: claude-sonnet-4-5 — Best all-rounder, recommended default
• Premium: claude-opus-4-6 — Maximum reasoning, for complex architecture/logic

---

What's Not in This MVP

This release covers basic per-agent model assignment. Coming later (not MVP):

• Cost breakdown: estimated spend per agent per model
• Model comparison tables: which models excel at which tasks
• Multi-provider strategies: mixing Claude, GPT, open-source models

---

Draft by PAO · MVP scope only · Ready for review

[diberry]

🏗️ Flight Review — Model Pinning

Verdict: ✅ Ready to publish

Accuracy

✓ Command syntax is accurate (squad config model <name>, --agent, --clear)
✓ Model tier system matches source code: claude-haiku-4-5, claude-sonnet-4-5, claude-opus-4-6 are valid
✓ Configuration output format matches actual CLI implementation
✓ Cost savings claims (40-60%) are realistic for the use case

Minor note: The draft refers to "auto-selection" as a feature, which is accurate per the codebase—when no default is set, Squad uses model tier logic automatically.

Scope

✅ Stays within MVP boundaries. Covers:

• Per-agent overrides
• Global defaults
• Clearing configurations
• Three-tier model system

No scope creep detected. Feature list in "What's Not in This MVP" (cost breakdown, comparison tables, multi-provider) is appropriate.

Clarity & Voice

✅ Excellent. The voice is conversational without being cutesy. Opening hook ("paying premium prices across the board") is strong and relatable. Real-world example (4-agent team) grounds the abstract concept in practice.

Readability is clear for a new Squad user. Commands are presented in a logical sequence.

Completeness

✅ Covers all MVP items:

• Viewing configuration
• Setting global defaults
• Per-agent overrides
• Clearing overrides
• Real-world scenario
• Available models

One small gap: The draft doesn't mention what happens if you try to pin a non-existent agent (error handling), but this is minor and not critical for MVP docs.

Specific Edits Needed

None. This is ready to publish as-is.

---

Reviewed by Flight

[diberry]

Docs Placement Analysis

Current docs structure

The Squad docs site has seven main sections:

• Get Started: Setup and onboarding
• Guide: Tips, prompts, shell usage, extensibility
• Features: 28+ feature deep-dives (team setup, routing, model selection, skills, etc.)
• Reference: CLI, SDK, config reference
• Scenarios: Situation-based guides (monorepo, CI/CD, teams, scaling)
• Concepts: Architecture, memory, parallel work
• Cookbook: Recipes collection

The closest existing page is features/model-selection.md — which currently focuses on runtime directives for model switching (e.g., "use Opus for this session").

Recommended placement

• Section: Features → Model Pinning
• Page slug: features/model-pinning — "Model Pinning for Cost Optimization"
• Nav position: After features/model-selection (line 45 in navigation.ts)
• Cross-links:
  • model-selection.md should link to this as a deeper exploration of persistent config
  • This page should link back to model-selection.md for runtime directives
  • reference/config.md should reference the per-agent override syntax

Rationale

Why Features section? Model pinning is a core Squad capability for per-agent LLM control — it deserves a dedicated feature page.

Why after Model Selection? The existing model-selection page covers directives and automatic routing. This new page goes deeper into the configuration layer (.squad/config.yaml, per-agent overrides, cost optimization playbook) — a natural progression.

Why separate from Model Selection? The current page is directive-focused (runtime). Issue #49 is configuration-focused (persistent setup, cost strategy). Splitting them keeps each page focused and lets users find the exact guidance they need.

Audience fit: Aligns with the target (Squad users managing multi-agent teams, cost-conscious teams) and is a quick-win for docs.

Supporting file changes

You'll want to:

1. Create docs/src/content/docs/features/model-pinning.md with the outline from issue content: Model Pinning in Squad: Control Which LLMs Power Your Agents #49
2. Update docs/src/navigation.ts line 45 to add the new nav item after model-selection
3. Add cross-links in features/model-selection.md and reference/config.md

[diberry]

Closing — docs PR shipped as bradygaster#644.