# /grid:model - Configure Model Selection

---
name: grid:model
description: Configure which Claude model to use for Grid agents
disable-model-invocation: true
argument-hint: "[quality|balanced|budget]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - AskUserQuestion
---

Configure which Claude models The Grid uses for its agents.

## USAGE

```
/grid:model                    # Show current config + options
/grid:model quality            # Use Opus for everything (best results, highest cost)
/grid:model balanced           # Use Sonnet for most tasks (good balance)
/grid:model budget             # Use Haiku where possible (lowest cost)
/grid:model custom             # Configure per-agent models
```

## MODEL TIERS

### QUALITY (Default)
All agents use **Opus** - best reasoning, highest quality output.

| Agent | Model |
|-------|-------|
| Planner | opus |
| Executor | opus |
| Recognizer | opus |
| Visual Inspector | opus |
| E2E Exerciser | opus |
| Persona Simulator | opus |

**Best for:** Complex projects, production code, when quality matters most.
**Cost:** ~3-5x more than Balanced.

### BALANCED
Most agents use **Sonnet** - good reasoning, moderate cost.

| Agent | Model |
|-------|-------|
| Planner | sonnet |
| Executor | sonnet |
| Recognizer | sonnet |
| Visual Inspector | sonnet |
| E2E Exerciser | sonnet |
| Persona Simulator | sonnet |

**Best for:** Most projects, good quality/cost tradeoff.
**Cost:** Baseline.

### BUDGET
Use **Haiku** where possible, Sonnet for complex reasoning.

| Agent | Model |
|-------|-------|
| Planner | sonnet (needs reasoning) |
| Executor | sonnet (needs reasoning) |
| Recognizer | haiku |
| Visual Inspector | haiku |
| E2E Exerciser | haiku |
| Persona Simulator | sonnet (needs reasoning) |

**Best for:** Prototypes, learning, cost-sensitive projects.
**Cost:** ~50-70% less than Balanced.

### CUSTOM
Set each agent individually.

## EXECUTION

When user runs `/grid:model`:

### No argument - Show current config
```
MODEL CONFIGURATION
═══════════════════

Current tier: {tier}

| Agent             | Model   |
|-------------------|---------|
| Planner           | {model} |
| Executor          | {model} |
| Recognizer        | {model} |
| Visual Inspector  | {model} |
| E2E Exerciser     | {model} |
| Persona Simulator | {model} |

Commands:
  /grid:model quality   - Opus for everything
  /grid:model balanced  - Sonnet for most
  /grid:model budget    - Haiku where possible
  /grid:model custom    - Configure individually

End of Line.
```

### With tier argument - Set tier
```python
# Read or create config
config_path = ".grid/config.json"
try:
    config = json.loads(read(config_path))
except:
    config = {}

# Set tier
config["model_tier"] = tier  # "quality" | "balanced" | "budget"

# Write config
write(config_path, json.dumps(config, indent=2))
```

Display:
```
MODEL TIER SET: {TIER}
═════════════════════

All Grid agents will now use {tier} models.

| Agent             | Model   |
|-------------------|---------|
| Planner           | {model} |
| ...               | ...     |

To change: /grid:model {other_tier}

End of Line.
```

### Custom mode - Interactive selection
Use AskUserQuestion to let user pick model for each agent type:

```
CUSTOM MODEL CONFIGURATION
══════════════════════════

Select model for each agent type:
```

Then save to `.grid/config.json`:
```json
{
  "model_tier": "custom",
  "models": {
    "planner": "opus",
    "executor": "sonnet",
    "recognizer": "haiku",
    "visual_inspector": "haiku",
    "e2e_exerciser": "haiku",
    "persona_simulator": "sonnet"
  }
}
```

## CONFIG FILE FORMAT

`.grid/config.json`:
```json
{
  "model_tier": "quality",
  "models": {
    "planner": "opus",
    "executor": "opus",
    "recognizer": "opus",
    "visual_inspector": "opus",
    "e2e_exerciser": "opus",
    "persona_simulator": "opus"
  },
  "topology": "hierarchical",
  "dynamic_routing": true,
  "routing_table": {
    "quality": {
      "complex": "opus",
      "medium": "opus",
      "simple": "sonnet"
    },
    "balanced": {
      "complex": "opus",
      "medium": "sonnet",
      "simple": "haiku"
    },
    "budget": {
      "complex": "sonnet",
      "medium": "haiku",
      "simple": "haiku"
    }
  }
}
```

## DYNAMIC MODEL ROUTING

**NEW in v1.7:** The Grid now assesses task complexity and routes to the optimal model automatically.

### How It Works

