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
**Generated:** 2026-01-20T17:18:00+09:00
**Commit:** 3d3d3e49
**Generated:** 2026-01-22T22:25:00+09:00
**Commit:** 85bf266f
**Branch:** dev
## 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
```
oh-my-opencode/
├── 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
│ ├── 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
│ ├── 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
│ ├── 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
│ └── index.ts # Main plugin entry (589 lines)
├── 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 |
| 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 |
| 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 |
| 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 |
| Orchestrator | `src/hooks/atlas/` | Main orchestration hook (771 lines) |
| Orchestrator hook | `src/hooks/atlas/` | Main orchestration hook (771 lines) |
## TDD (Test-Driven Development)
@ -144,14 +144,14 @@ bun test # Run tests (83 test files)
| File | Lines | Description |
|------|-------|-------------|
| `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/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/tools/delegate-task/tools.ts` | 770 | Category-based task delegation |
| `src/cli/config-manager.ts` | 616 | JSONC parsing, multi-level config |
| `src/agents/sisyphus.ts` | 615 | Main Sisyphus prompt |
| `src/cli/config-manager.ts` | 641 | JSONC parsing, multi-level config |
| `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 |
## MCP ARCHITECTURE
@ -171,7 +171,7 @@ Three-tier MCP system:
## NOTES
- **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)
- **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

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`.
## 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
**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:
1. Prioritizes native provider subscriptions (Claude, OpenAI, Gemini)
2. Falls back through alternative providers in priority order
3. Applies capability-specific logic (e.g., Oracle prefers GPT, visual tasks prefer Gemini)
**Solution**: A simple 3-step resolution flow:
1. **Step 1: User Override** — If you specify a model in `oh-my-opencode.json`, use exactly that
2. **Step 2: Provider Fallback** — Try each provider in the requirement's priority order until one is available
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 │ │
│ │ (Your direct subscriptions) │ │
│ │ │ │
│ │ Claude (anthropic/) ──► OpenAI (openai/) ──► Gemini │ │
│ │ │ │ (google/) │ │
│ │ ▼ ▼ │ │ │
│ │ Opus/Sonnet/Haiku GPT-5.2/Codex Gemini 3 Pro │ │
│ │ User specified model in oh-my-opencode.json? │ │
│ │ YES → Use exactly as specified │ │
│ │ NO → Continue to Step 2 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ (if no native available) │
│ ▼ │
│ Step 2: PROVIDER PRIORITY FALLBACK │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ TIER 2: OPENCODE ZEN │ │
│ │ (opencode/ prefix models) │ │
│ │ For each provider in requirement.providers order: │ │
│ │ │ │
│ │ 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 │ │
│ │ (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 │ │
│ │ Return systemDefaultModel (from opencode.json) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 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 |
|------------|------------|------------|------------|
| **High-tier tasks** (Sisyphus, Atlas) | Claude Opus | OpenAI GPT-5.2 | Gemini 3 Pro |
| **Standard tasks** | Claude Sonnet | OpenAI GPT-5.2 | Gemini 3 Flash |
| **Quick tasks** | Claude Haiku | OpenAI GPT-5.1-mini | Gemini 3 Flash |
| **Deep reasoning** (Oracle) | OpenAI GPT-5.2-Codex | Claude Opus | Gemini 3 Pro |
| **Visual/UI tasks** | Gemini 3 Pro | OpenAI GPT-5.2 | Claude Sonnet |
| **Writing tasks** | Gemini 3 Flash | OpenAI GPT-5.2 | Claude Sonnet |
| Agent | Model (no prefix) | Provider Priority Chain |
|-------|-------------------|-------------------------|
| **Sisyphus** | `claude-opus-4-5` | anthropic → github-copilot → opencode → antigravity → google |
| **oracle** | `gpt-5.2` | openai → anthropic → google → github-copilot → opencode |
| **librarian** | `glm-4.7-free` | opencode → github-copilot → anthropic |
| **explore** | `grok-code` | opencode → anthropic → github-copilot |
| **multimodal-looker** | `gemini-3-pro-preview` | google → openai → anthropic → github-copilot → opencode |
| **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) |
|-------|------------|-------------------------------------|
| **Sisyphus** | High-tier (isMax20) or Standard | `anthropic/claude-opus-4-5` or `anthropic/claude-sonnet-4-5` |
| **Oracle** | Deep reasoning | `openai/gpt-5.2-codex` |
| **Prometheus** | High-tier/Standard | Same as Sisyphus |
| **Metis** | High-tier/Standard | Same as Sisyphus |
| **Momus** | Deep reasoning | `openai/gpt-5.2-codex` |
| **Atlas** | High-tier/Standard | Same as Sisyphus |
| **multimodal-looker** | Visual | `google/gemini-3-pro-preview` |
| Category | Model (no prefix) | Provider Priority Chain |
|----------|-------------------|-------------------------|
| **visual-engineering** | `gemini-3-pro-preview` | google → openai → anthropic → github-copilot → opencode |
| **ultrabrain** | `gpt-5.2-codex` | openai → anthropic → google → github-copilot → opencode |
| **artistry** | `gemini-3-pro-preview` | google → openai → anthropic → github-copilot → opencode |
| **quick** | `claude-haiku-4-5` | anthropic → github-copilot → opencode → antigravity → google |
| **unspecified-low** | `claude-sonnet-4-5` | anthropic → github-copilot → opencode → antigravity → google |
| **unspecified-high** | `claude-opus-4-5` | anthropic → github-copilot → opencode → antigravity → google |
| **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:
```
┌────────────────────────────────────────┐
│ 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 │
└────────────────────────────────────────┘
```bash
bunx oh-my-opencode doctor --verbose
```
#### Special Case: librarian Agent
The `librarian` agent prioritizes Z.ai when available:
```
┌────────────────────────────────────────┐
│ 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.
The "Model Resolution" check shows:
- Each agent/category's model requirement
- Provider fallback chain
- User overrides (if configured)
- Effective resolution path
### 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
{
"agents": {
"Sisyphus": {
"model": "anthropic/claude-sonnet-4-5" // Force specific model
"model": "anthropic/claude-sonnet-4-5"
},
"oracle": {
"model": "openai/o3" // Use different model
"model": "openai/o3"
}
},
"categories": {
"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
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
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
```
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-junior.ts # Delegated task executor
├── dynamic-agent-prompt-builder.ts # Dynamic prompt generation
├── sisyphus-junior.ts # Delegated task executor (136 lines)
├── dynamic-agent-prompt-builder.ts # Dynamic prompt generation (360 lines)
├── oracle.ts # Strategic advisor (GPT-5.2)
├── librarian.ts # Multi-repo research (GLM-4.7-free)
├── explore.ts # Fast grep (Grok Code)
@ -19,8 +19,8 @@ agents/
├── prometheus-prompt.ts # Planning (1196 lines) - interview mode
├── metis.ts # Plan consultant - pre-planning analysis
├── momus.ts # Plan reviewer - validation
├── types.ts # AgentModelConfig interface
├── utils.ts # createBuiltinAgents(), getAgentName()
├── types.ts # AgentModelConfig, AgentPromptMetadata
├── utils.ts # createBuiltinAgents(), resolveModelWithFallback()
└── index.ts # builtinAgents export
```
@ -29,18 +29,20 @@ agents/
| Agent | Model | Temperature | Purpose |
|-------|-------|-------------|---------|
| 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 |
| librarian | opencode/glm-4.7-free | 0.1 | Docs, GitHub search, OSS examples |
| explore | opencode/grok-code | 0.1 | Fast contextual grep |
| multimodal-looker | google/gemini-3-flash | 0.1 | PDF/image analysis |
| 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 |
| Sisyphus-Junior | anthropic/claude-sonnet-4-5 | 0.1 | Category-spawned executor |
## HOW TO ADD
1. Create `src/agents/my-agent.ts` exporting `AgentConfig`
2. Add to `builtinAgents` in `src/agents/index.ts`
1. Create `src/agents/my-agent.ts` exporting factory + metadata
2. Add to `agentSources` in `src/agents/utils.ts`
3. Update `AgentNameSchema` in `src/config/schema.ts`
4. Register in `src/index.ts` initialization
@ -51,17 +53,20 @@ agents/
| oracle | write, edit, task, delegate_task |
| librarian | 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
- **Factory**: `createXXXAgent(model?: string): AgentConfig`
- **Metadata**: `XXX_PROMPT_METADATA: AgentPromptMetadata`
- **Tool restrictions**: `permission: { edit: "deny", bash: "ask" }`
- **Thinking**: 32k budget tokens for Sisyphus, Oracle, Prometheus
- **Metadata**: `XXX_PROMPT_METADATA: AgentPromptMetadata` with category, cost, triggers
- **Tool restrictions**: `createAgentToolRestrictions(tools)` or `createAgentToolAllowlist(tools)`
- **Thinking**: 32k budget tokens for Sisyphus, Oracle, Prometheus, Atlas
- **Model-specific**: GPT uses `reasoningEffort`, Anthropic uses `thinking` budget
## ANTI-PATTERNS
- **Trust reports**: NEVER trust subagent "I'm done" - verify outputs
- **High temp**: Don't use >0.3 for code agents
- **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/
├── index.ts # Commander.js entry, 5 subcommands
├── install.ts # Interactive TUI installer (462 lines)
├── config-manager.ts # JSONC parsing, multi-level merge (730 lines)
├── install.ts # Interactive TUI installer (520 lines)
├── config-manager.ts # JSONC parsing, multi-level merge (641 lines)
├── types.ts # InstallArgs, InstallConfig, DetectedConfig
├── doctor/
│ ├── index.ts # Doctor command entry
@ -18,7 +18,7 @@ cli/
│ ├── formatter.ts # Colored output, symbols
│ ├── constants.ts # Check IDs, categories, symbols
│ ├── types.ts # CheckResult, CheckDefinition
│ └── checks/ # 14 checks across 6 categories
│ └── checks/ # 14 checks across 6 categories (21 files)
│ ├── version.ts # OpenCode + plugin version
│ ├── config.ts # JSONC validity, Zod validation
│ ├── 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/
├── background-agent/ # Task lifecycle (1165 lines manager.ts)
├── background-agent/ # Task lifecycle (1335 lines manager.ts)
│ ├── manager.ts # Launch → poll → complete orchestration
│ ├── concurrency.ts # Per-provider/model limits
│ └── types.ts # BackgroundTask, LaunchInput
├── skill-mcp-manager/ # MCP client lifecycle
├── skill-mcp-manager/ # MCP client lifecycle (520 lines)
│ ├── manager.ts # Lazy loading, idle cleanup
│ └── types.ts # SkillMcpConfig, transports
├── builtin-skills/ # Playwright, git-master, frontend-ui-ux
@ -24,7 +24,7 @@ features/
├── claude-code-mcp-loader/ # .mcp.json with ${VAR} expansion
├── claude-code-plugin-loader/ # installed_plugins.json
├── 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
├── boulder-state/ # Todo state persistence
├── 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
├── todo-continuation-enforcer.ts # Force TODO completion
├── 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
├── auto-slash-command/ # Detects /command patterns
├── rules-injector/ # Conditional rules from .claude/rules/
@ -26,6 +26,9 @@ hooks/
├── think-mode/ # Dynamic thinking budget
├── keyword-detector/ # ultrawork/search/analyze modes
├── 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
```

