From d9ee0d9c0db8a5743968fe12acae57b47b7a93c3 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Thu, 19 Feb 2026 15:01:34 +0900 Subject: [PATCH] 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. --- docs/guide/agent-model-matching.md | 262 +++++++++++++++-------------- docs/guide/installation.md | 12 ++ 2 files changed, 148 insertions(+), 126 deletions(-) diff --git a/docs/guide/agent-model-matching.md b/docs/guide/agent-model-matching.md index 3d6e24943..27fce9b66 100644 --- a/docs/guide/agent-model-matching.md +++ b/docs/guide/agent-model-matching.md @@ -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 diff --git a/docs/guide/installation.md b/docs/guide/installation.md index 051887c2d..e8d27cf54 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -259,6 +259,18 @@ opencode auth login The plugin works perfectly by default. Do not change settings or turn off features without an explicit request. +### Custom Model Configuration + +If the user wants to override which model an agent uses, refer to the **[Agent-Model Matching Guide](./agent-model-matching.md)** before making changes. That guide explains: + +- **Why each agent uses its default model** — prompt optimization, model family compatibility +- **Which substitutions are safe** — staying within the same model family (e.g., Opus → Sonnet for Sisyphus) +- **Which substitutions are dangerous** — crossing model families without prompt support (e.g., GPT for Sisyphus) +- **How auto-routing works** — Prometheus and Atlas detect GPT models and switch to GPT-optimized prompts automatically +- **Full fallback chains** — what happens when the preferred model is unavailable + +Always explain to the user *why* a model is assigned to an agent when making custom changes. The guide provides the rationale for every assignment. + ### Verify the setup Read this document again, think about you have done everything correctly.