diff --git a/README.md b/README.md index aa134f808..5a1e7a617 100644 --- a/README.md +++ b/README.md @@ -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 ![Meet Hephaestus](.github/assets/hephaestus.png) @@ -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 diff --git a/docs/guide/agent-model-matching.md b/docs/guide/agent-model-matching.md new file mode 100644 index 000000000..c78aa0b91 --- /dev/null +++ b/docs/guide/agent-model-matching.md @@ -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