15
src/shared/AGENTS.md
View File

@ -2,7 +2,7 @@
## 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
@ -22,6 +22,11 @@ shared/
├── env-expander.ts # ${VAR} expansion in configs
├── system-directive.ts # System directive types
├── 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)
```
@ -37,6 +42,11 @@ shared/
| Resolve paths | `getOpenCodeConfigDir()`, `getClaudeConfigDir()` |
| Migrate config | `migrateConfigFile(path, rawConfig)` |
| 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
@ -52,6 +62,9 @@ if (isOpenCodeVersionAtLeast("1.1.0")) { /* new feature */ }
// Tool permission normalization
const permissions = migrateToolsToPermission(legacyTools)
// Model resolution with fallback chain
const model = await resolveModelWithFallback(client, requirements, override)
```
## ANTI-PATTERNS

6
src/tools/AGENTS.md
View File

@ -2,7 +2,7 @@
## 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
@ -13,9 +13,9 @@ tools/
│ ├── tools.ts # Business logic, ToolDefinition
│ ├── types.ts # Zod schemas
│ └── 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)
├── delegate-task/ # Category-based agent routing (761 lines)
├── delegate-task/ # Category-based agent routing (1027 lines)
├── session-manager/ # 4 tools: list, read, search, info
├── grep/ # Custom grep with timeout/truncation
├── glob/ # Custom glob with 60s timeout, 100 file limit