elias/oh-my-opencode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update AGENTS.md files and configuration docs

Browse Source 
Refresh documentation across all AGENTS.md files and update configuration documentation with latest features.

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
justsisyphus 2026-01-22 22:48:50 +09:00
parent ff92a4caa2
commit 638a314f6d
8 changed files with 128 additions and 247 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
AGENTS.md
View File

@ -1,25 +1,25 @@
# PROJECT KNOWLEDGE BASE # PROJECT KNOWLEDGE BASE
**Generated:** 2026-01-20T17:18:00+09:00 **Generated:** 2026-01-22T22:25:00+09:00
**Commit:** 3d3d3e49 **Commit:** 85bf266f
**Branch:** dev **Branch:** dev
## OVERVIEW ## OVERVIEW
ClaudeCode plugin implementing multi-model agent orchestration (Claude Opus 4.5, GPT-5.2, Gemini 3, Grok, GLM-4.7). 31 lifecycle hooks, 20+ tools (LSP, AST-Grep, delegation), 10 specialized agents, Claude Code compatibility layer. "oh-my-zsh" for ClaudeCode. OpenCode plugin implementing multi-model agent orchestration (Claude Opus 4.5, GPT-5.2, Gemini 3, Grok, GLM-4.7). 31 lifecycle hooks, 20+ tools (LSP, AST-Grep, delegation), 10 specialized agents, Claude Code compatibility layer. "oh-my-zsh" for OpenCode.
## STRUCTURE ## STRUCTURE
``` ```
oh-my-opencode/ oh-my-opencode/
├── src/ ├── src/
│ ├── agents/ # 10 AI agents (Sisyphus, oracle, librarian, explore, frontend, etc.) - see src/agents/AGENTS.md │ ├── agents/ # 10 AI agents (Sisyphus, oracle, librarian, explore, etc.) - see src/agents/AGENTS.md
│ ├── hooks/ # 31 lifecycle hooks (PreToolUse, PostToolUse, Stop, etc.) - see src/hooks/AGENTS.md │ ├── hooks/ # 31 lifecycle hooks (PreToolUse, PostToolUse, Stop, etc.) - see src/hooks/AGENTS.md
│ ├── tools/ # 20+ tools (LSP, AST-Grep, delegation, session) - see src/tools/AGENTS.md │ ├── tools/ # 20+ tools (LSP, AST-Grep, delegation, session) - see src/tools/AGENTS.md
│ ├── features/ # Background agents, Claude Code compat layer - see src/features/AGENTS.md │ ├── features/ # Background agents, Claude Code compat layer - see src/features/AGENTS.md
│ ├── shared/ # 43 cross-cutting utilities - see src/shared/AGENTS.md │ ├── shared/ # 50 cross-cutting utilities - see src/shared/AGENTS.md
│ ├── cli/ # CLI installer, doctor, run - see src/cli/AGENTS.md │ ├── cli/ # CLI installer, doctor, run - see src/cli/AGENTS.md
│ ├── mcp/ # Built-in MCPs: websearch, context7, grep_app │ ├── mcp/ # Built-in MCPs: websearch, context7, grep_app - see src/mcp/AGENTS.md
│ ├── config/ # Zod schema, TypeScript types │ ├── config/ # Zod schema, TypeScript types
│ └── index.ts # Main plugin entry (589 lines) │ └── index.ts # Main plugin entry (589 lines)
├── script/ # build-schema.ts, publish.ts, build-binaries.ts ├── script/ # build-schema.ts, publish.ts, build-binaries.ts
@ -40,11 +40,11 @@ oh-my-opencode/
| AST-Grep | `src/tools/ast-grep/` | napi.ts for @ast-grep/napi binding | | AST-Grep | `src/tools/ast-grep/` | napi.ts for @ast-grep/napi binding |
| Config schema | `src/config/schema.ts` | Zod schema, run `bun run build:schema` after changes | | Config schema | `src/config/schema.ts` | Zod schema, run `bun run build:schema` after changes |
| Claude Code compat | `src/features/claude-code-*-loader/` | Command, skill, agent, mcp loaders | | Claude Code compat | `src/features/claude-code-*-loader/` | Command, skill, agent, mcp loaders |
| Background agents | `src/features/background-agent/` | manager.ts (1165 lines) for task lifecycle | | Background agents | `src/features/background-agent/` | manager.ts (1335 lines) for task lifecycle |
| Skill MCP | `src/features/skill-mcp-manager/` | MCP servers embedded in skills | | Skill MCP | `src/features/skill-mcp-manager/` | MCP servers embedded in skills |
| CLI installer | `src/cli/install.ts` | Interactive TUI (462 lines) | | CLI installer | `src/cli/install.ts` | Interactive TUI (520 lines) |
| Doctor checks | `src/cli/doctor/checks/` | 14 health checks across 6 categories | | Doctor checks | `src/cli/doctor/checks/` | 14 health checks across 6 categories |
| Orchestrator | `src/hooks/atlas/` | Main orchestration hook (771 lines) | | Orchestrator hook | `src/hooks/atlas/` | Main orchestration hook (771 lines) |
## TDD (Test-Driven Development) ## TDD (Test-Driven Development)
@ -144,14 +144,14 @@ bun test # Run tests (83 test files)
| File | Lines | Description | | File | Lines | Description |
|------|-------|-------------| |------|-------|-------------|
| `src/agents/atlas.ts` | 1383 | Orchestrator agent, 7-section delegation, wisdom accumulation | | `src/agents/atlas.ts` | 1383 | Orchestrator agent, 7-section delegation, wisdom accumulation |
| `src/features/background-agent/manager.ts` | 1335 | Task lifecycle, concurrency, notification batching |
| `src/features/builtin-skills/skills.ts` | 1203 | Skill definitions (playwright, git-master, frontend-ui-ux) | | `src/features/builtin-skills/skills.ts` | 1203 | Skill definitions (playwright, git-master, frontend-ui-ux) |
| `src/agents/prometheus-prompt.ts` | 1196 | Planning agent, interview mode, Momus loop | | `src/agents/prometheus-prompt.ts` | 1196 | Planning agent, interview mode, Momus loop |
| `src/features/background-agent/manager.ts` | 1165 | Task lifecycle, concurrency, notification batching | | `src/tools/delegate-task/tools.ts` | 1027 | Category-based task delegation |
| `src/hooks/atlas/index.ts` | 771 | Orchestrator hook implementation | | `src/hooks/atlas/index.ts` | 771 | Orchestrator hook implementation |
| `src/tools/delegate-task/tools.ts` | 770 | Category-based task delegation | | `src/cli/config-manager.ts` | 641 | JSONC parsing, multi-level config |
| `src/cli/config-manager.ts` | 616 | JSONC parsing, multi-level config |
| `src/agents/sisyphus.ts` | 615 | Main Sisyphus prompt |
| `src/features/builtin-commands/templates/refactor.ts` | 619 | Refactoring command template | | `src/features/builtin-commands/templates/refactor.ts` | 619 | Refactoring command template |
| `src/agents/sisyphus.ts` | 615 | Main Sisyphus prompt |
| `src/tools/lsp/client.ts` | 596 | LSP protocol, JSON-RPC | | `src/tools/lsp/client.ts` | 596 | LSP protocol, JSON-RPC |
## MCP ARCHITECTURE ## MCP ARCHITECTURE
@ -171,7 +171,7 @@ Three-tier MCP system:
## NOTES ## NOTES
- **Testing**: Bun native test (`bun test`), BDD-style, 83 test files - **Testing**: Bun native test (`bun test`), BDD-style, 83 test files
- **ClaudeCode**: Requires >= 1.0.150 - **OpenCode**: Requires >= 1.0.150
- **Multi-lang docs**: README.md (EN), README.ko.md (KO), README.ja.md (JA), README.zh-cn.md (ZH-CN) - **Multi-lang docs**: README.md (EN), README.ko.md (KO), README.ja.md (JA), README.zh-cn.md (ZH-CN)
- **Config**: `~/.config/opencode/oh-my-opencode.json` (user) or `.opencode/oh-my-opencode.json` (project) - **Config**: `~/.config/opencode/oh-my-opencode.json` (user) or `.opencode/oh-my-opencode.json` (project)
- **Trusted deps**: @ast-grep/cli, @ast-grep/napi, @code-yeongyu/comment-checker - **Trusted deps**: @ast-grep/cli, @ast-grep/napi, @code-yeongyu/comment-checker