Instead of assigning the same model to all tasks based on tier, MC analyzes each task before spawning:

1. **Assess Complexity** - Score task based on file count, keywords, type, dependencies
2. **Consult Routing Table** - Map (tier, complexity) to optimal model
3. **Spawn with Model** - Use the routed model for the spawn
4. **Log Savings** - Track cost savings from dynamic routing

### Complexity Factors

| Factor | Score | Description |
|--------|-------|-------------|
| File count > 5 | +2 | Many files indicates cross-cutting work |
| File count > 2 | +1 | Moderate scope |
| Complex keywords (2+) | +2 | auth, payment, migration, security, etc. |
| Complex keywords (1) | +1 | Single complex domain |
| Design/planning task | +2 | Needs strong reasoning |
| Cross-cutting concern | +1 | Affects multiple subsystems |
| Dependencies > 3 | +1 | Complex dependency chain |

**Scoring:**
- Score >= 4: **complex**
- Score >= 2: **medium**
- Score < 2: **simple**

### Complex Keywords

Tasks containing these keywords get higher complexity scores:

```
auth, authentication, authorization
payment, billing, stripe, checkout
migration, migrate, schema
security, encryption, jwt, oauth
refactor, rewrite, redesign
architecture, infrastructure
database, postgres, mysql, mongodb
performance, optimization, caching
distributed, concurrent, async
```

### Routing Table

The default routing table (configurable in `.grid/config.json`):

| Tier | Complex | Medium | Simple |
|------|---------|--------|--------|
| **Quality** | opus | opus | sonnet |
| **Balanced** | opus | sonnet | haiku |
| **Budget** | sonnet | haiku | haiku |

**Key insight:** Quality tier downgrades simple tasks to Sonnet for speed. Balanced tier upgrades complex tasks to Opus for quality.

### Cost Savings Examples

| Task | Tier | Old Model | New Model | Savings |
|------|------|-----------|-----------|---------|
| Update README | quality | opus | sonnet | ~80% |
| Fix typo | quality | opus | sonnet | ~80% |
| Add config | balanced | sonnet | haiku | ~75% |
| Auth system | balanced | sonnet | opus | -400% (upgrade) |
| DB migration | budget | sonnet | sonnet | 0% |

**Note:** Upgrades cost more but improve quality on complex tasks.

### Disable Dynamic Routing

To use static tier-based routing instead:

```bash
# Environment variable
export GRID_DYNAMIC_ROUTING=false

# Or in config
{
  "dynamic_routing": false
}
```

### Custom Routing Table

Override the default routing in `.grid/config.json`:

```json
{
  "routing_table": {
    "quality": {
      "complex": "opus",
      "medium": "opus",
      "simple": "opus"  // Never downgrade
    },
    "balanced": {
      "complex": "opus",
      "medium": "sonnet",
      "simple": "sonnet"  // Don't use haiku
    }
  }
}
```

## ENVIRONMENT VARIABLE SUPPORT

The Grid respects Claude Code's native environment variables and Grid-specific variables:

### Configuration Priority (highest first)
1. `GRID_MODEL_TIER` - Grid's model tier environment variable
2. `CLAUDE_CODE_SUBAGENT_MODEL` - Claude Code's native subagent model override
3. `.claude/settings.local.json` - Local project settings
4. `.claude/settings.json` - Project settings
5. `~/.claude/settings.json` - User settings
6. `.grid/config.json` - Legacy Grid config

### Environment Variables

| Variable | Description |
|----------|-------------|
| `GRID_MODEL_TIER` | Set to `quality`, `balanced`, or `budget` |
| `CLAUDE_CODE_SUBAGENT_MODEL` | Override model for ALL subagents (takes precedence) |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Model for `opus` alias |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Model for `sonnet` alias |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Model for `haiku` alias |

### Usage

```bash
# Temporary (single session)
GRID_MODEL_TIER=budget claude

# Permanent (add to shell profile)
export GRID_MODEL_TIER=balanced

# Use Claude Code's native override
export CLAUDE_CODE_SUBAGENT_MODEL=claude-3-5-sonnet-20241022
```

When showing current configuration, also display:
```
Environment Overrides:
  GRID_MODEL_TIER:            {value or "(not set)"}
  CLAUDE_CODE_SUBAGENT_MODEL: {value or "(not set)"}
```

## RULES

1. Default to "quality" (Opus) if no config exists
2. Never use Haiku for Planner/Executor (needs reasoning capability)
3. Show cost implications when changing tiers
4. Config persists in `.grid/config.json`
5. Environment variables ALWAYS override config file settings
6. `CLAUDE_CODE_SUBAGENT_MODEL` overrides ALL model selections when set

End of Line.