docs: add agent-model matching guide for newcomers
- Add docs/guide/agent-model-matching.md with TL;DR table, detailed breakdown per agent, configuration examples, decision tree, common pitfalls, and default fallback chains - Update README.md to reference the guide in TOC, Just Install This section, and Features overview
This commit is contained in:
YeonGyu-Kim
@@ -115,6 +115,7 @@ Yes, technically possible. But I cannot recommend using it.
|
||||
- [🪄 The Magic Word: `ultrawork`](#-the-magic-word-ultrawork)
|
||||
- [For Those Who Want to Read: Meet Sisyphus](#for-those-who-want-to-read-meet-sisyphus)
|
||||
- [Just Install This](#just-install-this)
|
||||
- [Which Model Should I Use?](#which-model-should-i-use)
|
||||
- [For Those Who Want Autonomy: Meet Hephaestus](#for-those-who-want-autonomy-meet-hephaestus)
|
||||
- [Installation](#installation)
|
||||
- [For Humans](#for-humans)
|
||||
@@ -222,6 +223,10 @@ Need to look something up? It scours official docs, your entire codebase history
|
||||
|
||||
If you don't want all this, as mentioned, you can just pick and choose specific features.
|
||||
|
||||
#### Which Model Should I Use?
|
||||
|
||||
New to oh-my-opencode and not sure which model to pair with which agent? Check the **[Agent-Model Matching Guide](docs/guide/agent-model-matching.md)** — a quick reference for newcomers covering recommended models, fallback chains, and common pitfalls for each agent.
|
||||
|
||||
### For Those Who Want Autonomy: Meet Hephaestus
|
||||
|
||||
|
||||
@@ -307,6 +312,7 @@ See the full [Features Documentation](docs/features.md) for detailed information
|
||||
- **Built-in MCPs**: websearch (Exa), context7 (docs), grep_app (GitHub search)
|
||||
- **Session Tools**: List, read, search, and analyze session history
|
||||
- **Productivity Features**: Ralph Loop, Todo Enforcer, Comment Checker, Think Mode, and more
|
||||
- **[Agent-Model Matching Guide](docs/guide/agent-model-matching.md)**: Which model works best with which agent
|
||||
|
||||
## Configuration
|
||||
|
||||
|
||||
166
docs/guide/agent-model-matching.md
Normal file
166
docs/guide/agent-model-matching.md
Normal file
@@ -0,0 +1,166 @@
|
||||
# Agent-Model Matching Guide for Newcomers
|
||||
|
||||
> **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.
|
||||
|
||||
---
|
||||
|
||||
## TL;DR
|
||||
|
||||
| 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** | Claude Opus, GPT-5.2+ | — |
|
||||
|
||||
---
|
||||
|
||||
## Detailed Breakdown
|
||||
|
||||
### Sisyphus (ultraworker)
|
||||
**Purpose**: Primary orchestrator for complex multi-step tasks
|
||||
|
||||
**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
|
||||
|
||||
**⚠️ NEVER USE GPT** — Sisyphus is optimized for Claude-style models and performs poorly on GPT.
|
||||
|
||||
**Configuration Example**:
|
||||
```json
|
||||
{
|
||||
"agent": {
|
||||
"sisyphus": {
|
||||
"model": "anthropic/claude-opus-4-6",
|
||||
"variant": "max"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Hephaestus (deep worker)
|
||||
**Purpose**: Deep coding tasks requiring extensive reasoning
|
||||
|
||||
**Required Model**: **GPT-5.3-codex** (always)
|
||||
|
||||
Think of Hephaestus as "Codex on steroids" — it's specifically designed and tuned for GPT models.
|
||||
|
||||
**⚠️ DO NOT USE** if you don't have GPT access. DeepSeek *might* work but is not officially supported.
|
||||
|
||||
**Configuration Example**:
|
||||
```json
|
||||
{
|
||||
"agent": {
|
||||
"hephaestus": {
|
||||
"model": "openai/gpt-5.3-codex",
|
||||
"variant": "medium"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Prometheus (planner)
|
||||
**Purpose**: Strategic planning and work plan generation
|
||||
|
||||
**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**:
|
||||
1. **Claude Opus-4-6** — Best performance (recommended)
|
||||
2. **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": "anthropic/claude-opus-4-6"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Decision Tree
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
## Model Fallback Chains (Default Behavior)
|
||||
|
||||
The system will automatically fall back through these chains if your preferred model is unavailable:
|
||||
|
||||
**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
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [AGENTS.md](../AGENTS.md) — Full agent documentation
|
||||
- [configurations.md](./configurations.md) — Configuration reference
|
||||
- [orchestration-guide.md](./orchestration-guide.md) — How orchestration works
|
||||
Reference in New Issue
Block a user