docs: reorganize overview.md for better first-time user experience
- Add Quick Start section with clear installation link - Add 'How It Works: Agent Orchestration' section linking to orchestration.md - Add 'Agent Model Matching' section with JSON configuration examples - Restructure content flow for better readability - Add example JSON config to agent-model-matching.md - Maintain original voice and strong opinions while improving organization - All links now properly reference related docs
This commit is contained in:
YeonGyu-Kim
@@ -2,9 +2,58 @@
|
||||
|
||||
> **For agents and users**: How to pick the right model for each agent. Read this before customizing model settings.
|
||||
|
||||
Run `opencode models` to see all available models on your system, and `opencode auth login` to authenticate with providers.
|
||||
## Example Configuration
|
||||
|
||||
---
|
||||
Here's a practical example configuration showing agent-model assignments:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
|
||||
|
||||
"agents": {
|
||||
// Main orchestrator: Claude Opus or Kimi K2.5 work best
|
||||
"sisyphus": {
|
||||
"model": "kimi-for-coding/k2p5",
|
||||
"ultrawork": { "model": "anthropic/claude-opus-4-6", "variant": "max" }
|
||||
},
|
||||
|
||||
// Research agents: cheaper models are fine
|
||||
"librarian": { "model": "zai-coding-plan/glm-4.7" },
|
||||
"explore": { "model": "github-copilot/grok-code-fast-1" },
|
||||
|
||||
// Architecture consultation: GPT or Claude Opus
|
||||
"oracle": { "model": "openai/gpt-5.2", "variant": "high" },
|
||||
|
||||
// Prometheus inherits sisyphus model; just add prompt guidance
|
||||
"prometheus": { "prompt_append": "Leverage deep & quick agents heavily, always in parallel." }
|
||||
},
|
||||
|
||||
"categories": {
|
||||
// quick — trivial tasks
|
||||
"quick": { "model": "opencode/gpt-5-nano" },
|
||||
|
||||
// unspecified-low — moderate tasks
|
||||
"unspecified-low": { "model": "kimi-for-coding/k2p5" },
|
||||
|
||||
// unspecified-high — complex work
|
||||
"unspecified-high": { "model": "anthropic/claude-sonnet-4-6", "variant": "max" },
|
||||
|
||||
// visual-engineering — Gemini dominates visual tasks
|
||||
"visual-engineering": { "model": "google/gemini-3-pro", "variant": "high" },
|
||||
|
||||
// writing — docs/prose
|
||||
"writing": { "model": "kimi-for-coding/k2p5" }
|
||||
},
|
||||
|
||||
// Limit expensive providers; let cheap ones run freely
|
||||
"background_task": {
|
||||
"providerConcurrency": { "anthropic": 3, "openai": 3, "opencode": 10, "zai-coding-plan": 10 },
|
||||
"modelConcurrency": { "anthropic/claude-opus-4-6": 2, "opencode/gpt-5-nano": 20 }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Run `opencode models` to see all available models on your system, and `opencode auth login` to authenticate with providers.
|
||||
|
||||
## Model Families: Know Your Options
|
||||
|
||||
|
||||
@@ -8,7 +8,34 @@ Just better results, cheaper models, real orchestration.
|
||||
|
||||
---
|
||||
|
||||
## The Old Framing Is Dead
|
||||
## Quick Start
|
||||
|
||||
### Installation
|
||||
|
||||
Paste this into your LLM agent session:
|
||||
|
||||
```
|
||||
Install and configure oh-my-opencode by following the instructions here:
|
||||
https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/refs/heads/master/docs/guide/installation.md
|
||||
```
|
||||
|
||||
Or read the full [Installation Guide](./installation.md) for manual setup, provider authentication, and troubleshooting.
|
||||
|
||||
### Your First Task
|
||||
|
||||
Once installed, just type:
|
||||
|
||||
```
|
||||
ultrawork
|
||||
```
|
||||
|
||||
That's it. The agent figures everything out — explores your codebase, researches patterns, implements the feature, verifies with diagnostics. Keeps working until done.
|
||||
|
||||
Want more control? Press **Tab** to enter [Prometheus mode](./orchestration.md) for interview-based planning, then run `/start-work` for full orchestration.
|
||||
|
||||
---
|
||||
|
||||
## The Philosophy: Breaking Free
|
||||
|
||||
We used to call this "Claude Code on steroids." That was wrong.
|
||||
|
||||
@@ -18,6 +45,33 @@ Oh My OpenCode doesn't play that game. It orchestrates across models, picking th
|
||||
|
||||
---
|
||||
|
||||
## How It Works: Agent Orchestration
|
||||
|
||||
Instead of one agent doing everything, Oh My OpenCode uses **specialized agents that delegate to each other** based on task type.
|
||||
|
||||
**The Architecture:**
|
||||
|
||||
```
|
||||
User Request
|
||||
↓
|
||||
[Intent Gate] — Classifies what you actually want
|
||||
↓
|
||||
[Sisyphus] — Main orchestrator, plans and delegates
|
||||
↓
|
||||
├─→ [Prometheus] — Strategic planning (interview mode)
|
||||
├─→ [Atlas] — Todo orchestration and execution
|
||||
├─→ [Oracle] — Architecture consultation
|
||||
├─→ [Librarian] — Documentation/code search
|
||||
├─→ [Explore] — Fast codebase grep
|
||||
└─→ [Category-based agents] — Specialized by task type
|
||||
```
|
||||
|
||||
When Sisyphus delegates to a subagent, it doesn't pick a model name. It picks a **category** — `visual-engineering`, `ultrabrain`, `quick`, `deep`. The category automatically maps to the right model. You touch nothing.
|
||||
|
||||
For a deep dive into how agents collaborate, see the [Orchestration System Guide](./orchestration.md).
|
||||
|
||||
---
|
||||
|
||||
## Meet the Agents
|
||||
|
||||
### Sisyphus: The Discipline Agent
|
||||
@@ -27,10 +81,10 @@ Named after the Greek myth. He rolls the boulder every day. Never stops. Never g
|
||||
Sisyphus is your main orchestrator. He plans, delegates to specialists, and drives tasks to completion with aggressive parallel execution. He doesn't stop halfway. He doesn't get distracted. He finishes.
|
||||
|
||||
**Recommended models:**
|
||||
- **Claude Opus 4.6** - Best overall experience. Sisyphus was built with Claude-optimized prompts.
|
||||
- **Claude Sonnet 4.6** - Good balance of capability and cost.
|
||||
- **Kimi K2.5** - Great Claude-like alternative. Many users run this combo exclusively.
|
||||
- **GLM 5** - Solid option, especially via Z.ai.
|
||||
- **Claude Opus 4.6** — Best overall experience. Sisyphus was built with Claude-optimized prompts.
|
||||
- **Claude Sonnet 4.6** — Good balance of capability and cost.
|
||||
- **Kimi K2.5** — Great Claude-like alternative. Many users run this combo exclusively.
|
||||
- **GLM 5** — Solid option, especially via Z.ai.
|
||||
|
||||
Sisyphus has Claude-optimized prompts. No GPT prompt exists for Sisyphus. Claude-family models work best because that's what the prompts were engineered for.
|
||||
|
||||
@@ -44,41 +98,38 @@ Use Hephaestus when you need deep architectural reasoning, complex debugging acr
|
||||
|
||||
**Why this beats vanilla Codex CLI:**
|
||||
|
||||
**Multi-model orchestration.** Pure Codex is single-model. OmO routes different tasks to different models automatically. GPT for deep reasoning. Gemini for frontend. Haiku for speed. The right brain for the right job.
|
||||
**Background agents.** Fire 5+ agents in parallel. Something Codex simply cannot do. While one agent writes code, another researches patterns, another checks documentation. Like a real dev team.
|
||||
**Category system.** Tasks are routed by intent, not model name. `visual-engineering` gets Gemini. `ultrabrain` gets GPT-5.3 Codex. `quick` gets Haiku. No manual juggling.
|
||||
**Accumulated wisdom.** Subagents learn from previous results. Conventions discovered in task 1 are passed to task 5. Mistakes made early aren't repeated. The system gets smarter as it works.
|
||||
- **Multi-model orchestration.** Pure Codex is single-model. OmO routes different tasks to different models automatically. GPT for deep reasoning. Gemini for frontend. Haiku for speed. The right brain for the right job.
|
||||
- **Background agents.** Fire 5+ agents in parallel. Something Codex simply cannot do. While one agent writes code, another researches patterns, another checks documentation. Like a real dev team.
|
||||
- **Category system.** Tasks are routed by intent, not model name. `visual-engineering` gets Gemini. `ultrabrain` gets GPT-5.3 Codex. `quick` gets Haiku. No manual juggling.
|
||||
- **Accumulated wisdom.** Subagents learn from previous results. Conventions discovered in task 1 are passed to task 5. Mistakes made early aren't repeated. The system gets smarter as it works.
|
||||
|
||||
### Prometheus: The Strategic Planner
|
||||
|
||||
Prometheus interviews you like a real engineer. Asks clarifying questions. Identifies scope and ambiguities. Builds a detailed plan before a single line of code is touched.
|
||||
|
||||
Press **Tab** to enter Prometheus mode, or type `@plan "your task"` from Sisyphus.
|
||||
|
||||
### Atlas: The Conductor
|
||||
|
||||
Atlas executes Prometheus plans. Distributes tasks to specialized subagents. Accumulates learnings across tasks. Verifies completion independently.
|
||||
|
||||
Run `/start-work` to activate Atlas on your latest plan.
|
||||
|
||||
### Oracle: The Consultant
|
||||
|
||||
Read-only high-IQ consultant for architecture decisions and complex debugging. Consult Oracle when facing unfamiliar patterns, security concerns, or multi-system tradeoffs.
|
||||
|
||||
### Supporting Cast
|
||||
|
||||
- **Metis** — Gap analyzer. Catches what Prometheus missed before plans are finalized.
|
||||
- **Momus** — Ruthless reviewer. Validates plans against clarity, verification, and context criteria.
|
||||
- **Explore** — Fast codebase grep. Uses speed-focused models for pattern discovery.
|
||||
- **Librarian** — Documentation and OSS code search. Stays current on library APIs and best practices.
|
||||
- **Multimodal Looker** — Vision and screenshot analysis.
|
||||
|
||||
---
|
||||
|
||||
## Better Than Pure Claude Code
|
||||
|
||||
Claude Code is good. But it's a single agent running a single model doing everything alone.
|
||||
|
||||
Oh My OpenCode turns that into a coordinated team:
|
||||
|
||||
**Parallel execution.** Claude Code processes one thing at a time. OmO fires background agents in parallel — research, implementation, and verification happening simultaneously. Like having 5 engineers instead of 1.
|
||||
**Hash-anchored edits.** Claude Code's edit tool fails when the model can't reproduce lines exactly. OmO's `LINE#ID` content hashing validates every edit before applying. Grok Code Fast 1 went from 6.7% to 68.3% success rate just from this change.
|
||||
**Intent Gate.** Claude Code takes your prompt and runs. OmO classifies your true intent first — research, implementation, investigation, fix — then routes accordingly. Fewer misinterpretations, better results.
|
||||
**LSP + AST tools.** Workspace-level rename, go-to-definition, find-references, pre-build diagnostics, AST-aware code rewrites. IDE precision that vanilla Claude Code doesn't have.
|
||||
**Skills with embedded MCPs.** Each skill brings its own MCP servers, scoped to the task. Context window stays clean instead of bloating with every tool.
|
||||
**Discipline enforcement.** Todo enforcer yanks idle agents back to work. Comment checker strips AI slop. Ralph Loop keeps going until 100% done. The system doesn't let the agent slack off.
|
||||
|
||||
**The fundamental advantage.** Models have different temperaments. Claude thinks deeply. GPT reasons architecturally. Gemini visualizes. Haiku moves fast. Single-model tools force you to pick one personality for all tasks. Oh My OpenCode leverages them all, routing by task type. This isn't a temporary hack — it's the only architecture that makes sense as models specialize further. The gap between multi-model orchestration and single-model limitation widens every month. We're betting on that future.
|
||||
|
||||
---
|
||||
|
||||
## The Intent Gate
|
||||
|
||||
Before acting on any request, Sisyphus classifies your true intent.
|
||||
|
||||
Are you asking for research? Implementation? Investigation? A fix? The Intent Gate figures out what you actually want, not just the literal words you typed. This means the agent understands context, nuance, and the real goal behind your request.
|
||||
|
||||
Claude Code doesn't have this. It takes your prompt and runs. Oh My OpenCode thinks first, then acts.
|
||||
|
||||
---
|
||||
|
||||
## Two Ways to Work
|
||||
## Working Modes
|
||||
|
||||
### Ultrawork Mode: For the Lazy
|
||||
|
||||
@@ -100,21 +151,114 @@ Use Prometheus for multi-day projects, critical production changes, complex refa
|
||||
|
||||
---
|
||||
|
||||
## Model Configuration
|
||||
## Agent Model Matching
|
||||
|
||||
Different agents work best with different models. Oh My OpenCode automatically assigns optimal models, but you can customize everything.
|
||||
|
||||
### Default Configuration
|
||||
|
||||
Models are auto-configured at install time. The interactive installer asks which providers you have, then generates optimal model assignments for each agent and category.
|
||||
|
||||
At runtime, fallback chains ensure work continues even if your preferred provider is down. Each agent has a provider priority chain. The system tries providers in order until it finds an available model.
|
||||
|
||||
You can override specific agents or categories in your config, but you don't have to. The defaults work. The fallbacks work. Everything just works.
|
||||
### Custom Model Configuration
|
||||
|
||||
See the [Installation Guide](./installation.md) for details on initial setup and provider configuration.
|
||||
You can override specific agents or categories in your config:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
|
||||
|
||||
"agents": {
|
||||
// Main orchestrator: Claude Opus or Kimi K2.5 work best
|
||||
"sisyphus": {
|
||||
"model": "kimi-for-coding/k2p5",
|
||||
"ultrawork": { "model": "anthropic/claude-opus-4-6", "variant": "max" }
|
||||
},
|
||||
|
||||
// Research agents: cheaper models are fine
|
||||
"librarian": { "model": "zai-coding-plan/glm-4.7" },
|
||||
"explore": { "model": "github-copilot/grok-code-fast-1" },
|
||||
|
||||
// Architecture consultation: GPT or Claude Opus
|
||||
"oracle": { "model": "openai/gpt-5.2", "variant": "high" }
|
||||
},
|
||||
|
||||
"categories": {
|
||||
// Frontend work: Gemini dominates visual tasks
|
||||
"visual-engineering": { "model": "google/gemini-3-pro", "variant": "high" },
|
||||
|
||||
// Quick tasks: use the cheapest models
|
||||
"quick": { "model": "anthropic/claude-haiku-4-5" },
|
||||
|
||||
// Deep reasoning: GPT-5.3-codex
|
||||
"ultrabrain": { "model": "openai/gpt-5.3-codex", "variant": "xhigh" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Model Families
|
||||
|
||||
**Claude-like models** (instruction-following, structured output):
|
||||
- Claude Opus 4.6, Claude Sonnet 4.6, Claude Haiku 4.5
|
||||
- Kimi K2.5 — behaves very similarly to Claude
|
||||
- GLM 5 — Claude-like behavior, good for broad tasks
|
||||
|
||||
**GPT models** (explicit reasoning, principle-driven):
|
||||
- GPT-5.3-codex — deep coding powerhouse, required for Hephaestus
|
||||
- GPT-5.2 — high intelligence, default for Oracle
|
||||
- GPT-5-Nano — ultra-cheap, fast utility tasks
|
||||
|
||||
**Different-behavior models**:
|
||||
- Gemini 3 Pro — excels at visual/frontend tasks
|
||||
- MiniMax M2.5 — fast and smart for utility tasks
|
||||
- Grok Code Fast 1 — optimized for code grep/search
|
||||
|
||||
See the [Agent-Model Matching Guide](./agent-model-matching.md) for complete details on which models work best for each agent, safe vs dangerous overrides, and provider priority chains.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
## Why It's Better Than Pure Claude Code
|
||||
|
||||
- [Orchestration Guide](./orchestration.md) - Deep dive into agent collaboration
|
||||
- [Features Reference](../reference/features.md) - Complete feature documentation
|
||||
- [Configuration Reference](../reference/configuration.md) - Customize everything
|
||||
- [Manifesto](../manifesto.md) - Philosophy behind the project
|
||||
Claude Code is good. But it's a single agent running a single model doing everything alone.
|
||||
|
||||
Oh My OpenCode turns that into a coordinated team:
|
||||
|
||||
**Parallel execution.** Claude Code processes one thing at a time. OmO fires background agents in parallel — research, implementation, and verification happening simultaneously. Like having 5 engineers instead of 1.
|
||||
|
||||
**Hash-anchored edits.** Claude Code's edit tool fails when the model can't reproduce lines exactly. OmO's `LINE#ID` content hashing validates every edit before applying. Grok Code Fast 1 went from 6.7% to 68.3% success rate just from this change.
|
||||
|
||||
**Intent Gate.** Claude Code takes your prompt and runs. OmO classifies your true intent first — research, implementation, investigation, fix — then routes accordingly. Fewer misinterpretations, better results.
|
||||
|
||||
**LSP + AST tools.** Workspace-level rename, go-to-definition, find-references, pre-build diagnostics, AST-aware code rewrites. IDE precision that vanilla Claude Code doesn't have.
|
||||
|
||||
**Skills with embedded MCPs.** Each skill brings its own MCP servers, scoped to the task. Context window stays clean instead of bloating with every tool.
|
||||
|
||||
**Discipline enforcement.** Todo enforcer yanks idle agents back to work. Comment checker strips AI slop. Ralph Loop keeps going until 100% done. The system doesn't let the agent slack off.
|
||||
|
||||
**The fundamental advantage.** Models have different temperaments. Claude thinks deeply. GPT reasons architecturally. Gemini visualizes. Haiku moves fast. Single-model tools force you to pick one personality for all tasks. Oh My OpenCode leverages them all, routing by task type. This isn't a temporary hack — it's the only architecture that makes sense as models specialize further. The gap between multi-model orchestration and single-model limitation widens every month. We're betting on that future.
|
||||
|
||||
---
|
||||
|
||||
## The Intent Gate
|
||||
|
||||
Before acting on any request, Sisyphus classifies your true intent.
|
||||
|
||||
Are you asking for research? Implementation? Investigation? A fix? The Intent Gate figures out what you actually want, not just the literal words you typed. This means the agent understands context, nuance, and the real goal behind your request.
|
||||
|
||||
Claude Code doesn't have this. It takes your prompt and runs. Oh My OpenCode thinks first, then acts.
|
||||
|
||||
---
|
||||
|
||||
## What's Next
|
||||
|
||||
- **[Installation Guide](./installation.md)** — Complete setup instructions, provider authentication, and troubleshooting
|
||||
- **[Orchestration Guide](./orchestration.md)** — Deep dive into agent collaboration, planning with Prometheus, and execution with Atlas
|
||||
- **[Agent-Model Matching Guide](./agent-model-matching.md)** — Which models work best for each agent and how to customize
|
||||
- **[Configuration Reference](../reference/configuration.md)** — Full config options with examples
|
||||
- **[Features Reference](../reference/features.md)** — Complete feature documentation
|
||||
- **[Manifesto](../manifesto.md)** — Philosophy behind the project
|
||||
|
||||
---
|
||||
|
||||
**Ready to start?** Type `ultrawork` and see what a coordinated AI team can do.
|
||||
|
||||
Reference in New Issue
Block a user