docs: rewrite agent-model matching as technical guide for agents
Rewrite agent-model-matching.md as a technical reference that: - Documents actual fallback chains from model-requirements.ts - Explains model-specific prompt routing (Prometheus/Atlas GPT detection) - Covers safe vs dangerous model substitutions with rationale - Includes task categories (visual-engineering, deep, quick, etc.) - Guides agents on how to explain model choices to users - Adds provider priority chain Also update installation.md to reference the guide when users want custom model configuration, with explanation of what is safe to change and why.
This commit is contained in:
YeonGyu-Kim
@@ -1,167 +1,177 @@
|
||||
# Agent-Model Matching Guide for Newcomers
|
||||
# Agent-Model Matching Guide
|
||||
|
||||
> **Quick Reference**: Which model to use with which agent for the best results
|
||||
|
||||
This guide helps you match the right AI model to each oh-my-opencode agent based on real-world usage and testing.
|
||||
> **For agents and users**: This document explains the principles behind oh-my-opencode's agent-model assignments. Use it to understand why each agent uses a specific model, and how to customize them correctly.
|
||||
|
||||
---
|
||||
|
||||
## TL;DR
|
||||
## Why Model Matching Matters
|
||||
|
||||
| Agent | Best Models | Avoid |
|
||||
|-------|-------------|-------|
|
||||
| **Sisyphus** | Claude Opus, Sonnet, Kimi K2.5, GLM 5 | GPT ❌ |
|
||||
| **Hephaestus** | GPT-5.3-codex only | Non-GPT ❌ |
|
||||
| **Prometheus** | Claude Opus | GPT (untested) |
|
||||
| **Atlas** | Kimi K2.5, Claude Sonnet, GPT-5.2+ | — |
|
||||
Each oh-my-opencode agent has a **dedicated system prompt** optimized for a specific model family. Some agents (Atlas, Prometheus) ship separate prompts for GPT vs Claude models, with automatic routing via `isGptModel()` detection. Assigning the wrong model family to an agent doesn't just degrade performance — the agent may receive instructions formatted for a completely different model's reasoning style.
|
||||
|
||||
**Key principle**: Agents are tuned to model families, not individual models. A Claude-tuned agent works with Opus, Sonnet, or Haiku. A GPT-tuned agent works with GPT-5.2 or GPT-5.3-codex. Crossing families requires a model-specific prompt (which only some agents have).
|
||||
|
||||
---
|
||||
|
||||
## Detailed Breakdown
|
||||
## Agent-Model Map (Source of Truth)
|
||||
|
||||
### Sisyphus (ultraworker)
|
||||
**Purpose**: Primary orchestrator for complex multi-step tasks
|
||||
This table reflects the actual fallback chains in `src/shared/model-requirements.ts`. The first available model in the chain is used.
|
||||
|
||||
**Recommended Models** (in order of preference):
|
||||
1. **Claude Opus-4-6** — The best overall performance
|
||||
2. **Claude Sonnet-4-6** — Satisfiable, often better than pure Claude Code + Opus
|
||||
3. **Kimi K2.5** — Good for broad tasks, excellent cost-performance
|
||||
4. **GLM 5** — Good for various tasks, not as capable on broad tasks as Kimi
|
||||
5. **MiniMax** — Budget option when cost matters
|
||||
### Core Agents
|
||||
|
||||
**⚠️ NEVER USE GPT** — Sisyphus is optimized for Claude-style models and performs poorly on GPT.
|
||||
| Agent | Role | Primary Model Family | Fallback Chain | Has GPT Prompt? |
|
||||
|-------|------|---------------------|----------------|-----------------|
|
||||
| **Sisyphus** | Main ultraworker | Claude | Opus → Kimi K2.5 → GLM 5 → Big Pickle | No — **never use GPT** |
|
||||
| **Hephaestus** | Deep autonomous worker | GPT (only) | GPT-5.3-codex (medium) | N/A (GPT-native) |
|
||||
| **Prometheus** | Strategic planner | Claude (default), GPT (auto-detected) | Opus → GPT-5.2 → Kimi K2.5 → Gemini 3 Pro | **Yes** — `src/agents/prometheus/gpt.ts` |
|
||||
| **Atlas** | Todo orchestrator | Kimi K2.5 (default), GPT (auto-detected) | Kimi K2.5 → Sonnet → GPT-5.2 | **Yes** — `src/agents/atlas/gpt.ts` |
|
||||
| **Oracle** | Architecture/debugging | GPT | GPT-5.2 → Gemini 3 Pro → Opus | No |
|
||||
| **Metis** | Plan review consultant | Claude | Opus → Kimi K2.5 → GPT-5.2 → Gemini 3 Pro | No |
|
||||
| **Momus** | High-accuracy reviewer | GPT | GPT-5.2 → Opus → Gemini 3 Pro | No |
|
||||
|
||||
**Configuration Example**:
|
||||
```json
|
||||
### Utility Agents
|
||||
|
||||
| Agent | Role | Primary Model Family | Fallback Chain |
|
||||
|-------|------|---------------------|----------------|
|
||||
| **Explore** | Fast codebase grep | Grok/lightweight | Grok Code Fast 1 → MiniMax M2.5 → Haiku → GPT-5-nano |
|
||||
| **Librarian** | Docs/code search | Lightweight | MiniMax M2.5 → Gemini 3 Flash → Big Pickle |
|
||||
| **Multimodal Looker** | Vision/screenshots | Kimi/multimodal | Kimi K2.5 → Gemini 3 Flash → GPT-5.2 → GLM-4.6v |
|
||||
|
||||
### Task Categories
|
||||
|
||||
Categories are used for `background_task` and `delegate_task` dispatching:
|
||||
|
||||
| Category | Purpose | Primary Model | Notes |
|
||||
|----------|---------|---------------|-------|
|
||||
| `visual-engineering` | Frontend/UI work | Gemini 3 Pro | Gemini excels at visual tasks |
|
||||
| `ultrabrain` | Maximum intelligence | GPT-5.3-codex (xhigh) | Highest reasoning variant |
|
||||
| `deep` | Deep coding | GPT-5.3-codex (medium) | Requires GPT availability |
|
||||
| `artistry` | Creative/design | Gemini 3 Pro | Requires Gemini availability |
|
||||
| `quick` | Fast simple tasks | Claude Haiku | Cheapest, fastest |
|
||||
| `unspecified-high` | General high-quality | Claude Opus | Default for complex tasks |
|
||||
| `unspecified-low` | General standard | Claude Sonnet | Default for standard tasks |
|
||||
| `writing` | Text/docs | Kimi K2.5 | Best prose quality |
|
||||
|
||||
---
|
||||
|
||||
## Model-Specific Prompt Routing
|
||||
|
||||
### How It Works
|
||||
|
||||
Some agents detect the assigned model at runtime and switch prompts:
|
||||
|
||||
```typescript
|
||||
// From src/agents/prometheus/system-prompt.ts
|
||||
export function getPrometheusPrompt(model?: string): string {
|
||||
if (model && isGptModel(model)) return getGptPrometheusPrompt() // XML-tagged, principle-driven
|
||||
return PROMETHEUS_SYSTEM_PROMPT // Claude-optimized, modular sections
|
||||
}
|
||||
```
|
||||
|
||||
**Agents with dual prompts:**
|
||||
- **Prometheus**: Claude prompt (modular sections) vs GPT prompt (XML-tagged, Codex plan mode style with explicit decision criteria)
|
||||
- **Atlas**: Claude prompt vs GPT prompt (GPT-optimized todo orchestration)
|
||||
|
||||
**Why this matters for customization**: If you override Prometheus to use a GPT model, the GPT prompt activates automatically. But if you override Sisyphus to use GPT — there is no GPT prompt, and performance will degrade significantly.
|
||||
|
||||
### Model Family Detection
|
||||
|
||||
`isGptModel()` matches:
|
||||
- Any model starting with `openai/` or `github-copilot/gpt-`
|
||||
- Model names starting with common GPT prefixes (`gpt-`, `o1-`, `o3-`, `o4-`, `codex-`)
|
||||
|
||||
Everything else is treated as "Claude-like" (Claude, Kimi, GLM, Gemini).
|
||||
|
||||
---
|
||||
|
||||
## Customization Guide
|
||||
|
||||
### When to Customize
|
||||
|
||||
Customize model assignments when:
|
||||
- You have a specific provider subscription (e.g., only OpenAI, no Anthropic)
|
||||
- You want to use a cheaper model for certain agents
|
||||
- You're experimenting with new models
|
||||
|
||||
### How to Customize
|
||||
|
||||
Override in `oh-my-opencode.json` (user: `~/.config/opencode/oh-my-opencode.json`, project: `.opencode/oh-my-opencode.json`):
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"agent": {
|
||||
"sisyphus": {
|
||||
"model": "anthropic/claude-opus-4-6",
|
||||
"variant": "max"
|
||||
}
|
||||
"agents": {
|
||||
"sisyphus": { "model": "kimi-for-coding/k2p5" },
|
||||
"atlas": { "model": "anthropic/claude-sonnet-4-6" },
|
||||
"prometheus": { "model": "openai/gpt-5.2" } // Will auto-switch to GPT prompt
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
### Safe Substitutions (same model family)
|
||||
|
||||
### Hephaestus (deep worker)
|
||||
**Purpose**: Deep coding tasks requiring extensive reasoning
|
||||
These swaps are safe because they stay within the same prompt family:
|
||||
|
||||
**Required Model**: **GPT-5.3-codex** (always)
|
||||
| Agent | Default | Safe Alternatives |
|
||||
|-------|---------|-------------------|
|
||||
| **Sisyphus** | Claude Opus | Claude Sonnet, Kimi K2.5, GLM 5 (any Claude-like) |
|
||||
| **Hephaestus** | GPT-5.3-codex | No alternatives — GPT only |
|
||||
| **Prometheus** | Claude Opus | Claude Sonnet (Claude prompt) OR GPT-5.2 (auto-switches to GPT prompt) |
|
||||
| **Atlas** | Kimi K2.5 | Claude Sonnet (Claude prompt) OR GPT-5.2 (auto-switches to GPT prompt) |
|
||||
| **Oracle** | GPT-5.2 | Gemini 3 Pro, Claude Opus |
|
||||
|
||||
Think of Hephaestus as "Codex on steroids" — it's specifically designed and tuned for GPT models.
|
||||
### Dangerous Substitutions (cross-family without prompt support)
|
||||
|
||||
**⚠️ DO NOT USE** if you don't have GPT access. DeepSeek *might* work but is not officially supported.
|
||||
| Agent | Dangerous Override | Why |
|
||||
|-------|-------------------|-----|
|
||||
| **Sisyphus** → GPT | No GPT-optimized prompt exists. Sisyphus is deeply tuned for Claude-style reasoning. Performance drops dramatically. |
|
||||
| **Hephaestus** → Claude | Hephaestus is purpose-built for GPT's Codex capabilities. Claude cannot replicate this. |
|
||||
| **Explore** → Opus | Massive overkill and cost waste. Explore needs speed, not intelligence. |
|
||||
|
||||
**Configuration Example**:
|
||||
```json
|
||||
{
|
||||
"agent": {
|
||||
"hephaestus": {
|
||||
"model": "openai/gpt-5.3-codex",
|
||||
"variant": "medium"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
### Explaining to Users
|
||||
|
||||
When a user asks about model configuration, explain:
|
||||
|
||||
1. **The default works out of the box** — the installer configures optimal models based on their subscriptions
|
||||
2. **Each agent has a "home" model family** — Sisyphus is Claude-native, Hephaestus is GPT-native
|
||||
3. **Some agents auto-adapt** — Prometheus and Atlas detect GPT models and switch to optimized prompts
|
||||
4. **Cross-family overrides are risky** — unless the agent has a dedicated prompt for that family
|
||||
5. **Cost optimization is valid** — swapping Opus → Sonnet or Kimi K2.5 for Sisyphus is fine and saves money
|
||||
6. **Point to this guide** for the full fallback chains and rationale
|
||||
|
||||
---
|
||||
|
||||
### Prometheus (planner)
|
||||
**Purpose**: Strategic planning and work plan generation
|
||||
## Provider Priority
|
||||
|
||||
**Recommended Model**: **Claude Opus-4-6** (strongly recommended)
|
||||
|
||||
Prometheus is optimized for Claude's reasoning capabilities. GPT compatibility is not yet tested but may be evaluated in the future.
|
||||
|
||||
**Configuration Example**:
|
||||
```json
|
||||
{
|
||||
"agent": {
|
||||
"plan": {
|
||||
"model": "anthropic/claude-opus-4-6",
|
||||
"variant": "max"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Atlas (orchestrator)
|
||||
**Purpose**: Todo list orchestration and multi-agent coordination
|
||||
|
||||
**Recommended Models** (in order of preference):
|
||||
1. **Kimi K2.5** — Best for Atlas orchestration
|
||||
2. **Claude Sonnet-4-6** — Strong alternative
|
||||
3. **GPT-5.2+** — Good enough, has GPT-optimized prompt
|
||||
|
||||
Atlas has model-specific prompt detection and will automatically use GPT-optimized instructions when running on GPT models.
|
||||
|
||||
**Configuration Example**:
|
||||
```json
|
||||
{
|
||||
"agent": {
|
||||
"atlas": {
|
||||
"model": "kimi/kimi-k2.5"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Decision Tree
|
||||
When multiple providers are available, oh-my-opencode prefers:
|
||||
|
||||
```
|
||||
Do you have GPT access?
|
||||
├── YES → Use Hephaestus for deep coding, Atlas for orchestration
|
||||
└── NO → Use Sisyphus (Claude/Kimi/GLM) for all tasks
|
||||
|
||||
Need planning/strategy?
|
||||
├── YES → Use Prometheus (Claude Opus recommended)
|
||||
└── NO → Skip Prometheus, use other agents directly
|
||||
|
||||
Complex multi-step task?
|
||||
├── YES → Use Sisyphus (Claude-family models)
|
||||
└── NO → Use category-specific agents or Hephaestus
|
||||
Native (anthropic/, openai/, google/) > Kimi for Coding > GitHub Copilot > OpenCode Zen > Z.ai Coding Plan
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Pitfalls to Avoid
|
||||
|
||||
1. **Don't use GPT with Sisyphus** — Performance will be subpar
|
||||
2. **Don't use non-GPT with Hephaestus** — It's specifically built for GPT
|
||||
3. **Don't force Prometheus on GPT** — It's untested; use Claude for now
|
||||
4. **Don't overthink Atlas** — It adapts automatically to your model
|
||||
Each fallback chain entry specifies which providers can serve that model. The system picks the first entry where at least one provider is connected.
|
||||
|
||||
---
|
||||
|
||||
## Model Fallback Chains (Default Behavior)
|
||||
## Quick Decision Tree for Users
|
||||
|
||||
The system will automatically fall back through these chains if your preferred model is unavailable:
|
||||
```
|
||||
What subscriptions do you have?
|
||||
|
||||
**Sisyphus**: Opus → Kimi K2.5 → GLM 4.7 → Big Pickle
|
||||
**Hephaestus**: GPT-5.3-codex only (no fallback)
|
||||
**Prometheus**: Opus → Kimi K2.5 → GLM 4.7 → GPT-5.2 → Gemini 3 Pro
|
||||
**Atlas**: Kimi K2.5 → GLM 4.7 → Opus → GPT-5.2 → Gemini 3 Pro
|
||||
├── Claude (Anthropic) → Sisyphus works optimally. Prometheus/Metis use Claude prompts.
|
||||
├── OpenAI/ChatGPT → Hephaestus unlocked. Oracle/Momus use GPT. Prometheus auto-switches.
|
||||
├── Both Claude + OpenAI → Full agent roster. Best experience.
|
||||
├── Gemini only → Visual-engineering category excels. Other agents use Gemini as fallback.
|
||||
├── GitHub Copilot only → Works as fallback provider for all model families.
|
||||
├── OpenCode Zen only → Free-tier access to multiple models. Functional but rate-limited.
|
||||
└── No subscription → Limited functionality. Consider OpenCode Zen (free).
|
||||
|
||||
---
|
||||
|
||||
## Tips for Newcomers
|
||||
|
||||
- **Start with Sisyphus + Claude Opus** for general tasks
|
||||
- **Use Hephaestus when you need deep reasoning** (requires GPT)
|
||||
- **Try GLM 5 or Kimi K2.5** for cost-effective alternatives to Claude
|
||||
- **Check the model requirements** in your config to avoid mismatches
|
||||
- **Use `variant: "max"` or `variant: "high"`** for best results on capable models
|
||||
For each user scenario, the installer (`bunx oh-my-opencode install`) auto-configures the optimal assignment.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [AGENTS.md](../AGENTS.md) — Full agent documentation
|
||||
- [configurations.md](./configurations.md) — Configuration reference
|
||||
- [orchestration-guide.md](./orchestration-guide.md) — How orchestration works
|
||||
- [Installation Guide](./installation.md) — Setup with subscription-based model configuration
|
||||
- [Configuration Reference](../configurations.md) — Full config options including agent overrides
|
||||
- [Overview](./overview.md) — How the agent system works
|
||||
- [`src/shared/model-requirements.ts`](../../src/shared/model-requirements.ts) — Source of truth for fallback chains
|
||||
|
||||
Reference in New Issue
Block a user