278
docs/configurations.md
View File

@ -308,268 +308,128 @@ Add custom categories in `oh-my-opencode.json`:
Each category supports: `model`, `temperature`, `top_p`, `maxTokens`, `thinking`, `reasoningEffort`, `textVerbosity`, `tools`, `prompt_append`. Each category supports: `model`, `temperature`, `top_p`, `maxTokens`, `thinking`, `reasoningEffort`, `textVerbosity`, `tools`, `prompt_append`.
## Model Selection System ## Model Resolution System
The installer automatically configures optimal models based on your subscriptions. This section explains how models are selected for each agent and category. At runtime, Oh My OpenCode uses a 3-step resolution process to determine which model to use for each agent and category. This happens dynamically based on your configuration and available models.
### Overview ### Overview
**Problem**: Users have different subscription combinations (Claude, OpenAI, Gemini, etc.). The system needs to automatically select the best available model for each task. **Problem**: Users have different provider configurations. The system needs to select the best available model for each task at runtime.
**Solution**: A tiered fallback system that: **Solution**: A simple 3-step resolution flow:
1. Prioritizes native provider subscriptions (Claude, OpenAI, Gemini) 1. **Step 1: User Override** — If you specify a model in `oh-my-opencode.json`, use exactly that
2. Falls back through alternative providers in priority order 2. **Step 2: Provider Fallback** — Try each provider in the requirement's priority order until one is available
3. Applies capability-specific logic (e.g., Oracle prefers GPT, visual tasks prefer Gemini) 3. **Step 3: System Default** — Fall back to OpenCode's configured default model
### Provider Priority ### Resolution Flow
``` ```
┌─────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────┐
│ MODEL SELECTION FLOW │ │ MODEL RESOLUTION FLOW │
├─────────────────────────────────────────────────────────────────┤ ├─────────────────────────────────────────────────────────────────┤
│ │ │ │
│ Step 1: USER OVERRIDE │
│ ┌─────────────────────────────────────────────────────────┐ │ │ ┌─────────────────────────────────────────────────────────┐ │
│ │ TIER 1: NATIVE PROVIDERS │ │ │ │ User specified model in oh-my-opencode.json? │ │
│ │ (Your direct subscriptions) │ │ │ │ YES → Use exactly as specified │ │
│ │ │ │ │ │ NO → Continue to Step 2 │ │
│ │ Claude (anthropic/) ──► OpenAI (openai/) ──► Gemini │ │
│ │ │ │ (google/) │ │
│ │ ▼ ▼ │ │ │
│ │ Opus/Sonnet/Haiku GPT-5.2/Codex Gemini 3 Pro │ │
│ └─────────────────────────────────────────────────────────┘ │ │ └─────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
│ ▼ (if no native available) │ │ ▼ │
│ Step 2: PROVIDER PRIORITY FALLBACK │
│ ┌─────────────────────────────────────────────────────────┐ │ │ ┌─────────────────────────────────────────────────────────┐ │
│ │ TIER 2: OPENCODE ZEN │ │ │ │ For each provider in requirement.providers order: │ │
│ │ (opencode/ prefix models) │ │
│ │ │ │ │ │ │ │
│ │ opencode/claude-opus-4-5, opencode/gpt-5.2, etc. │ │ │ │ Example for Sisyphus: │ │
│ │ anthropic → github-copilot → opencode → antigravity │ │
│ │ │ │ │ │ │ │
│ │ ▼ ▼ ▼ ▼ │ │
│ │ Try: anthropic/claude-opus-4-5 │ │
│ │ Try: github-copilot/claude-opus-4-5 │ │
│ │ Try: opencode/claude-opus-4-5 │ │
│ │ ... │ │
│ │ │ │
│ │ Found in available models? → Return matched model │ │
│ │ Not found? → Try next provider │ │
│ └─────────────────────────────────────────────────────────┘ │ │ └─────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
│ ▼ (if no OpenCode Zen) │ │ ▼ (all providers exhausted) │
│ Step 3: SYSTEM DEFAULT │
│ ┌─────────────────────────────────────────────────────────┐ │ │ ┌─────────────────────────────────────────────────────────┐ │
│ │ TIER 3: GITHUB COPILOT │ │ │ │ Return systemDefaultModel (from opencode.json) │ │
│ │ (github-copilot/ prefix models) │ │
│ │ │ │
│ │ github-copilot/claude-opus-4.5, etc. │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ (if no Copilot) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ TIER 4: Z.AI CODING PLAN │ │
│ │ (zai-coding-plan/ prefix models) │ │
│ │ │ │
│ │ zai-coding-plan/glm-4.7 (GLM models only) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ (ultimate fallback) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ FALLBACK: FREE TIER │ │
│ │ │ │
│ │ opencode/glm-4.7-free │ │
│ └─────────────────────────────────────────────────────────┘ │ │ └─────────────────────────────────────────────────────────┘ │
│ │ │ │
└─────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────┘
``` ```
### Native Tier Cross-Fallback ### Agent Provider Chains
Within the Native tier, models fall back based on capability requirements: Each agent has a defined provider priority chain. The system tries providers in order until it finds an available model:
| Capability | 1st Choice | 2nd Choice | 3rd Choice | | Agent | Model (no prefix) | Provider Priority Chain |
|------------|------------|------------|------------| |-------|-------------------|-------------------------|
| **High-tier tasks** (Sisyphus, Atlas) | Claude Opus | OpenAI GPT-5.2 | Gemini 3 Pro | | **Sisyphus** | `claude-opus-4-5` | anthropic → github-copilot → opencode → antigravity → google |
| **Standard tasks** | Claude Sonnet | OpenAI GPT-5.2 | Gemini 3 Flash | | **oracle** | `gpt-5.2` | openai → anthropic → google → github-copilot → opencode |
| **Quick tasks** | Claude Haiku | OpenAI GPT-5.1-mini | Gemini 3 Flash | | **librarian** | `glm-4.7-free` | opencode → github-copilot → anthropic |
| **Deep reasoning** (Oracle) | OpenAI GPT-5.2-Codex | Claude Opus | Gemini 3 Pro | | **explore** | `grok-code` | opencode → anthropic → github-copilot |
| **Visual/UI tasks** | Gemini 3 Pro | OpenAI GPT-5.2 | Claude Sonnet | | **multimodal-looker** | `gemini-3-pro-preview` | google → openai → anthropic → github-copilot → opencode |
| **Writing tasks** | Gemini 3 Flash | OpenAI GPT-5.2 | Claude Sonnet | | **Prometheus (Planner)** | `claude-opus-4-5` | anthropic → github-copilot → opencode → antigravity → google |
| **Metis (Plan Consultant)** | `claude-sonnet-4-5` | anthropic → github-copilot → opencode → antigravity → google |
| **Momus (Plan Reviewer)** | `claude-opus-4-5` | anthropic → github-copilot → opencode → antigravity → google |
| **Atlas** | `claude-sonnet-4-5` | anthropic → github-copilot → opencode → antigravity → google |
### Agent-Specific Rules ### Category Provider Chains
#### Standard Agents Categories follow the same resolution logic:
| Agent | Capability | Example (Claude + OpenAI + Gemini) | | Category | Model (no prefix) | Provider Priority Chain |
|-------|------------|-------------------------------------| |----------|-------------------|-------------------------|
| **Sisyphus** | High-tier (isMax20) or Standard | `anthropic/claude-opus-4-5` or `anthropic/claude-sonnet-4-5` | | **visual-engineering** | `gemini-3-pro-preview` | google → openai → anthropic → github-copilot → opencode |
| **Oracle** | Deep reasoning | `openai/gpt-5.2-codex` | | **ultrabrain** | `gpt-5.2-codex` | openai → anthropic → google → github-copilot → opencode |
| **Prometheus** | High-tier/Standard | Same as Sisyphus | | **artistry** | `gemini-3-pro-preview` | google → openai → anthropic → github-copilot → opencode |
| **Metis** | High-tier/Standard | Same as Sisyphus | | **quick** | `claude-haiku-4-5` | anthropic → github-copilot → opencode → antigravity → google |
| **Momus** | Deep reasoning | `openai/gpt-5.2-codex` | | **unspecified-low** | `claude-sonnet-4-5` | anthropic → github-copilot → opencode → antigravity → google |
| **Atlas** | High-tier/Standard | Same as Sisyphus | | **unspecified-high** | `claude-opus-4-5` | anthropic → github-copilot → opencode → antigravity → google |
| **multimodal-looker** | Visual | `google/gemini-3-pro-preview` | | **writing** | `gemini-3-flash-preview` | google → openai → anthropic → github-copilot → opencode |
#### Special Case: explore Agent ### Checking Your Configuration
The `explore` agent has unique logic for cost optimization: Use the `doctor` command to see how models resolve with your current configuration:
``` ```bash
┌────────────────────────────────────────┐ bunx oh-my-opencode doctor --verbose
│ EXPLORE AGENT LOGIC │
├────────────────────────────────────────┤
│ │
│ Has Claude + isMax20? │
│ │ │
│ YES │ NO │
│ ▼ │ ▼ │
│ ┌──────┐│┌────────────────────┐ │
│ │Haiku ││ │ opencode/grok-code │ │
│ │4.5 │││ (free & fast) │ │
│ └──────┘│└────────────────────┘ │
│ │
│ Rationale: │
│ • max20 users want to use Claude quota │
│ • Others save quota with free grok │
└────────────────────────────────────────┘
``` ```
#### Special Case: librarian Agent The "Model Resolution" check shows:
- Each agent/category's model requirement
The `librarian` agent prioritizes Z.ai when available: - Provider fallback chain
- User overrides (if configured)
``` - Effective resolution path
┌────────────────────────────────────────┐
│ LIBRARIAN AGENT LOGIC │
├────────────────────────────────────────┤
│ │
│ Has Z.ai Coding Plan? │
│ │ │
│ YES │ NO │
│ ▼ │ ▼ │
│ ┌──────────────┐ ┌──────────────────┐ │
│ │zai-coding- │ │ Normal fallback │ │
│ │plan/glm-4.7 │ │ chain applies │ │
│ └──────────────┘ └──────────────────┘ │
│ │
│ Rationale: │
│ • GLM excels at documentation tasks │
│ • Z.ai provides dedicated GLM access │
└────────────────────────────────────────┘
```
### Category-Specific Rules
Categories follow the same fallback logic as agents:
| Category | Primary Capability | Fallback Chain |
|----------|-------------------|----------------|
| `visual-engineering` | Visual | Gemini → OpenAI → Claude |
| `ultrabrain` | Deep reasoning | OpenAI → Claude → Gemini |
| `artistry` | Visual/Creative | Gemini → OpenAI → Claude |
| `quick` | Quick tasks | Claude Haiku → OpenAI mini → Gemini Flash |
| `unspecified-low` | Standard | Claude Sonnet → OpenAI → Gemini Flash |
| `unspecified-high` | High-tier | Claude Opus → OpenAI → Gemini Pro |
| `writing` | Writing | Gemini Flash → OpenAI → Claude |
### Subscription Scenarios
#### Scenario 1: Claude Only (Standard Plan)
```json
// User has: Claude Pro (not max20)
{
"agents": {
"Sisyphus": { "model": "anthropic/claude-sonnet-4-5" },
"oracle": { "model": "anthropic/claude-opus-4-5" },
"explore": { "model": "opencode/grok-code" },
"librarian": { "model": "opencode/glm-4.7-free" }
}
}
```
#### Scenario 2: Claude Only (Max20 Plan)
```json
// User has: Claude Max (max20 mode)
{
"agents": {
"Sisyphus": { "model": "anthropic/claude-opus-4-5" },
"oracle": { "model": "anthropic/claude-opus-4-5" },
"explore": { "model": "anthropic/claude-haiku-4-5" },
"librarian": { "model": "opencode/glm-4.7-free" }
}
}
```
#### Scenario 3: ChatGPT Only
```json
// User has: OpenAI/ChatGPT Plus only
{
"agents": {
"Sisyphus": { "model": "openai/gpt-5.2" },
"oracle": { "model": "openai/gpt-5.2-codex" },
"explore": { "model": "opencode/grok-code" },
"multimodal-looker": { "model": "openai/gpt-5.2" },
"librarian": { "model": "opencode/glm-4.7-free" }
}
}
```
#### Scenario 4: Full Stack (Claude + OpenAI + Gemini)
```json
// User has: All native providers
{
"agents": {
"Sisyphus": { "model": "anthropic/claude-opus-4-5" },
"oracle": { "model": "openai/gpt-5.2-codex" },
"explore": { "model": "anthropic/claude-haiku-4-5" },
"multimodal-looker": { "model": "google/gemini-3-pro-preview" },
"librarian": { "model": "opencode/glm-4.7-free" }
}
}
```
#### Scenario 5: GitHub Copilot Only
```json
// User has: GitHub Copilot only (no native providers)
{
"agents": {
"Sisyphus": { "model": "github-copilot/claude-sonnet-4.5" },
"oracle": { "model": "github-copilot/gpt-5.2-codex" },
"explore": { "model": "opencode/grok-code" },
"librarian": { "model": "github-copilot/gpt-5.2" }
}
}
```
### isMax20 Flag Impact
The `isMax20` flag (Claude Max 20x mode) affects high-tier task model selection:
| isMax20 | High-tier Capability | Result |
|---------|---------------------|--------|
| `true` | Uses `unspecified-high` | Opus-class models |
| `false` | Uses `unspecified-low` | Sonnet-class models |
**Affected agents**: Sisyphus, Prometheus, Metis, Atlas
**Why?**: Max20 users have 20x more Claude usage, so they can afford Opus for orchestration. Standard users should conserve quota with Sonnet.
### Manual Override ### Manual Override
You can always override automatic selection in `oh-my-opencode.json`: Override any agent or category model in `oh-my-opencode.json`:
```json ```json
{ {
"agents": { "agents": {
"Sisyphus": { "Sisyphus": {
"model": "anthropic/claude-sonnet-4-5" // Force specific model "model": "anthropic/claude-sonnet-4-5"
}, },
"oracle": { "oracle": {
"model": "openai/o3" // Use different model "model": "openai/o3"
} }
}, },
"categories": { "categories": {
"visual-engineering": { "visual-engineering": {
"model": "anthropic/claude-opus-4-5" // Override category default "model": "anthropic/claude-opus-4-5"
} }
} }
} }
``` ```
When you specify a model override, it takes precedence (Step 1) and the provider fallback chain is skipped entirely.
## Hooks ## Hooks
Disable specific built-in hooks via `disabled_hooks` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`: Disable specific built-in hooks via `disabled_hooks` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:

31
src/agents/AGENTS.md
View File

@ -2,16 +2,16 @@
## OVERVIEW ## OVERVIEW
8 AI agents for multi-model orchestration. Sisyphus (primary), oracle, librarian, explore, multimodal-looker, Prometheus, Metis, Momus. 10 AI agents for multi-model orchestration. Sisyphus (primary), Atlas (orchestrator), oracle, librarian, explore, multimodal-looker, Prometheus, Metis, Momus, Sisyphus-Junior.
## STRUCTURE ## STRUCTURE
``` ```
agents/ agents/
├── atlas.ts # Orchestrator (1383 lines) - 7-phase delegation ├── atlas.ts # Master Orchestrator (1383 lines) - 7-phase delegation
├── sisyphus.ts # Main prompt (615 lines) ├── sisyphus.ts # Main prompt (615 lines)
├── sisyphus-junior.ts # Delegated task executor ├── sisyphus-junior.ts # Delegated task executor (136 lines)
├── dynamic-agent-prompt-builder.ts # Dynamic prompt generation ├── dynamic-agent-prompt-builder.ts # Dynamic prompt generation (360 lines)
├── oracle.ts # Strategic advisor (GPT-5.2) ├── oracle.ts # Strategic advisor (GPT-5.2)
├── librarian.ts # Multi-repo research (GLM-4.7-free) ├── librarian.ts # Multi-repo research (GLM-4.7-free)
├── explore.ts # Fast grep (Grok Code) ├── explore.ts # Fast grep (Grok Code)
@ -19,8 +19,8 @@ agents/
├── prometheus-prompt.ts # Planning (1196 lines) - interview mode ├── prometheus-prompt.ts # Planning (1196 lines) - interview mode
├── metis.ts # Plan consultant - pre-planning analysis ├── metis.ts # Plan consultant - pre-planning analysis
├── momus.ts # Plan reviewer - validation ├── momus.ts # Plan reviewer - validation
├── types.ts # AgentModelConfig interface ├── types.ts # AgentModelConfig, AgentPromptMetadata
├── utils.ts # createBuiltinAgents(), getAgentName() ├── utils.ts # createBuiltinAgents(), resolveModelWithFallback()
└── index.ts # builtinAgents export └── index.ts # builtinAgents export
``` ```
@ -29,18 +29,20 @@ agents/
| Agent | Model | Temperature | Purpose | | Agent | Model | Temperature | Purpose |
|-------|-------|-------------|---------| |-------|-------|-------------|---------|
| Sisyphus | anthropic/claude-opus-4-5 | 0.1 | Primary orchestrator, todo-driven | | Sisyphus | anthropic/claude-opus-4-5 | 0.1 | Primary orchestrator, todo-driven |
| Atlas | anthropic/claude-opus-4-5 | 0.1 | Master orchestrator, delegate_task |
| oracle | openai/gpt-5.2 | 0.1 | Read-only consultation, debugging | | oracle | openai/gpt-5.2 | 0.1 | Read-only consultation, debugging |
| librarian | opencode/glm-4.7-free | 0.1 | Docs, GitHub search, OSS examples | | librarian | opencode/glm-4.7-free | 0.1 | Docs, GitHub search, OSS examples |
| explore | opencode/grok-code | 0.1 | Fast contextual grep | | explore | opencode/grok-code | 0.1 | Fast contextual grep |
| multimodal-looker | google/gemini-3-flash | 0.1 | PDF/image analysis | | multimodal-looker | google/gemini-3-flash | 0.1 | PDF/image analysis |
| Prometheus | anthropic/claude-opus-4-5 | 0.1 | Strategic planning, interview mode | | Prometheus | anthropic/claude-opus-4-5 | 0.1 | Strategic planning, interview mode |
| Metis | anthropic/claude-sonnet-4-5 | 0.1 | Pre-planning gap analysis | | Metis | anthropic/claude-sonnet-4-5 | 0.3 | Pre-planning gap analysis |
| Momus | anthropic/claude-sonnet-4-5 | 0.1 | Plan validation | | Momus | anthropic/claude-sonnet-4-5 | 0.1 | Plan validation |
| Sisyphus-Junior | anthropic/claude-sonnet-4-5 | 0.1 | Category-spawned executor |
## HOW TO ADD ## HOW TO ADD
1. Create `src/agents/my-agent.ts` exporting `AgentConfig` 1. Create `src/agents/my-agent.ts` exporting factory + metadata
2. Add to `builtinAgents` in `src/agents/index.ts` 2. Add to `agentSources` in `src/agents/utils.ts`
3. Update `AgentNameSchema` in `src/config/schema.ts` 3. Update `AgentNameSchema` in `src/config/schema.ts`
4. Register in `src/index.ts` initialization 4. Register in `src/index.ts` initialization
@ -51,17 +53,20 @@ agents/
| oracle | write, edit, task, delegate_task | | oracle | write, edit, task, delegate_task |
| librarian | write, edit, task, delegate_task, call_omo_agent | | librarian | write, edit, task, delegate_task, call_omo_agent |
| explore | write, edit, task, delegate_task, call_omo_agent | | explore | write, edit, task, delegate_task, call_omo_agent |
| multimodal-looker | Allowlist: read, glob, grep | | multimodal-looker | Allowlist: read only |
| Sisyphus-Junior | task, delegate_task (cannot spawn implementation agents) |
## KEY PATTERNS ## KEY PATTERNS
- **Factory**: `createXXXAgent(model?: string): AgentConfig` - **Factory**: `createXXXAgent(model?: string): AgentConfig`
- **Metadata**: `XXX_PROMPT_METADATA: AgentPromptMetadata` - **Metadata**: `XXX_PROMPT_METADATA: AgentPromptMetadata` with category, cost, triggers
- **Tool restrictions**: `permission: { edit: "deny", bash: "ask" }` - **Tool restrictions**: `createAgentToolRestrictions(tools)` or `createAgentToolAllowlist(tools)`
- **Thinking**: 32k budget tokens for Sisyphus, Oracle, Prometheus - **Thinking**: 32k budget tokens for Sisyphus, Oracle, Prometheus, Atlas
- **Model-specific**: GPT uses `reasoningEffort`, Anthropic uses `thinking` budget
## ANTI-PATTERNS ## ANTI-PATTERNS
- **Trust reports**: NEVER trust subagent "I'm done" - verify outputs - **Trust reports**: NEVER trust subagent "I'm done" - verify outputs
- **High temp**: Don't use >0.3 for code agents - **High temp**: Don't use >0.3 for code agents
- **Sequential calls**: Use `delegate_task` with `run_in_background` - **Sequential calls**: Use `delegate_task` with `run_in_background`
- **Missing metadata**: Every agent needs `XXX_PROMPT_METADATA` export

6
src/cli/AGENTS.md
View File

@ -9,8 +9,8 @@ CLI entry point: `bunx oh-my-opencode`. Interactive installer, doctor diagnostic
``` ```
cli/ cli/
├── index.ts # Commander.js entry, 5 subcommands ├── index.ts # Commander.js entry, 5 subcommands
├── install.ts # Interactive TUI installer (462 lines) ├── install.ts # Interactive TUI installer (520 lines)
├── config-manager.ts # JSONC parsing, multi-level merge (730 lines) ├── config-manager.ts # JSONC parsing, multi-level merge (641 lines)
├── types.ts # InstallArgs, InstallConfig, DetectedConfig ├── types.ts # InstallArgs, InstallConfig, DetectedConfig
├── doctor/ ├── doctor/
│ ├── index.ts # Doctor command entry │ ├── index.ts # Doctor command entry
@ -18,7 +18,7 @@ cli/
│ ├── formatter.ts # Colored output, symbols │ ├── formatter.ts # Colored output, symbols
│ ├── constants.ts # Check IDs, categories, symbols │ ├── constants.ts # Check IDs, categories, symbols
│ ├── types.ts # CheckResult, CheckDefinition │ ├── types.ts # CheckResult, CheckDefinition
│ └── checks/ # 14 checks across 6 categories │ └── checks/ # 14 checks across 6 categories (21 files)
│ ├── version.ts # OpenCode + plugin version │ ├── version.ts # OpenCode + plugin version
│ ├── config.ts # JSONC validity, Zod validation │ ├── config.ts # JSONC validity, Zod validation
│ ├── auth.ts # Anthropic, OpenAI, Google │ ├── auth.ts # Anthropic, OpenAI, Google

6
src/features/AGENTS.md
View File

@ -8,11 +8,11 @@ Core feature modules + Claude Code compatibility layer. Background agents, skill
``` ```
features/ features/
├── background-agent/ # Task lifecycle (1165 lines manager.ts) ├── background-agent/ # Task lifecycle (1335 lines manager.ts)
│ ├── manager.ts # Launch → poll → complete orchestration │ ├── manager.ts # Launch → poll → complete orchestration
│ ├── concurrency.ts # Per-provider/model limits │ ├── concurrency.ts # Per-provider/model limits
│ └── types.ts # BackgroundTask, LaunchInput │ └── types.ts # BackgroundTask, LaunchInput
├── skill-mcp-manager/ # MCP client lifecycle ├── skill-mcp-manager/ # MCP client lifecycle (520 lines)
│ ├── manager.ts # Lazy loading, idle cleanup │ ├── manager.ts # Lazy loading, idle cleanup
│ └── types.ts # SkillMcpConfig, transports │ └── types.ts # SkillMcpConfig, transports
├── builtin-skills/ # Playwright, git-master, frontend-ui-ux ├── builtin-skills/ # Playwright, git-master, frontend-ui-ux
@ -24,7 +24,7 @@ features/
├── claude-code-mcp-loader/ # .mcp.json with ${VAR} expansion ├── claude-code-mcp-loader/ # .mcp.json with ${VAR} expansion
├── claude-code-plugin-loader/ # installed_plugins.json ├── claude-code-plugin-loader/ # installed_plugins.json
├── claude-code-session-state/ # Session state persistence ├── claude-code-session-state/ # Session state persistence
├── opencode-skill-loader/ # Skills from 6 directories ├── opencode-skill-loader/ # Skills from 6 directories (12 files)
├── context-injector/ # AGENTS.md/README.md injection ├── context-injector/ # AGENTS.md/README.md injection
├── boulder-state/ # Todo state persistence ├── boulder-state/ # Todo state persistence
├── task-toast-manager/ # Toast notifications ├── task-toast-manager/ # Toast notifications

5
src/hooks/AGENTS.md
View File

@ -12,7 +12,7 @@ hooks/
├── anthropic-context-window-limit-recovery/ # Auto-summarize at token limit ├── anthropic-context-window-limit-recovery/ # Auto-summarize at token limit
├── todo-continuation-enforcer.ts # Force TODO completion ├── todo-continuation-enforcer.ts # Force TODO completion
├── ralph-loop/ # Self-referential dev loop until done ├── ralph-loop/ # Self-referential dev loop until done
├── claude-code-hooks/ # settings.json hook compat layer (13 files) ├── claude-code-hooks/ # settings.json hook compat layer (14 files) - see AGENTS.md
├── comment-checker/ # Prevents AI slop/excessive comments ├── comment-checker/ # Prevents AI slop/excessive comments
├── auto-slash-command/ # Detects /command patterns ├── auto-slash-command/ # Detects /command patterns
├── rules-injector/ # Conditional rules from .claude/rules/ ├── rules-injector/ # Conditional rules from .claude/rules/
@ -26,6 +26,9 @@ hooks/
├── think-mode/ # Dynamic thinking budget ├── think-mode/ # Dynamic thinking budget
├── keyword-detector/ # ultrawork/search/analyze modes ├── keyword-detector/ # ultrawork/search/analyze modes
├── background-notification/ # OS notification on task completion ├── background-notification/ # OS notification on task completion
├── prometheus-md-only/ # Enforces planner read-only mode
├── agent-usage-reminder/ # Reminds to use specialized agents
├── auto-update-checker/ # Checks for plugin updates
└── tool-output-truncator.ts # Prevents context bloat └── tool-output-truncator.ts # Prevents context bloat
``` ```

15
src/shared/AGENTS.md
View File

@ -2,7 +2,7 @@
## OVERVIEW ## OVERVIEW
43 cross-cutting utilities: path resolution, token truncation, config parsing, Claude Code compatibility. 50 cross-cutting utilities: path resolution, token truncation, config parsing, model resolution, Claude Code compatibility.
## STRUCTURE ## STRUCTURE
@ -22,6 +22,11 @@ shared/
├── env-expander.ts # ${VAR} expansion in configs ├── env-expander.ts # ${VAR} expansion in configs
├── system-directive.ts # System directive types ├── system-directive.ts # System directive types
├── hook-utils.ts # Hook helper functions ├── hook-utils.ts # Hook helper functions
├── model-requirements.ts # Agent/Category model requirements (providers + model)
├── model-availability.ts # Available models fetch + fuzzy matching
├── model-resolver.ts # 3-step model resolution (override → provider fallback → default)
├── shell-env.ts # Cross-platform shell environment
├── prompt-parts-helper.ts # Prompt parts manipulation
└── *.test.ts # Test files (colocated) └── *.test.ts # Test files (colocated)
``` ```
@ -37,6 +42,11 @@ shared/
| Resolve paths | `getOpenCodeConfigDir()`, `getClaudeConfigDir()` | | Resolve paths | `getOpenCodeConfigDir()`, `getClaudeConfigDir()` |
| Migrate config | `migrateConfigFile(path, rawConfig)` | | Migrate config | `migrateConfigFile(path, rawConfig)` |
| Compare versions | `isOpenCodeVersionAtLeast("1.1.0")` | | Compare versions | `isOpenCodeVersionAtLeast("1.1.0")` |
| Get agent model requirements | `AGENT_MODEL_REQUIREMENTS` in `model-requirements.ts` |
| Get category model requirements | `CATEGORY_MODEL_REQUIREMENTS` in `model-requirements.ts` |
| Resolve model with fallback | `resolveModelWithFallback()` in `model-resolver.ts` |
| Fuzzy match model names | `fuzzyMatchModel()` in `model-availability.ts` |
| Fetch available models | `fetchAvailableModels(client)` in `model-availability.ts` |
## KEY PATTERNS ## KEY PATTERNS
@ -52,6 +62,9 @@ if (isOpenCodeVersionAtLeast("1.1.0")) { /* new feature */ }
// Tool permission normalization // Tool permission normalization
const permissions = migrateToolsToPermission(legacyTools) const permissions = migrateToolsToPermission(legacyTools)
// Model resolution with fallback chain
const model = await resolveModelWithFallback(client, requirements, override)
``` ```
## ANTI-PATTERNS ## ANTI-PATTERNS

6
src/tools/AGENTS.md
View File

@ -2,7 +2,7 @@
## OVERVIEW ## OVERVIEW
20+ tools: LSP (11), AST-Grep (2), Search (2), Session (4), Agent delegation (3), System (2). High-performance C++ bindings via @ast-grep/napi. 20+ tools: LSP (6), AST-Grep (2), Search (2), Session (4), Agent delegation (4), System (2), Skill (3). High-performance C++ bindings via @ast-grep/napi.
## STRUCTURE ## STRUCTURE
@ -13,9 +13,9 @@ tools/
│ ├── tools.ts # Business logic, ToolDefinition │ ├── tools.ts # Business logic, ToolDefinition
│ ├── types.ts # Zod schemas │ ├── types.ts # Zod schemas
│ └── constants.ts # Fixed values, descriptions │ └── constants.ts # Fixed values, descriptions
├── lsp/ # 11 tools: goto_definition, references, symbols, diagnostics, rename ├── lsp/ # 6 tools: goto_definition, references, symbols, diagnostics, prepare_rename, rename
├── ast-grep/ # 2 tools: search, replace (25 languages via NAPI) ├── ast-grep/ # 2 tools: search, replace (25 languages via NAPI)
├── delegate-task/ # Category-based agent routing (761 lines) ├── delegate-task/ # Category-based agent routing (1027 lines)
├── session-manager/ # 4 tools: list, read, search, info ├── session-manager/ # 4 tools: list, read, search, info
├── grep/ # Custom grep with timeout/truncation ├── grep/ # Custom grep with timeout/truncation
├── glob/ # Custom glob with 60s timeout, 100 file limit ├── glob/ # Custom glob with 60s timeout, 100 file limit