diff --git a/docs/examples/coding-focused.jsonc b/docs/examples/coding-focused.jsonc
index f81be175e..2d94eda2f 100644
--- a/docs/examples/coding-focused.jsonc
+++ b/docs/examples/coding-focused.jsonc
@@ -1,5 +1,5 @@
{
- "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
+ "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-openagent.schema.json",
// Optimized for intensive coding sessions.
// Prioritizes deep implementation agents and fast feedback loops.
diff --git a/docs/examples/default.jsonc b/docs/examples/default.jsonc
index 611f7534b..e5c7cb6a7 100644
--- a/docs/examples/default.jsonc
+++ b/docs/examples/default.jsonc
@@ -1,5 +1,5 @@
{
- "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
+ "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-openagent.schema.json",
// Balanced defaults for general development.
// Tuned for reliability across diverse tasks without overspending.
diff --git a/docs/examples/planning-focused.jsonc b/docs/examples/planning-focused.jsonc
index 1aa096df3..3136ccdc5 100644
--- a/docs/examples/planning-focused.jsonc
+++ b/docs/examples/planning-focused.jsonc
@@ -1,5 +1,5 @@
{
- "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
+ "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-openagent.schema.json",
// Optimized for strategic planning, architecture, and complex project design.
// Prioritizes deep thinking agents and thorough analysis before execution.
diff --git a/docs/guide/agent-model-matching.md b/docs/guide/agent-model-matching.md
index 3517fcf6f..f5f0b4189 100644
--- a/docs/guide/agent-model-matching.md
+++ b/docs/guide/agent-model-matching.md
@@ -332,7 +332,7 @@ See the [Orchestration System Guide](./orchestration.md) for how agents dispatch
```jsonc
{
- "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
+ "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-openagent.schema.json",
"agents": {
// Sisyphus: Kimi K2.6 is the top alternative to Claude for orchestration
diff --git a/docs/guide/installation.md b/docs/guide/installation.md
index f6fe0aed0..afaac80b9 100644
--- a/docs/guide/installation.md
+++ b/docs/guide/installation.md
@@ -15,12 +15,13 @@ Run the interactive installer:
```bash
bunx oh-my-openagent install # recommended
-npx oh-my-openagent install # alternative
```
+Use Bun only for installation. Do not use npm, yarn, or pnpm.
+
> **Note**: The CLI ships with standalone binaries for all major platforms. No runtime (Bun/Node.js) is required for CLI execution after installation.
>
-> **Supported platforms**: macOS (ARM64, x64), Linux (x64, ARM64, Alpine/musl), Windows (x64)
+> **Supported platforms**: 11 platform binaries across macOS (ARM64, x64, x64-baseline), Linux (x64, x64-baseline, x64-musl, x64-musl-baseline, ARM64, ARM64-musl), and Windows (x64, x64-baseline)
Follow the prompts to configure your Claude, ChatGPT, and Gemini subscriptions. After installation, authenticate your providers as instructed.
@@ -28,7 +29,23 @@ Anonymous telemetry is enabled by default to track active installations (DAU/WAU
After you install it, you can read this [overview guide](./overview.md) to understand more.
-The published package and local binary are still `oh-my-opencode`. Inside `opencode.json`, the compatibility layer now prefers the plugin entry `oh-my-openagent`, while legacy `oh-my-opencode` entries still load with a warning. Plugin config loading recognizes both `oh-my-openagent.json[c]` and `oh-my-opencode.json[c]` during the transition. If you see a "Using legacy package name" warning from `bunx oh-my-openagent doctor`, update your `opencode.json` plugin entry from `"oh-my-opencode"` to `"oh-my-openagent"`.
+The project is dual-published during the rename transition: `oh-my-openagent` and `oh-my-opencode` are both published package names. Inside `opencode.json`, the compatibility layer now prefers the plugin entry `oh-my-openagent`, while legacy `oh-my-opencode` entries still load with a warning. Plugin config loading recognizes both `oh-my-openagent.json[c]` and `oh-my-opencode.json[c]` during the transition. If you see a "Using legacy package name" warning from `bunx oh-my-openagent doctor`, update your `opencode.json` plugin entry from `"oh-my-opencode"` to `"oh-my-openagent"`.
+
+Postinstall validates both platform binary resolution and OpenCode version compatibility.
+
+Core CLI subcommands are: `install`, `run`, `doctor`, `mcp-oauth`, `refresh-model-capabilities`, and `get-local-version`.
+
+Config schema URL:
+
+```json
+"$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-openagent.schema.json"
+```
+
+Operational notes:
+
+- Claude Code compatibility is supported.
+- Claude Code plugin discovery load timeout is 10 seconds.
+- Runtime logger path: `/tmp/oh-my-opencode.log`
## For LLM Agents
diff --git a/docs/guide/orchestration.md b/docs/guide/orchestration.md
index c091dd948..dc50b10bd 100644
--- a/docs/guide/orchestration.md
+++ b/docs/guide/orchestration.md
@@ -41,11 +41,11 @@ flowchart TB
end
subgraph Execution["Execution Layer (Orchestrator)"]
- Orchestrator[" Atlas
(Conductor)
claude-sonnet-4-6 / kimi-k2.5 / gpt-5.5 / minimax-m2.7"]
+ Orchestrator[" Atlas
(Conductor)
claude-sonnet-4-6 / kimi-k2.6 / gpt-5.5 / minimax-m2.7"]
end
subgraph Workers["Worker Layer (Specialized Agents)"]
- Junior[" Sisyphus-Junior
(Task Executor)
claude-sonnet-4-6 / kimi-k2.5 / gpt-5.5 / minimax-m2.7"]
+ Junior[" Sisyphus-Junior
(Task Executor)
claude-sonnet-4-6 / kimi-k2.6 / gpt-5.5 / minimax-m2.7"]
Oracle[" Oracle
(Architecture)
gpt-5.5 / gemini-3.1-pro / claude-opus-4-7 / glm-5"]
Explore[" Explore
(Codebase Grep)
gpt-5.4-mini-fast / minimax-m2.7-highspeed / claude-haiku-4-5"]
Librarian[" Librarian
(Docs/OSS)
gpt-5.4-mini-fast / minimax-m2.7-highspeed / claude-haiku-4-5"]
@@ -77,6 +77,28 @@ flowchart TB
Model labels above show the current fallback stacks from `src/shared/model-requirements.ts`, not marketing names.
+### Agent Inventory and Modes (Current)
+
+The system has **11 built-in agents**:
+
+- Primary: `sisyphus`, `hephaestus`, `prometheus`, `atlas`
+- Subagent: `oracle`, `librarian`, `explore`, `multimodal-looker`, `metis`, `momus`, `sisyphus-junior`
+
+Canonical assembly order for primary agents is:
+
+`Sisyphus → Hephaestus → Prometheus → Atlas`
+
+Mode distinction:
+
+- `mode: "primary"`: top-level session agents selected directly in UI/CLI
+- `mode: "subagent"`: worker/consultant agents invoked via `task(..., subagent_type="...")` or `call_omo_agent(...)`
+
+### Delegation Semantics (Important)
+
+- `task(category="...")` routes to **Sisyphus-Junior** with category-optimized model routing
+- `task(subagent_type="...")` invokes that specific agent directly (for example `oracle`, `explore`, `librarian`)
+- Category and `subagent_type` are mutually exclusive inputs in one call
+
---
## Planning: Prometheus + Metis + Momus
@@ -294,18 +316,17 @@ task({ category: "visual-engineering", prompt: "..." }); // "Design beautifully"
task({ category: "quick", prompt: "..." }); // "Just get it done fast"
```
-### Built-in Categories
+### Delegate-Task Categories
-| Category | Default config | Runtime fallback order | When to Use |
-| -------------------- | ------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
-| `visual-engineering` | `google/gemini-3.1-pro high` | `gemini-3.1-pro` → `glm-5` → `claude-opus-4-7` → `glm-5` → `k2p5` | Frontend, UI/UX, design, styling, animation |
-| `ultrabrain` | `openai/gpt-5.5 xhigh` | `gpt-5.5` → `gemini-3.1-pro` → `claude-opus-4-7` → `glm-5` | Deep logical reasoning, complex architecture decisions |
-| `deep` | `openai/gpt-5.5 medium` | `gpt-5.5` → `claude-opus-4-7` → `gemini-3.1-pro` | Goal-oriented autonomous problem-solving, thorough research |
-| `artistry` | `google/gemini-3.1-pro high` | `gemini-3.1-pro` → `claude-opus-4-7` → `gpt-5.5` | Highly creative or artistic tasks, novel ideas |
-| `quick` | `openai/gpt-5.4-mini` | `gpt-5.4-mini` → `claude-haiku-4-5` → `gemini-3-flash` → `minimax-m2.7` → `gpt-5-nano` | Trivial tasks, single file changes, typo fixes |
-| `unspecified-low` | `anthropic/claude-sonnet-4-6` | `claude-sonnet-4-6` → `gpt-5.3-codex` → `kimi-k2.5` → `gemini-3-flash` → `minimax-m2.7` | Tasks that don't fit other categories, low effort |
-| `unspecified-high` | `anthropic/claude-opus-4-7 max` | `claude-opus-4-7` → `gpt-5.5` → `glm-5` → `k2p5` → `kimi-k2.5` | Tasks that don't fit other categories, high effort |
-| `writing` | `kimi-for-coding/k2p5` | `gemini-3-flash` → `kimi-k2.5` → `claude-sonnet-4-6` → `minimax-m2.7` | Documentation, prose, technical writing |
+`task(category="...")` supports these category names in user-facing orchestration:
+
+`visual-engineering`, `artistry`, `ultrabrain`, `deep`, `quick`, `unspecified-low`, `unspecified-high`, `writing`, `quick-rust`, `quick-zig`, `git`
+
+Notes:
+
+- Built-in defaults are defined in `src/tools/delegate-task/*-categories.ts` and `src/shared/model-requirements.ts`
+- Projects/users can extend categories via config; additional category names may appear in your session prompt
+- Regardless of category name, category dispatch goes through Sisyphus-Junior
### Skills: Domain-Specific Instructions
@@ -326,6 +347,40 @@ task(
);
```
+Skill loading priority is:
+
+`project > opencode > user > builtin`
+
+### Skill MCP (Tier 3)
+
+Skill-embedded MCP servers are isolated per session using a composite key pattern:
+
+`${sessionID}:${skillName}:${serverName}`
+
+This prevents state bleed across sessions when the same skill/MCP is used concurrently.
+
+### Background Task Concurrency
+
+Background task concurrency defaults to **5** when no overrides are configured.
+
+- Keyed by model/provider routing key
+- Configurable via `background_task.defaultConcurrency`, `background_task.providerConcurrency`, and `background_task.modelConcurrency`
+
+### Team Mode
+
+Team mode is parallel multi-agent orchestration and is **OFF by default**.
+
+For `subagent_type` team members, current eligibility is:
+
+- Eligible: `sisyphus`, `atlas`, `sisyphus-junior`
+- Conditional: `hephaestus` (requires teammate permission enablement)
+- Hard-reject: `oracle`, `librarian`, `explore`, `multimodal-looker`, `metis`, `momus`, `prometheus`
+
+Why `oracle`/`prometheus` are rejected in team members:
+
+- Oracle is read-only (cannot write/edit/patch/delegate)
+- Prometheus is constrained to `.sisyphus/*.md` writes by the `prometheus-md-only` hook
+
---
## Usage Patterns
diff --git a/docs/guide/overview.md b/docs/guide/overview.md
index 21443a68a..bcb734b0b 100644
--- a/docs/guide/overview.md
+++ b/docs/guide/overview.md
@@ -54,7 +54,7 @@ Instead of one agent doing everything, Oh My OpenAgent uses **specialized agents
```
User Request
↓
-[Intent Gate] — Classifies what you actually want
+[IntentGate] — Classifies what you actually want
↓
[Sisyphus] — Main orchestrator, plans and delegates
↓
@@ -248,7 +248,7 @@ Oh My OpenAgent turns that into a coordinated team:
**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.
+**IntentGate.** 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.
@@ -260,7 +260,7 @@ Oh My OpenAgent turns that into a coordinated team:
---
-## The Intent Gate
+## IntentGate
Before acting on any request, Sisyphus classifies your true intent.
diff --git a/docs/guide/team-mode.md b/docs/guide/team-mode.md
index 05ec799d4..1396e2a95 100644
--- a/docs/guide/team-mode.md
+++ b/docs/guide/team-mode.md
@@ -14,7 +14,7 @@ OFF by default. Enable via JSONC config.
## Enable
-Add to `~/.config/opencode/oh-my-opencode.jsonc` (or project `.opencode/oh-my-opencode.jsonc`):
+Add to user config `~/.config/opencode/oh-my-openagent.jsonc` or project config `.opencode/oh-my-openagent.jsonc`:
```jsonc
{
@@ -29,9 +29,25 @@ Add to `~/.config/opencode/oh-my-opencode.jsonc` (or project `.opencode/oh-my-op
After enabling, restart opencode. The 12 `team_*` tools become available.
+## Config schema (11 fields)
+
+All fields live under `team_mode`:
+
+- `enabled` (boolean, default `false`)
+- `tmux_visualization` (boolean, default `false`)
+- `max_parallel_members` (int, `1..8`, default `4`)
+- `max_members` (int, `1..8`, default `8`)
+- `max_messages_per_run` (int, `>=1`, default `10000`)
+- `max_wall_clock_minutes` (int, `>=1`, default `120`)
+- `max_member_turns` (int, `>=1`, default `500`)
+- `base_dir` (optional string; default resolves to `~/.omo`)
+- `message_payload_max_bytes` (int, `>=1024`, default `32768`)
+- `recipient_unread_max_bytes` (int, `>=1024`, default `262144`)
+- `mailbox_poll_interval_ms` (int, `>=500`, default `3000`)
+
## Define a team
-Teams live as directories under `~/.omo/teams/{name}/config.json`:
+Team specs live under `~/.omo/teams/{name}/config.json` (user scope) or `/.omo/teams/{name}/config.json` (project scope):
```json
{
@@ -45,7 +61,7 @@ Teams live as directories under `~/.omo/teams/{name}/config.json`:
}
```
-Project-scoped variant: `/.omo/teams/{name}/config.json` (project beats user on collisions).
+When both scopes define the same team name, project scope wins.
`version`, `createdAt`, and `leadAgentId` are optional in config files. The loader fills them automatically. You can either write a top-level `lead: {...}` shorthand, mark one member with `isLead: true`, or omit both when the team has exactly one member.
@@ -56,7 +72,11 @@ Project-scoped variant: `/.omo/teams/{name}/config.json` (project beats
## Eligible agents
-Only **sisyphus, atlas, sisyphus-junior, hephaestus** can be members. Read-only and orchestration-only agents (`oracle`, `librarian`, `explore`, `multimodal-looker`, `metis`, `momus`, `prometheus`) are rejected at parse time. Use `delegate-task` for those.
+- **Eligible:** `sisyphus`, `atlas`, `sisyphus-junior`.
+- **Conditional:** `hephaestus` (needs teammate permission `teammate: "allow"`; otherwise use `subagent_type: "sisyphus"`).
+- **Hard-reject:** `oracle`, `librarian`, `explore`, `multimodal-looker`, `metis`, `momus`, `prometheus`.
+
+Hard-reject agents fail TeamSpec parsing because they cannot write mailbox state. Use `delegate-task` for those agents.
## Lifecycle
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index bc8892dd7..ca33f7614 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -1,337 +1,167 @@
# CLI Reference
-Complete reference for the published `oh-my-opencode` CLI. During the rename transition, OpenCode plugin registration now prefers `oh-my-openagent` inside `opencode.json`.
+Complete reference for the published CLI package. During the rename transition, both package names work:
+
+- `oh-my-openagent` (preferred package name)
+- `oh-my-opencode` (compatibility package name)
+
+Plugin registration inside `opencode.json` prefers `oh-my-openagent`.
## Basic Usage
```bash
-# Display help
-bunx oh-my-opencode
+# Display help (preferred package)
+bunx oh-my-openagent
-# Or with npx
-npx oh-my-opencode
+# Compatibility package
+bunx oh-my-opencode
```
## Commands
-| Command | Description |
-| ----------------------------- | ------------------------------------------------------ |
-| `install` | Interactive setup wizard |
-| `doctor` | Environment diagnostics and health checks |
-| `run` | OpenCode session runner with task completion enforcement |
-| `get-local-version` | Display local version information and update check |
-| `refresh-model-capabilities` | Refresh the cached models.dev-based model capabilities |
-| `version` | Show version information |
-| `mcp oauth` | MCP OAuth authentication management |
+| Command | Description |
+| --- | --- |
+| `install` | Interactive setup wizard |
+| `doctor` | Installation health diagnostics |
+| `run ` | Non-interactive OpenCode session runner with completion enforcement |
+| `get-local-version` | Show current installed version and check for updates |
+| `refresh-model-capabilities` | Refresh cached model capabilities snapshot from models.dev |
+| `version` | Show CLI version |
+| `mcp oauth` | OAuth token management for MCP servers |
---
## install
-Interactive installation tool for initial Oh My OpenCode setup. Provides a TUI based on `@clack/prompts`.
+Interactive installation tool for initial setup.
### Usage
```bash
-bunx oh-my-opencode install
+bunx oh-my-openagent install
```
-### Installation Process
-
-1. **Subscription Selection**: Choose which providers and subscriptions you actually have
-2. **Plugin Registration**: Registers `oh-my-openagent` in OpenCode settings, or upgrades a legacy `oh-my-opencode` entry during the compatibility window
-3. **Configuration File Creation**: Writes the generated OmO config to `oh-my-opencode.json` in the active OpenCode config directory
-4. **Authentication Hints**: Shows the `opencode auth login` steps for the providers you selected, unless `--skip-auth` is set
-5. **Telemetry Defaults**: Anonymous telemetry remains enabled unless you opt out through environment variables
-
### Options
| Option | Description |
-| ------ | ----------- |
-| `--no-tui` | Run in non-interactive mode without TUI |
-| `--claude ` | Claude subscription mode |
-| `--openai ` | OpenAI / ChatGPT subscription |
-| `--gemini ` | Gemini integration |
-| `--copilot ` | GitHub Copilot subscription |
-| `--opencode-zen ` | OpenCode Zen access |
-| `--zai-coding-plan ` | Z.ai Coding Plan subscription |
-| `--kimi-for-coding ` | Kimi for Coding subscription |
-| `--opencode-go ` | OpenCode Go subscription |
-| `--vercel-ai-gateway ` | Vercel AI Gateway: no, yes (default: no) |
+| --- | --- |
+| `--no-tui` | Run in non-interactive mode (requires all needed options) |
+| `--claude ` | Claude subscription: `no`, `yes`, `max20` |
+| `--openai ` | OpenAI/ChatGPT subscription: `no`, `yes` |
+| `--gemini ` | Gemini integration: `no`, `yes` |
+| `--copilot ` | GitHub Copilot subscription: `no`, `yes` |
+| `--opencode-zen ` | OpenCode Zen access: `no`, `yes` |
+| `--zai-coding-plan ` | Z.ai Coding Plan subscription: `no`, `yes` |
+| `--kimi-for-coding ` | Kimi For Coding subscription: `no`, `yes` |
+| `--opencode-go ` | OpenCode Go subscription: `no`, `yes` |
+| `--vercel-ai-gateway ` | Vercel AI Gateway: `no`, `yes` |
| `--skip-auth` | Skip authentication setup hints |
-Anonymous telemetry uses PostHog with a hashed installation identifier. Disable it with `OMO_SEND_ANONYMOUS_TELEMETRY=0` or `OMO_DISABLE_POSTHOG=1`. See [Privacy Policy](../legal/privacy-policy.md).
+Anonymous telemetry uses PostHog with a hashed installation identifier. Disable with `OMO_SEND_ANONYMOUS_TELEMETRY=0` or `OMO_DISABLE_POSTHOG=1`.
---
## doctor
-Diagnoses your environment to ensure Oh My OpenCode is functioning correctly. The current checks are grouped into system, config, tools, and models.
+Diagnoses your environment and configuration. Checks are grouped into four categories: **System**, **Config**, **Tools**, and **Models**.
-The doctor command detects common issues including:
-- Legacy plugin entry references in `opencode.json` (warns when `oh-my-opencode` is still used instead of `oh-my-openagent`)
-- Configuration file validity and JSONC parsing errors
-- Model resolution and fallback chain verification
-- Missing or misconfigured MCP servers
### Usage
```bash
-bunx oh-my-opencode doctor
+bunx oh-my-openagent doctor
```
-### Diagnostic Categories
-
-| Category | Check Items |
-| ----------------- | ------------------------------------------------------------------------------------ |
-| **System** | OpenCode binary, version (>= 1.0.150), plugin registration, legacy package name warning |
-| **Config** | Configuration file validity, JSONC parsing, Zod schema validation |
-| **Tools** | AST-Grep, LSP servers, GitHub CLI, MCP servers |
-| **Models** | Model capabilities cache, model resolution, agent/category overrides, availability |
-
### Options
-| Option | Description |
-| ------------ | ----------------------------------------- |
-| `--status` | Show compact system dashboard |
-| `--verbose` | Show detailed diagnostic information |
-| `--json` | Output results in JSON format |
+| Option | Description |
+| --- | --- |
+| `--status` | Show compact system dashboard |
+| `--verbose` | Show detailed diagnostic information |
+| `--json` | Output results in JSON format |
-### Example Output
+### Notes
-```
-oh-my-opencode doctor
+- The current minimum OpenCode version check is `>= 1.4.0`.
+- The doctor command warns when legacy plugin registration (`oh-my-opencode`) is still present in `opencode.json`.
-┌──────────────────────────────────────────────────┐
-│ Oh-My-OpenAgent Doctor │
-└──────────────────────────────────────────────────┘
-
-System
- ✓ OpenCode version: 1.0.155 (>= 1.0.150)
- ✓ Plugin registered in opencode.json
-
-Config
- ✓ oh-my-opencode.jsonc is valid
- ✓ Model resolution: all agents have valid fallback chains
- ⚠ categories.visual-engineering: using default model
-
-Tools
- ✓ AST-Grep available
- ✓ LSP servers configured
-
-Models
- ✓ 11 agents, 8 categories, 0 overrides
- ⚠ Some configured models rely on compatibility fallback
-
-Summary: 10 passed, 1 warning, 0 failed
-```
---
## run
-Run opencode with todo/background task completion enforcement. Unlike 'opencode run', this command waits until all todos are completed or cancelled, and all child sessions (background tasks) are idle.
+Runs a non-interactive session and exits only when both conditions are true:
+
+- all todos are completed or cancelled
+- all background child sessions are idle
### Usage
```bash
-bunx oh-my-opencode run
+bunx oh-my-openagent run
```
### Options
-| Option | Description |
-| --------------------- | ------------------------------------------------------------------- |
-| `-a, --agent ` | Agent to use (default: from CLI/env/config, fallback: Sisyphus) |
-| `-m, --model ` | Model override (e.g., anthropic/claude-sonnet-4) |
-| `-d, --directory ` | Working directory |
-| `-p, --port ` | Server port (attaches if port already in use) |
-| `--attach ` | Attach to existing opencode server URL |
-| `--on-complete ` | Shell command to run after completion |
-| `--json` | Output structured JSON result to stdout |
-| `--no-timestamp` | Disable timestamp prefix in run output |
-| `--verbose` | Show full event stream (default: messages/tools only) |
-| `--session-id ` | Resume existing session instead of creating new one |
+| Option | Description |
+| --- | --- |
+| `-a, --agent ` | Agent to use (default resolution chain applies) |
+| `-m, --model ` | Model override (example: `anthropic/claude-sonnet-4`) |
+| `-d, --directory ` | Working directory |
+| `-p, --port ` | Server port (attaches if already in use) |
+| `--attach ` | Attach to an existing OpenCode server URL |
+| `--on-complete ` | Run shell command after completion |
+| `--json` | Output structured JSON result |
+| `--no-timestamp` | Disable timestamp prefix in output |
+| `--verbose` | Show full event stream (default: messages/tools only) |
+| `--session-id ` | Resume an existing session |
+
+### Agent Resolution Order
+
+1. `--agent`
+2. `OPENCODE_DEFAULT_AGENT`
+3. `default_run_agent` in plugin config
+4. `Sisyphus`
---
## get-local-version
-Show current installed version and check for updates.
+Shows local plugin version state and update status.
### Usage
```bash
-bunx oh-my-opencode get-local-version
+bunx oh-my-openagent get-local-version
```
### Options
-| Option | Description |
-| ----------------- | ---------------------------------------------- |
-| `-d, --directory` | Working directory to check config from |
-| `--json` | Output in JSON format for scripting |
+| Option | Description |
+| --- | --- |
+| `-d, --directory ` | Working directory used for plugin/config detection |
+| `--json` | Output JSON for scripting |
-### Output
-
-Shows:
-- Current installed version
-- Latest available version on npm
-- Whether you're up to date
-- Special modes (local dev, pinned version)
-
----
-
-## version
-
-Show version information.
-
-### Usage
-
-```bash
-bunx oh-my-opencode version
-```
-
-`--on-complete` runs through your current shell when possible: `sh` on Unix shells, `pwsh` for PowerShell on non-Windows, `powershell.exe` for PowerShell on Windows, and `cmd.exe` as the Windows fallback.
-
----
-
-## mcp oauth
-
-Manages OAuth 2.1 authentication for remote MCP servers.
-
-### Usage
-
-```bash
-# Login to an OAuth-protected MCP server
-bunx oh-my-opencode mcp oauth login --server-url https://api.example.com
-
-# Login with explicit client ID and scopes
-bunx oh-my-opencode mcp oauth login my-api --server-url https://api.example.com --client-id my-client --scopes read write
-
-# Remove stored OAuth tokens
-bunx oh-my-opencode mcp oauth logout --server-url https://api.example.com
-
-# Check OAuth token status
-bunx oh-my-opencode mcp oauth status [server-name]
-```
-
-### Options
-
-| Option | Description |
-| -------------------- | ------------------------------------------------------------------------- |
-| `--server-url ` | MCP server URL (required for login) |
-| `--client-id ` | OAuth client ID (optional if server supports Dynamic Client Registration) |
-| `--scopes ` | OAuth scopes as separate variadic arguments (for example: `--scopes read write`) |
-
-### Token Storage
-
-Tokens are stored in `~/.config/opencode/mcp-oauth.json` with `0600` permissions (owner read/write only). Key format: `{serverHost}/{resource}`.
-
----
-
-## Configuration Files
-
-The runtime loads user config as the base config, then merges project config on top:
-
-1. **Project Level**: `.opencode/oh-my-openagent.jsonc`, `.opencode/oh-my-openagent.json`, `.opencode/oh-my-opencode.jsonc`, or `.opencode/oh-my-opencode.json`
-2. **User Level**: `~/.config/opencode/oh-my-openagent.jsonc`, `~/.config/opencode/oh-my-openagent.json`, `~/.config/opencode/oh-my-opencode.jsonc`, or `~/.config/opencode/oh-my-opencode.json`
-
-**Naming Note**: The published package and binary are still `oh-my-opencode`. Inside `opencode.json`, the compatibility layer now prefers the plugin entry `oh-my-openagent`. Plugin config loading recognizes both `oh-my-openagent.*` and legacy `oh-my-opencode.*` basenames. If both basenames exist in the same directory, the legacy `oh-my-opencode.*` file currently wins.
-
-### Filename Compatibility
-
-Both `.jsonc` and `.json` extensions are supported. JSONC (JSON with Comments) is preferred as it allows:
-- Comments (both `//` and `/* */` styles)
-- Trailing commas in arrays and objects
-
-If both `.jsonc` and `.json` exist in the same directory, the `.jsonc` file takes precedence.
-
-### JSONC Support
-
-Configuration files support **JSONC (JSON with Comments)** format. You can use comments and trailing commas.
-
-```jsonc
-{
- // Agent configuration
- "sisyphus_agent": {
- "disabled": false,
- "planner_enabled": true,
- },
-
- /* Category customization */
- "categories": {
- "visual-engineering": {
- "model": "google/gemini-3.1-pro",
- },
- },
-}
-```
-
----
-
-## Troubleshooting
-
-### "OpenCode version too old" Error
-
-```bash
-# Update OpenCode
-npm install -g opencode@latest
-# or
-bun install -g opencode@latest
-```
-
-### "Plugin not registered" Error
-
-```bash
-# Reinstall plugin
-bunx oh-my-opencode install
-```
-
-### Doctor Check Failures
-
-```bash
-# Diagnose with detailed information
-bunx oh-my-opencode doctor --verbose
-
-# Show compact system dashboard
-bunx oh-my-opencode doctor --status
-
-# JSON output for scripting
-bunx oh-my-opencode doctor --json
-```
-
-### "Using legacy package name" Warning
-
-The doctor warns if it finds the legacy plugin entry `oh-my-opencode` in `opencode.json`. Update the plugin array to the canonical `oh-my-openagent` entry:
-
-```bash
-# Replace the legacy plugin entry in user config
-jq '.plugin = (.plugin // [] | map(if . == "oh-my-opencode" then "oh-my-openagent" else . end))' \
- ~/.config/opencode/opencode.json > /tmp/opencode.json && mv /tmp/opencode.json ~/.config/opencode/opencode.json
-```
---
## refresh-model-capabilities
-Refreshes the cached model capabilities snapshot from models.dev. This updates the local cache used by capability resolution and compatibility diagnostics.
+Refreshes the cached model capabilities snapshot from models.dev.
### Usage
```bash
-bunx oh-my-opencode refresh-model-capabilities
+bunx oh-my-openagent refresh-model-capabilities
```
### Options
-| Option | Description |
-| ----------------- | --------------------------------------------------- |
-| `-d, --directory` | Working directory to read oh-my-opencode config from |
-| `--source-url ` | Override the models.dev source URL |
-| `--json` | Output refresh summary as JSON |
+| Option | Description |
+| --- | --- |
+| `-d, --directory ` | Working directory used to read plugin config |
+| `--source-url ` | Override models.dev source URL |
+| `--json` | Output refresh summary as JSON |
### Configuration
-Configure automatic refresh behavior in your plugin config:
-
```jsonc
{
"model_capabilities": {
@@ -345,63 +175,51 @@ Configure automatic refresh behavior in your plugin config:
---
-## Non-Interactive Mode
+## version
-Use JSON output for CI or scripted diagnostics.
+Shows CLI package version.
+
+### Usage
```bash
-# Run doctor in CI environment
-bunx oh-my-opencode doctor --json
-
-# Save results to file
-bunx oh-my-opencode doctor --json > doctor-report.json
+bunx oh-my-openagent version
```
---
-## Developer Information
+## mcp oauth
-### CLI Structure
+OAuth token management for MCP servers (Tier-3 MCP OAuth flow, including PKCE and dynamic client registration when supported by the server).
-```
-src/cli/
-├── cli-program.ts # Commander.js-based main entry
-├── install.ts # @clack/prompts-based TUI installer
-├── config-manager/ # JSONC parsing, multi-source config management
-│ └── *.ts
-├── doctor/ # Health check system
-│ ├── index.ts # Doctor command entry
-│ └── checks/ # 17+ individual check modules
-├── run/ # Session runner
-│ └── *.ts
-└── mcp-oauth/ # OAuth management commands
- └── *.ts
+### Usage
+
+```bash
+# Authenticate
+bunx oh-my-openagent mcp oauth login --server-url https://api.example.com
+
+# Authenticate with explicit client ID and scopes
+bunx oh-my-openagent mcp oauth login --server-url https://api.example.com --client-id my-client --scopes read write
+
+# Remove stored tokens
+bunx oh-my-openagent mcp oauth logout --server-url https://api.example.com
+
+# Show token status
+bunx oh-my-openagent mcp oauth status [server-name]
```
-### Adding New Doctor Checks
+### Options
-Create `src/cli/doctor/checks/my-check.ts`:
+| Option | Description |
+| --- | --- |
+| `--server-url ` | OAuth server URL (required by `login`, and required by `logout`) |
+| `--client-id ` | OAuth client ID (optional if server supports DCR) |
+| `--scopes ` | OAuth scopes as variadic values |
-```typescript
-import type { DoctorCheck } from "../types";
+---
-export const myCheck: DoctorCheck = {
- name: "my-check",
- category: "environment",
- check: async () => {
- // Check logic
- const isOk = await someValidation();
+## Exit Codes
- return {
- status: isOk ? "pass" : "fail",
- message: isOk ? "Everything looks good" : "Something is wrong",
- };
- },
-};
-```
+- `0` on success
+- `1` on failure
-Register in `src/cli/doctor/checks/index.ts`:
-
-```typescript
-export { myCheck } from "./my-check";
-```
+`run`, `install`, `doctor`, `get-local-version`, `refresh-model-capabilities`, and `mcp oauth` subcommands return explicit numeric exit codes.
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index f33084acd..9321b156e 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -1,1034 +1,278 @@
# Configuration Reference
-Complete reference for Oh My OpenCode plugin configuration. During the rename transition, the runtime recognizes both `oh-my-openagent.json[c]` and legacy `oh-my-opencode.json[c]` files.
+This reference documents the current runtime behavior for Oh My OpenAgent plugin config loading and validation.
----
+During the rename transition, both basenames are accepted:
-## Table of Contents
+- Preferred: `oh-my-openagent.jsonc` or `oh-my-openagent.json`
+- Legacy: `oh-my-opencode.jsonc` or `oh-my-opencode.json`
-- [Getting Started](#getting-started)
- - [File Locations](#file-locations)
- - [Quick Start Example](#quick-start-example)
-- [Core Concepts](#core-concepts)
- - [Agents](#agents)
- - [Categories](#categories)
- - [Model Resolution](#model-resolution)
-- [Task System](#task-system)
- - [Background Tasks](#background-tasks)
- - [Sisyphus Agent](#sisyphus-agent)
- - [Sisyphus Tasks](#sisyphus-tasks)
-- [Features](#features)
- - [Skills](#skills)
- - [Hooks](#hooks)
- - [Commands](#commands)
- - [Browser Automation](#browser-automation)
- - [Tmux Integration](#tmux-integration)
- - [Git Master](#git-master)
- - [Comment Checker](#comment-checker)
- - [Notification](#notification)
- - [MCPs](#mcps)
- - [LSP](#lsp)
-- [Advanced](#advanced)
- - [Runtime Fallback](#runtime-fallback)
- - [Model Capabilities](#model-capabilities)
- - [Hashline Edit](#hashline-edit)
- - [Experimental](#experimental)
-- [Reference](#reference)
- - [Environment Variables](#environment-variables)
- - [Provider-Specific](#provider-specific)
+## Format and Naming Rules
----
+- Config format: JSONC (`//` comments, `/* */` comments, trailing commas)
+- Key style: `snake_case`
+- Validation: Zod v4 schema validation
+- Auto-migration: legacy keys and values are migrated by `migrateConfigFile()`
-## Getting Started
-
-### File Locations
-
-User config loads first. Project configs are discovered by walking from the working directory up to `$HOME`; closer configs win. If the working directory is outside `$HOME`, only that directory is checked.
-
-1. Walked configs: `.opencode/oh-my-openagent.json[c]` or legacy `.opencode/oh-my-opencode.json[c]`
-2. User config (`.jsonc` preferred over `.json`):
-
-| Platform | Path candidates |
-| ----------- | --------------- |
-| macOS/Linux | `~/.config/opencode/oh-my-openagent.json[c]`, `~/.config/opencode/oh-my-opencode.json[c]` |
-| Windows | `%APPDATA%\opencode\oh-my-openagent.json[c]`, `%APPDATA%\opencode\oh-my-opencode.json[c]` |
-
-**Security note:** `mcp_env_allowlist` is user-only. Walked configs cannot extend it.
-
-**Rename compatibility:** The published package and CLI binary remain `oh-my-opencode`. OpenCode plugin registration prefers `oh-my-openagent`, while legacy `oh-my-opencode` entries and config basenames still load during the transition. Config detection checks `oh-my-opencode` before `oh-my-openagent`, so if both plugin config basenames exist in the same directory, the legacy `oh-my-opencode.*` file currently wins.
-JSONC supports `// line comments`, `/* block comments */`, and trailing commas.
-
-Enable schema autocomplete:
-
-```json
-{
- "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json"
-}
-```
-
-Run `bunx oh-my-opencode install` for guided setup. Run `opencode models` to list available models.
-
-### Quick Start Example
-
-Here's a practical starting configuration:
+Schema autocomplete:
```jsonc
{
- "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
+ "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-openagent.schema.json",
+}
+```
+## File Discovery and Merge Order
+
+Load order (`src/plugin-config.ts`):
+
+1. User config in OpenCode config dir (`~/.config/opencode` on macOS/Linux, `%APPDATA%\\opencode` on Windows)
+2. Walked project configs from the current directory up to `$HOME` (closer directory wins)
+
+When current directory is outside `$HOME`, walking is pinned to that directory.
+
+### Merge semantics
+
+- Deep merge: `agents`, `categories`, `team_mode`, `claude_code`
+- Set union (dedup arrays):
+ - `agent_definitions`
+ - `disabled_agents`
+ - `disabled_mcps`
+ - `disabled_hooks`
+ - `disabled_commands`
+ - `disabled_skills`
+ - `disabled_tools`
+ - `mcp_env_allowlist` (during merge phase)
+- Override replace: all other keys
+
+Security rule: final `mcp_env_allowlist` is forced to user-config only. Walked/project configs cannot extend it.
+
+## Migration Behavior
+
+- Legacy basename can be migrated to canonical basename automatically.
+- Config migrations are idempotent and tracked using migration sidecar state (plus legacy `_migrations` compatibility handling).
+- When content changes, migration writes timestamped backups like `*.bak.`.
+
+## Top-level Key Reference
+
+Types/defaults below are from `assets/oh-my-openagent.schema.json`.
+
+| Key | Type | Default |
+| --- | --- | --- |
+| `$schema` | `string` | none |
+| `_migrations` | `string[]` | none |
+| `agent_definitions` | `string[]` | none |
+| `agents` | `object` | none |
+| `auto_update` | `boolean` | none |
+| `babysitting` | `object` | none |
+| `background_task` | `object` | none |
+| `browser_automation_engine` | `object` | none |
+| `categories` | `object` | none |
+| `claude_code` | `object` | none |
+| `comment_checker` | `object` | none |
+| `default_run_agent` | `string` | none |
+| `disabled_agents` | `string[]` | none |
+| `disabled_commands` | `string[]` | none |
+| `disabled_hooks` | `string[]` | none |
+| `disabled_mcps` | `string[]` | none |
+| `disabled_skills` | `string[]` | none |
+| `disabled_tools` | `string[]` | none |
+| `experimental` | `object` | none |
+| `git_master` | `object` | `{ "commit_footer": true, "include_co_authored_by": true, "git_env_prefix": "GIT_MASTER=1" }` |
+| `hashline_edit` | `boolean` | none |
+| `keyword_detector` | `object` | none |
+| `mcp_env_allowlist` | `string[]` | none |
+| `model_capabilities` | `object` | none |
+| `model_fallback` | `boolean` | none |
+| `new_task_system_enabled` | `boolean` | none |
+| `notification` | `object` | none |
+| `openclaw` | `object` | none |
+| `ralph_loop` | `object` | none |
+| `runtime_fallback` | `boolean \| object` | none |
+| `sisyphus` | `object` | none |
+| `sisyphus_agent` | `object` | none |
+| `skills` | `string[] \| object` | none |
+| `start_work` | `object` | none |
+| `team_mode` | `object` | none |
+| `tmux` | `object` | none |
+| `websearch` | `object` | none |
+
+## High-use Sections
+
+### `team_mode` (all fields)
+
+```jsonc
+{
+ "team_mode": {
+ "enabled": false,
+ "tmux_visualization": false,
+ "max_parallel_members": 4,
+ "max_members": 8,
+ "max_messages_per_run": 10000,
+ "max_wall_clock_minutes": 120,
+ "max_member_turns": 500,
+ "base_dir": "/custom/path", // optional
+ "message_payload_max_bytes": 32768,
+ "recipient_unread_max_bytes": 262144,
+ "mailbox_poll_interval_ms": 3000,
+ },
+}
+```
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `false` | Master switch |
+| `tmux_visualization` | `boolean` | `false` | Visual tmux mode |
+| `max_parallel_members` | `integer` | `4` | Range `1..8` |
+| `max_members` | `integer` | `8` | Range `1..8` |
+| `max_messages_per_run` | `integer` | `10000` | Minimum `1` |
+| `max_wall_clock_minutes` | `integer` | `120` | Minimum `1` |
+| `max_member_turns` | `integer` | `500` | Minimum `1` |
+| `base_dir` | `string` | none | Optional override path |
+| `message_payload_max_bytes` | `integer` | `32768` | Minimum `1024` |
+| `recipient_unread_max_bytes` | `integer` | `262144` | Minimum `1024` |
+| `mailbox_poll_interval_ms` | `integer` | `3000` | Minimum `500` |
+
+### `tmux`
+
+| Field | Type | Default |
+| --- | --- | --- |
+| `enabled` | `boolean` | `false` |
+| `layout` | `string` | `"main-vertical"` |
+| `main_pane_size` | `number` | `60` |
+| `main_pane_min_width` | `number` | `120` |
+| `agent_pane_min_width` | `number` | `40` |
+| `isolation` | `string` | `"inline"` |
+
+### `background_task`
+
+| Field | Type | Default |
+| --- | --- | --- |
+| `defaultConcurrency` | `number` | none |
+| `providerConcurrency` | `object` | none |
+| `modelConcurrency` | `object` | none |
+| `maxDepth` | `integer` | none |
+| `staleTimeoutMs` | `number` | none |
+| `messageStalenessTimeoutMs` | `number` | none |
+| `taskTtlMs` | `number` | none |
+| `sessionGoneTimeoutMs` | `number` | none |
+| `syncPollTimeoutMs` | `number` | none |
+| `maxToolCalls` | `integer` | none |
+| `circuitBreaker` | `object` | none |
+
+### `experimental`
+
+| Field | Type | Default |
+| --- | --- | --- |
+| `aggressive_truncation` | `boolean` | none |
+| `auto_resume` | `boolean` | none |
+| `preemptive_compaction` | `boolean` | none |
+| `truncate_all_tool_outputs` | `boolean` | none |
+| `dynamic_context_pruning` | `object` | none |
+| `task_system` | `boolean` | none |
+| `plugin_load_timeout_ms` | `number` | none |
+| `safe_hook_creation` | `boolean` | none |
+| `disable_omo_env` | `boolean` | none |
+| `hashline_edit` | `boolean` | none |
+| `model_fallback_title` | `boolean` | none |
+| `max_tools` | `integer` | none |
+
+### `openclaw`
+
+| Field | Type | Default |
+| --- | --- | --- |
+| `enabled` | `boolean` | `false` |
+| `gateways` | `object` | `{}` |
+| `hooks` | `object` | `{}` |
+| `replyListener` | `object` | none |
+
+### `sisyphus_agent`
+
+| Field | Type | Default |
+| --- | --- | --- |
+| `disabled` | `boolean` | none |
+| `default_builder_enabled` | `boolean` | none |
+| `planner_enabled` | `boolean` | none |
+| `replace_plan` | `boolean` | none |
+| `tdd` | `boolean` | `true` |
+
+### `git_master`
+
+| Field | Type | Default |
+| --- | --- | --- |
+| `commit_footer` | `boolean \| string` | `true` |
+| `include_co_authored_by` | `boolean` | `true` |
+| `git_env_prefix` | `string` | `"GIT_MASTER=1"` |
+
+### `model_capabilities`
+
+| Field | Type | Default |
+| --- | --- | --- |
+| `enabled` | `boolean` | none |
+| `auto_refresh_on_start` | `boolean` | none |
+| `refresh_timeout_ms` | `integer` | none |
+| `source_url` | `string` | none |
+
+### `browser_automation_engine`
+
+| Field | Type | Default |
+| --- | --- | --- |
+| `provider` | `string` | `"playwright"` |
+
+### `notification`, `comment_checker`, `keyword_detector`, `websearch`, `ralph_loop`, `babysitting`, `start_work`
+
+| Key | Field | Type | Default |
+| --- | --- | --- | --- |
+| `notification` | `force_enable` | `boolean` | none |
+| `comment_checker` | `custom_prompt` | `string` | none |
+| `keyword_detector` | `disabled_keywords` | `string[]` | none |
+| `websearch` | `provider` | `string` | none |
+| `ralph_loop` | `enabled` | `boolean` | `false` |
+| `ralph_loop` | `default_max_iterations` | `number` | `100` |
+| `ralph_loop` | `state_dir` | `string` | none |
+| `ralph_loop` | `default_strategy` | `string` | `"continue"` |
+| `babysitting` | `timeout_ms` | `number` | `120000` |
+| `start_work` | `auto_commit` | `boolean` | `true` |
+
+## Agents, Categories, Skills
+
+- `agents`: per-agent overrides. Built-ins include `sisyphus`, `hephaestus`, `prometheus`, `oracle`, `librarian`, `explore`, `atlas`, `metis`, `momus`, `multimodal-looker`, `sisyphus-junior`.
+- `categories`: category-level model and prompt routing overrides.
+- `skills`: either array form or object form.
+- `disabled_agents`, `disabled_skills`, `disabled_hooks`, `disabled_tools`, `disabled_commands`, `disabled_mcps`: string arrays.
+
+## Runtime and Model Fallback
+
+- `model_fallback`: global switch for proactive model fallback behavior.
+- `runtime_fallback`: boolean or object config for reactive fallback behavior.
+- Provider/model fallback chains are defined in code (`src/shared/model-requirements.ts`).
+
+## Verified JSONC Example
+
+```jsonc
+{
+ "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-openagent.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-7", "variant": "max" },
- },
-
- // Research agents: cheap fast models are fine
- "librarian": { "model": "google/gemini-3-flash" },
+ "sisyphus": { "model": "anthropic/claude-opus-4-7" },
"explore": { "model": "github-copilot/grok-code-fast-1" },
-
- // Architecture consultation: GPT-5.5 or Claude Opus
- "oracle": { "model": "openai/gpt-5.5", "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": "anthropic/claude-sonnet-4-6" },
-
- // unspecified-high - complex work
- "unspecified-high": { "model": "anthropic/claude-opus-4-7", "variant": "max" },
-
- // writing - docs/prose
- "writing": { "model": "google/gemini-3-flash" },
-
- // visual-engineering - Gemini dominates visual tasks
- "visual-engineering": {
- "model": "google/gemini-3.1-pro",
- "variant": "high",
- },
-
- // Custom category for git operations
- "git": {
- "model": "opencode/gpt-5-nano",
- "description": "All git operations",
- "prompt_append": "Focus on atomic commits, clear messages, and safe operations.",
- },
+ "deep": { "model": "openai/gpt-5.5" },
},
-
- // 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-7": 2,
- "opencode/gpt-5-nano": 20,
- },
+ "disabled_hooks": ["startup-toast"],
+ "team_mode": {
+ "enabled": true,
+ "max_parallel_members": 4,
+ "max_members": 8,
+ "max_messages_per_run": 10000,
+ "max_wall_clock_minutes": 120,
+ "max_member_turns": 500,
+ "message_payload_max_bytes": 32768,
+ "recipient_unread_max_bytes": 262144,
+ "mailbox_poll_interval_ms": 3000,
+ "tmux_visualization": false,
},
-
- "experimental": { "aggressive_truncation": true, "task_system": true },
"tmux": { "enabled": false },
}
```
-
----
-
-## Core Concepts
-
-### Agents
-
-Override built-in agent settings. Available agents: `sisyphus`, `hephaestus`, `prometheus`, `oracle`, `librarian`, `explore`, `multimodal-looker`, `metis`, `momus`, `atlas`, `sisyphus-junior`.
-
-```json
-{
- "agents": {
- "explore": { "model": "anthropic/claude-haiku-4-5", "temperature": 0.5 },
- "multimodal-looker": { "disable": true }
- }
-}
-```
-
-Disable agents entirely: `{ "disabled_agents": ["oracle", "multimodal-looker"] }`
-
-Core agents receive an injected runtime `order` field for deterministic Tab cycling in the UI: Sisyphus = 1, Hephaestus = 2, Prometheus = 3, Atlas = 4. This is not a user-configurable config key.
-
-#### Agent Options
-
-| Option | Type | Description |
-| ----------------- | -------------- | --------------------------------------------------------------- |
-| `model` | string | Model override (`provider/model`) |
-| `fallback_models` | string\|array | Fallback models on API errors. Supports strings or mixed arrays of strings and object entries with per-model settings |
-| `temperature` | number | Sampling temperature |
-| `top_p` | number | Top-p sampling |
-| `prompt` | string | Replace system prompt. Supports `file://` URIs |
-| `prompt_append` | string | Append to system prompt. Supports `file://` URIs |
-| `tools` | array | Allowed tools list |
-| `disable` | boolean | Disable this agent |
-| `mode` | string | Agent mode |
-| `color` | string | UI color |
-| `permission` | object | Per-tool permissions (see below) |
-| `category` | string | Inherit model from category |
-| `variant` | string | Model variant: `max`, `high`, `medium`, `low`, `xhigh`. Normalized to supported values |
-| `maxTokens` | number | Max response tokens |
-| `thinking` | object | Anthropic extended thinking |
-| `reasoningEffort` | string | OpenAI reasoning: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`. Normalized to supported values |
-| `textVerbosity` | string | Text verbosity: `low`, `medium`, `high` |
-| `providerOptions` | object | Provider-specific options |
-
-#### Anthropic Extended Thinking
-
-```json
-{
- "agents": {
- "oracle": { "thinking": { "type": "enabled", "budgetTokens": 200000 } }
- }
-}
-```
-
-#### Agent Permissions
-
-Control what tools an agent can use:
-
-```json
-{
- "agents": {
- "explore": {
- "permission": {
- "edit": "deny",
- "bash": "ask",
- "webfetch": "allow"
- }
- }
- }
-}
-```
-
-| Permission | Values |
-| -------------------- | --------------------------------------------------------------------------- |
-| `edit` | `ask` / `allow` / `deny` |
-| `bash` | `ask` / `allow` / `deny` or per-command: `{ "git": "allow", "rm": "deny" }` |
-| `webfetch` | `ask` / `allow` / `deny` |
-| `doom_loop` | `ask` / `allow` / `deny` |
-| `external_directory` | `ask` / `allow` / `deny` |
-
-
-#### Fallback Models with Per-Model Settings
-
-`fallback_models` accepts either a single model string or an array. Array entries can be plain strings or objects with individual model settings:
-
-```jsonc
-{
- "agents": {
- "sisyphus": {
- "model": "anthropic/claude-opus-4-7",
- "fallback_models": [
- // Simple string fallback
- "openai/gpt-5.5",
- // Object with per-model settings
- {
- "model": "google/gemini-3.1-pro",
- "variant": "high",
- "temperature": 0.2
- },
- {
- "model": "anthropic/claude-sonnet-4-6",
- "thinking": { "type": "enabled", "budgetTokens": 64000 }
- }
- ]
- }
- }
-}
-```
-
-Object entries support: `model`, `variant`, `reasoningEffort`, `temperature`, `top_p`, `maxTokens`, `thinking`.
-
-#### File URIs for Prompts
-
-Both `prompt` and `prompt_append` support loading content from files via `file://` URIs. Category-level `prompt_append` supports the same URI forms.
-
-```jsonc
-{
- "agents": {
- "sisyphus": {
- "prompt_append": "file:///absolute/path/to/prompt.txt"
- },
- "oracle": {
- "prompt": "file://./relative/to/project/prompt.md"
- },
- "explore": {
- "prompt_append": "file://~/home/dir/prompt.txt"
- }
- },
- "categories": {
- "custom": {
- "model": "anthropic/claude-sonnet-4-6",
- "prompt_append": "file://./category-context.md"
- }
- }
-}
-```
-
-Paths can be absolute (`file:///abs/path`), relative to project root (`file://./rel/path`), or home-relative (`file://~/home/path`). If a file URI cannot be decoded, resolved, or read, OmO inserts a warning placeholder into the prompt instead of failing hard.
-
-### Categories
-
-Domain-specific model delegation used by the `task()` tool. When Sisyphus delegates work, it picks a category, not a model name.
-
-#### Built-in Categories
-
-| Category | Default Model | Description |
-| -------------------- | ------------------------------- | ---------------------------------------------- |
-| `visual-engineering` | `google/gemini-3.1-pro` (high) | Frontend, UI/UX, design, animation |
-| `ultrabrain` | `openai/gpt-5.5` (xhigh) | Deep logical reasoning, complex architecture |
-| `deep` | `openai/gpt-5.5` (medium) | Autonomous problem-solving, thorough research |
-| `artistry` | `google/gemini-3.1-pro` (high) | Creative/unconventional approaches |
-| `quick` | `openai/gpt-5.4-mini` | Trivial tasks, typo fixes, single-file changes |
-| `unspecified-low` | `anthropic/claude-sonnet-4-6` | General tasks, low effort |
-| `unspecified-high` | `anthropic/claude-opus-4-7` (max) | General tasks, high effort |
-| `writing` | `google/gemini-3-flash` | Documentation, prose, technical writing |
-
-> **Note**: Built-in defaults only apply if the category is present in your config. Otherwise the system default model is used.
-
-#### Category Options
-
-| Option | Type | Default | Description |
-| ------------------- | ------------- | ------- | ------------------------------------------------------------------- |
-| `model` | string | - | Model override |
-| `fallback_models` | string\|array | - | Fallback models on API errors. Supports strings or mixed arrays of strings and object entries with per-model settings |
-| `temperature` | number | - | Sampling temperature |
-| `top_p` | number | - | Top-p sampling |
-| `maxTokens` | number | - | Max response tokens |
-| `thinking` | object | - | Anthropic extended thinking |
-| `reasoningEffort` | string | - | OpenAI reasoning effort. Unsupported values are normalized |
-| `textVerbosity` | string | - | Text verbosity |
-| `tools` | array | - | Allowed tools |
-| `prompt_append` | string | - | Append to system prompt |
-| `variant` | string | - | Model variant. Unsupported values are normalized |
-| `description` | string | - | Shown in `task()` tool prompt |
-| `is_unstable_agent` | boolean | `false` | Force background mode + monitoring. Auto-enabled for Gemini models. |
-
-Disable categories: `{ "disabled_categories": ["ultrabrain"] }`
-
-### Model Resolution
-
-Runtime priority:
-
-1. **UI-selected model** - model chosen in the OpenCode UI, for primary agents
-2. **User override** - model set in config → used exactly as-is. Even on cold cache, explicit user configuration takes precedence over hardcoded fallback chains
-3. **Category default** - model inherited from the assigned category config
-4. **User `fallback_models`** - user-configured fallback list is tried before built-in fallback chains
-5. **Provider fallback chain** - built-in provider/model chain from OmO source
-6. **System default** - OpenCode's configured default model
-
-#### Model Settings Compatibility
-
-Model settings are compatibility-normalized against model capabilities instead of failing hard.
-
-Normalized fields:
-
-- `variant` - downgraded to the closest supported value
-- `reasoningEffort` - downgraded to the closest supported value, or removed if unsupported
-- `temperature` - removed if unsupported by the model metadata
-- `top_p` - removed if unsupported by the model metadata
-- `maxTokens` - capped to the model's reported max output limit
-- `thinking` - removed if the target model does not support thinking
-
-Examples:
-- Claude models do not support `reasoningEffort` - it is removed automatically
-- GPT-4.1 does not support reasoning - `reasoningEffort` is removed
-- o-series models support `none` through `high` - `xhigh` is downgraded to `high`
-- GPT-5 supports `none`, `minimal`, `low`, `medium`, `high`, `xhigh` - all pass through
-
-Capability data comes from provider runtime metadata first. OmO also ships bundled models.dev-backed capability data, supports a refreshable local models.dev cache, and falls back to heuristic family detection plus alias rules when exact metadata is unavailable. `bunx oh-my-opencode doctor` surfaces capability diagnostics and warns when a configured model relies on compatibility fallback.
-
-
-#### Agent Provider Chains
-
-| Agent | Default Model | Provider Priority |
-| --------------------- | ------------------- | ---------------------------------------------------------------------------- |
-| **Sisyphus** | `claude-opus-4-7` | `anthropic\|github-copilot\|opencode/claude-opus-4-7 (max)` → `opencode-go/kimi-k2.6` → `kimi-for-coding/k2p5` → `opencode\|moonshotai\|moonshotai-cn\|firmware\|ollama-cloud\|aihubmix/kimi-k2.5` → `openai\|github-copilot\|opencode/gpt-5.5 (medium)` → `zai-coding-plan\|opencode/glm-5` → `opencode/big-pickle` |
-| **Hephaestus** | `gpt-5.5` | `gpt-5.5 (medium)` |
-| **oracle** | `gpt-5.5` | `openai\|github-copilot\|opencode/gpt-5.5 (high)` → `google\|github-copilot\|opencode/gemini-3.1-pro (high)` → `anthropic\|github-copilot\|opencode/claude-opus-4-7 (max)` → `opencode-go/glm-5.1` |
-| **librarian** | `gpt-5.4-mini-fast` | `openai/gpt-5.4-mini-fast` → `opencode-go/qwen3.5-plus` → `vercel/minimax-m2.7-highspeed` → `opencode-go\|vercel/minimax-m2.7` → `anthropic\|opencode\|vercel/claude-haiku-4-5` → `openai\|opencode\|vercel/gpt-5.4-nano` |
-| **explore** | `gpt-5.4-mini-fast` | `openai/gpt-5.4-mini-fast` → `opencode-go/qwen3.5-plus` → `vercel/minimax-m2.7-highspeed` → `opencode-go\|vercel/minimax-m2.7` → `anthropic\|opencode\|vercel/claude-haiku-4-5` → `openai\|opencode\|vercel/gpt-5.4-nano` |
-| **multimodal-looker** | `gpt-5.5` | `openai\|opencode/gpt-5.5 (medium)` → `opencode-go/kimi-k2.6` → `zai-coding-plan/glm-4.6v` → `openai\|github-copilot\|opencode/gpt-5-nano` |
-| **Prometheus** | `claude-opus-4-7` | `anthropic\|github-copilot\|opencode/claude-opus-4-7 (max)` → `openai\|github-copilot\|opencode/gpt-5.5 (high)` → `opencode-go/glm-5.1` → `google\|github-copilot\|opencode/gemini-3.1-pro` |
-| **Metis** | `claude-sonnet-4-6` | `anthropic\|github-copilot\|opencode/claude-sonnet-4-6` → `anthropic\|github-copilot\|opencode/claude-opus-4-7 (max)` → `openai\|github-copilot\|opencode/gpt-5.5 (high)` → `opencode-go/glm-5.1` → `kimi-for-coding/k2p5` |
-| **Momus** | `gpt-5.5` | `openai\|github-copilot\|opencode/gpt-5.5 (xhigh)` → `anthropic\|github-copilot\|opencode/claude-opus-4-7 (max)` → `google\|github-copilot\|opencode/gemini-3.1-pro (high)` → `opencode-go/glm-5.1` |
-| **Atlas** | `claude-sonnet-4-6` | `anthropic\|github-copilot\|opencode/claude-sonnet-4-6` → `opencode-go/kimi-k2.6` → `openai\|github-copilot\|opencode/gpt-5.5 (medium)` → `opencode-go/minimax-m2.7` |
-
-#### Category Provider Chains
-
-| Category | Default Model | Provider Priority |
-| ---------------------- | ------------------- | -------------------------------------------------------------- |
-| **visual-engineering** | `gemini-3.1-pro` | `google\|github-copilot\|opencode/gemini-3.1-pro (high)` → `zai-coding-plan\|opencode/glm-5` → `anthropic\|github-copilot\|opencode/claude-opus-4-7 (max)` → `opencode-go/glm-5.1` → `kimi-for-coding/k2p5` |
-| **ultrabrain** | `gpt-5.5` | `openai\|opencode/gpt-5.5 (xhigh)` → `google\|github-copilot\|opencode/gemini-3.1-pro (high)` → `anthropic\|github-copilot\|opencode/claude-opus-4-7 (max)` → `opencode-go/glm-5.1` |
-| **deep** | `gpt-5.5` | `openai\|github-copilot\|venice\|opencode/gpt-5.5 (medium)` → `anthropic\|github-copilot\|opencode/claude-opus-4-7 (max)` → `google\|github-copilot\|opencode/gemini-3.1-pro (high)` |
-| **artistry** | `gemini-3.1-pro` | `google\|github-copilot\|opencode/gemini-3.1-pro (high)` → `anthropic\|github-copilot\|opencode/claude-opus-4-7 (max)` → `openai\|github-copilot\|opencode/gpt-5.5` |
-| **quick** | `gpt-5.4-mini` | `openai\|github-copilot\|opencode/gpt-5.4-mini` → `anthropic\|github-copilot\|opencode/claude-haiku-4-5` → `google\|github-copilot\|opencode/gemini-3-flash` → `opencode-go/minimax-m2.7` → `opencode/gpt-5-nano` |
-| **unspecified-low** | `claude-sonnet-4-6` | `anthropic\|github-copilot\|opencode/claude-sonnet-4-6` → `openai\|opencode/gpt-5.3-codex (medium)` → `opencode-go/kimi-k2.6` → `google\|github-copilot\|opencode/gemini-3-flash` → `opencode-go/minimax-m2.7` |
-| **unspecified-high** | `claude-opus-4-7` | `anthropic\|github-copilot\|opencode/claude-opus-4-7 (max)` → `openai\|github-copilot\|opencode/gpt-5.5 (high)` → `zai-coding-plan\|opencode/glm-5` → `kimi-for-coding/k2p5` → `opencode-go/glm-5.1` → `opencode/kimi-k2.5` → `opencode\|moonshotai\|moonshotai-cn\|firmware\|ollama-cloud\|aihubmix/kimi-k2.5` |
-| **writing** | `gemini-3-flash` | `google\|github-copilot\|opencode/gemini-3-flash` → `opencode-go/kimi-k2.6` → `anthropic\|github-copilot\|opencode/claude-sonnet-4-6` → `opencode-go/minimax-m2.7` |
-
-Run `bunx oh-my-opencode doctor --verbose` to see effective model resolution for your config.
-
----
-
-## Task System
-
-### Background Tasks
-
-Control parallel agent execution and concurrency limits.
-
-```json
-{
- "background_task": {
- "defaultConcurrency": 5,
- "staleTimeoutMs": 180000,
- "providerConcurrency": { "anthropic": 3, "openai": 5, "google": 10 },
- "modelConcurrency": { "anthropic/claude-opus-4-7": 2 }
- }
-}
-```
-
-| Option | Default | Description |
-| --------------------- | -------- | --------------------------------------------------------------------- |
-| `defaultConcurrency` | - | Max concurrent tasks (all providers) |
-| `staleTimeoutMs` | `180000` | Interrupt tasks with no activity (min: 60000) |
-| `providerConcurrency` | - | Per-provider limits (key = provider name) |
-| `modelConcurrency` | - | Per-model limits (key = `provider/model`). Overrides provider limits. |
-
-Priority: `modelConcurrency` > `providerConcurrency` > `defaultConcurrency`
-
-### Sisyphus Agent
-
-Configure the main orchestration system.
-
-```json
-{
- "sisyphus_agent": {
- "disabled": false,
- "default_builder_enabled": false,
- "planner_enabled": true,
- "replace_plan": true
- }
-}
-```
-
-| Option | Default | Description |
-| ------------------------- | ------- | --------------------------------------------------------------- |
-| `disabled` | `false` | Disable all Sisyphus orchestration, restore original build/plan |
-| `default_builder_enabled` | `false` | Enable OpenCode-Builder agent (off by default) |
-| `planner_enabled` | `true` | Enable Prometheus (Planner) agent |
-| `replace_plan` | `true` | Demote default plan agent to subagent mode |
-
-Sisyphus agents can also be customized under `agents` using their names: `Sisyphus`, `OpenCode-Builder`, `Prometheus (Planner)`, `Metis (Plan Consultant)`.
-
-### Sisyphus Tasks
-
-File-based task persistence with dependency tracking, used for cross-session task management. The task system is controlled by `experimental.task_system` (defaults to `true` since v3.14). When enabled, `TodoWrite`/`TodoRead` are intercepted and replaced with the Task tools (`task_create`, `task_get`, `task_list`, `task_update`).
-
-The `sisyphus.tasks` section configures **storage options** only:
-
-```json
-{
- "sisyphus": {
- "tasks": {
- "storage_path": ".sisyphus/tasks",
- "claude_code_compat": false
- }
- }
-}
-```
-
-| Option | Default | Description |
-| -------------------- | ----------------- | ------------------------------------------ |
-| `storage_path` | `.sisyphus/tasks` | Storage path (relative to project root) |
-| `task_list_id` | - | Force task list ID (alternative to env `ULTRAWORK_TASK_LIST_ID`) |
-| `claude_code_compat` | `false` | Enable Claude Code path compatibility mode |
-
-To disable the task system entirely, set `experimental.task_system` to `false`:
-
-```json
-{
- "experimental": { "task_system": false }
-}
-```
-
----
-
-## Features
-
-### Skills
-
-Skills bring domain-specific expertise and embedded MCPs.
-
-Built-in skills: `playwright`, `playwright-cli`, `agent-browser`, `dev-browser`, `git-master`, `frontend-ui-ux`
-
-Disable built-in skills: `{ "disabled_skills": ["playwright"] }`
-
-#### Skills Configuration
-
-```json
-{
- "skills": {
- "sources": [
- { "path": "./my-skills", "recursive": true },
- "https://example.com/skill.yaml"
- ],
- "enable": ["my-skill"],
- "disable": ["other-skill"],
- "my-skill": {
- "description": "What it does",
- "template": "Custom prompt template",
- "from": "source-file.ts",
- "model": "custom/model",
- "agent": "custom-agent",
- "subtask": true,
- "argument-hint": "usage hint",
- "license": "MIT",
- "compatibility": ">= 3.0.0",
- "metadata": { "author": "Your Name" },
- "allowed-tools": ["read", "bash"]
- }
- }
-}
-```
-
-| `sources` option | Default | Description |
-| ---------------- | ------- | ------------------------------- |
-| `path` | - | Local path or remote URL |
-| `recursive` | `false` | Recurse into subdirectories |
-| `glob` | - | Glob pattern for file selection |
-
-### Hooks
-
-Disable built-in hooks via `disabled_hooks`:
-
-```json
-{ "disabled_hooks": ["comment-checker"] }
-```
-
-Available hooks: `todo-continuation-enforcer`, `context-window-monitor`, `session-recovery`, `session-notification`, `comment-checker`, `grep-output-truncator`, `tool-output-truncator`, `directory-agents-injector`, `directory-readme-injector`, `empty-task-response-detector`, `think-mode`, `anthropic-context-window-limit-recovery`, `rules-injector`, `background-notification`, `auto-update-checker`, `startup-toast`, `keyword-detector`, `agent-usage-reminder`, `non-interactive-env`, `interactive-bash-session`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`, `ralph-loop`, `preemptive-compaction`, `auto-slash-command`, `sisyphus-junior-notepad`, `no-sisyphus-gpt`, `start-work`, `runtime-fallback`
-
-**Notes:**
-
-- `directory-agents-injector` - auto-disabled on OpenCode 1.1.37+ (native AGENTS.md support)
-- `no-sisyphus-gpt` - **do not disable**. It blocks incompatible GPT models for Sisyphus while allowing the dedicated GPT-5.4 and GPT-5.5 prompt paths.
-- `startup-toast` is a sub-feature of `auto-update-checker`. Disable just the toast by adding `startup-toast` to `disabled_hooks`.
-- `session-recovery` - automatically recovers from recoverable session errors (missing tool results, unavailable tools, thinking block violations). Shows toast notifications during recovery. Enable `experimental.auto_resume` for automatic retry after recovery.
-
-### Commands
-
-Disable built-in commands via `disabled_commands`:
-
-```json
-{ "disabled_commands": ["init-deep", "start-work"] }
-```
-
-Available commands: `init-deep`, `ralph-loop`, `ulw-loop`, `cancel-ralph`, `refactor`, `start-work`, `stop-continuation`, `handoff`
-
-### Browser Automation
-
-| Provider | Interface | Installation |
-| ---------------------- | --------- | --------------------------------------------------- |
-| `playwright` (default) | MCP tools | Auto-installed via npx |
-| `agent-browser` | Bash CLI | `bun add -g agent-browser && agent-browser install` |
-
-Switch provider:
-
-```json
-{ "browser_automation_engine": { "provider": "agent-browser" } }
-```
-
-### Tmux Integration
-
-Run background subagents in separate tmux panes. Requires running inside tmux with `opencode --port `.
-
-```json
-{
- "tmux": {
- "enabled": true,
- "layout": "main-vertical",
- "main_pane_size": 60,
- "main_pane_min_width": 120,
- "agent_pane_min_width": 40
- }
-}
-```
-
-| Option | Default | Description |
-| ---------------------- | --------------- | ----------------------------------------------------------------------------------- |
-| `enabled` | `false` | Enable tmux pane spawning |
-| `layout` | `main-vertical` | `main-vertical` / `main-horizontal` / `tiled` / `even-horizontal` / `even-vertical` |
-| `main_pane_size` | `60` | Main pane % (20–80) |
-| `main_pane_min_width` | `120` | Min main pane columns |
-| `agent_pane_min_width` | `40` | Min agent pane columns |
-
-### Git Master
-
-Configure git commit behavior:
-
-```json
-{ "git_master": { "commit_footer": true, "include_co_authored_by": true } }
-```
-
-### Comment Checker
-
-Customize the comment quality checker:
-
-```json
-{
- "comment_checker": {
- "custom_prompt": "Your message. Use {{comments}} placeholder."
- }
-}
-```
-
-### Notification
-
-Force-enable session notifications:
-
-```json
-{ "notification": { "force_enable": true } }
-```
-
-`force_enable` (`false`) - force session-notification even if external notification plugins are detected.
-
-### MCPs
-
-Built-in MCPs (enabled by default): `websearch` (Exa AI), `context7` (library docs), `grep_app` (GitHub code search).
-
-```json
-{ "disabled_mcps": ["websearch", "context7", "grep_app"] }
-```
-
-### LSP
-
-Configure Language Server Protocol integration:
-
-```json
-{
- "lsp": {
- "typescript-language-server": {
- "command": ["typescript-language-server", "--stdio"],
- "extensions": [".ts", ".tsx"],
- "priority": 10,
- "env": { "NODE_OPTIONS": "--max-old-space-size=4096" },
- "initialization": {
- "preferences": { "includeInlayParameterNameHints": "all" }
- }
- },
- "pylsp": { "disabled": true }
- }
-}
-```
-
-| Option | Type | Description |
-| ---------------- | ------- | ------------------------------------ |
-| `command` | array | Command to start LSP server |
-| `extensions` | array | File extensions (e.g. `[".ts"]`) |
-| `priority` | number | Priority when multiple servers match |
-| `env` | object | Environment variables |
-| `initialization` | object | Init options passed to server |
-| `disabled` | boolean | Disable this server |
-
----
-
-## Advanced
-
-### Runtime Fallback
-
-Auto-switches to backup models on API errors.
-
-**Simple configuration** (enable/disable with defaults):
-
-```json
-{ "runtime_fallback": true }
-```
-
-```json
-{ "runtime_fallback": false }
-```
-
-**Advanced configuration** (full control):
-
-```json
-{
- "runtime_fallback": {
- "enabled": true,
- "retry_on_errors": [400, 429, 503, 529],
- "max_fallback_attempts": 3,
- "cooldown_seconds": 60,
- "timeout_seconds": 30,
- "notify_on_fallback": true
- }
-}
-```
-
-| Option | Default | Description |
-| ----------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `enabled` | `false` | Enable runtime fallback |
-| `retry_on_errors` | `[400,429,503,529]` | HTTP codes that trigger fallback. Also handles classified provider key errors. |
-| `max_fallback_attempts` | `3` | Max fallback attempts per session (1–20) |
-| `cooldown_seconds` | `60` | Seconds before retrying a failed model |
-| `timeout_seconds` | `30` | Seconds before forcing next fallback. **Set to `0` to disable timeout-based escalation and provider retry message detection.** |
-| `notify_on_fallback` | `true` | Toast notification on model switch |
-
-#### Speeding Up Fallback (Proxy APIs)
-
-If you are using a proxy API provider, they may return different error codes (e.g., `401`, `403`, `404`) for quota exhaustion or model unavailability. To make fallback trigger instantly without waiting for long timeouts:
-
-```jsonc
-{
- "runtime_fallback": {
- "enabled": true,
- // Add your proxy's specific error codes to retry_on_errors
- "retry_on_errors": [400, 401, 403, 404, 429, 500, 502, 503, 504],
- "max_fallback_attempts": 3,
- "cooldown_seconds": 15, // Shorter cooldown
- "timeout_seconds": 10 // Detect hung proxy requests faster
- }
-}
-```
-
-Define `fallback_models` per agent or category:
-
-```json
-{
- "agents": {
- "sisyphus": {
- "model": "anthropic/claude-opus-4-7",
- "fallback_models": [
- "openai/gpt-5.5",
- {
- "model": "google/gemini-3.1-pro",
- "variant": "high"
- }
- ]
- }
- }
-}
-```
-
-`fallback_models` also supports object-style entries so you can attach settings to a specific fallback model:
-
-```json
-{
- "agents": {
- "sisyphus": {
- "model": "anthropic/claude-opus-4-7",
- "fallback_models": [
- "openai/gpt-5.5",
- {
- "model": "anthropic/claude-sonnet-4-6",
- "variant": "high",
- "thinking": { "type": "enabled", "budgetTokens": 12000 }
- },
- {
- "model": "openai/gpt-5.3-codex",
- "reasoningEffort": "high",
- "temperature": 0.2,
- "top_p": 0.95,
- "maxTokens": 8192
- }
- ]
- }
- }
-}
-```
-
-Mixed arrays are allowed, so string entries and object entries can appear together in the same fallback chain.
-
-#### Object-style `fallback_models`
-
-Object entries use the following shape:
-
-| Field | Type | Description |
-| ----- | ---- | ----------- |
-| `model` | string | Fallback model ID. Provider prefix is optional when OmO can inherit the current/default provider. |
-| `variant` | string | Explicit variant override for this fallback entry. |
-| `reasoningEffort` | string | OpenAI reasoning effort override for this fallback entry. |
-| `temperature` | number | Temperature applied if this fallback model becomes active. |
-| `top_p` | number | Top-p applied if this fallback model becomes active. |
-| `maxTokens` | number | Max response tokens applied if this fallback model becomes active. |
-| `thinking` | object | Anthropic thinking config applied if this fallback model becomes active. |
-
-Per-model settings are **fallback-only**. They are promoted only when that specific fallback model is actually selected, so they do not override your primary model settings when the primary model resolves successfully.
-
-`thinking` uses the same shape as the normal agent/category option:
-
-| Field | Type | Description |
-| ----- | ---- | ----------- |
-| `type` | string | `enabled` or `disabled` |
-| `budgetTokens` | number | Optional Anthropic thinking budget |
-
-Object entries can also omit the provider prefix when OmO can infer it from the current/default provider. If you provide both inline variant syntax in `model` and an explicit `variant` field, the explicit `variant` field wins.
-
-#### Full examples
-
-**1. Simple string chain**
-
-Use strings when you only need an ordered fallback chain:
-
-```json
-{
- "agents": {
- "atlas": {
- "model": "anthropic/claude-sonnet-4-6",
- "fallback_models": [
- "anthropic/claude-haiku-4-5",
- "openai/gpt-5.5",
- "google/gemini-3.1-pro"
- ]
- }
- }
-}
-```
-
-**2. Same-provider shorthand**
-
-If the primary model already establishes the provider, fallback entries can omit the prefix:
-
-```json
-{
- "agents": {
- "atlas": {
- "model": "openai/gpt-5.5",
- "fallback_models": [
- "gpt-5.4-mini",
- {
- "model": "gpt-5.3-codex",
- "reasoningEffort": "medium",
- "maxTokens": 4096
- }
- ]
- }
- }
-}
-```
-
-In this example OmO treats `gpt-5.4-mini` and `gpt-5.3-codex` as OpenAI fallback entries because the current/default provider is already `openai`.
-
-**3. Mixed cross-provider chain**
-
-Mix string entries and object entries when only some fallback models need special settings:
-
-```json
-{
- "agents": {
- "sisyphus": {
- "model": "anthropic/claude-opus-4-7",
- "fallback_models": [
- "openai/gpt-5.5",
- {
- "model": "anthropic/claude-sonnet-4-6",
- "variant": "high",
- "thinking": { "type": "enabled", "budgetTokens": 12000 }
- },
- {
- "model": "google/gemini-3.1-pro",
- "variant": "high"
- }
- ]
- }
- }
-}
-```
-
-**4. Category-level fallback chain**
-
-`fallback_models` works the same way under `categories`:
-
-```json
-{
- "categories": {
- "deep": {
- "model": "openai/gpt-5.3-codex",
- "fallback_models": [
- {
- "model": "openai/gpt-5.5",
- "reasoningEffort": "xhigh",
- "maxTokens": 12000
- },
- {
- "model": "anthropic/claude-opus-4-7",
- "variant": "max",
- "temperature": 0.2
- },
- "google/gemini-3.1-pro(high)"
- ]
- }
- }
-}
-```
-
-**5. Full object entry with every supported field**
-
-This shows every supported object-style parameter in one place:
-
-```json
-{
- "agents": {
- "oracle": {
- "model": "openai/gpt-5.5",
- "fallback_models": [
- {
- "model": "openai/gpt-5.3-codex(low)",
- "variant": "xhigh",
- "reasoningEffort": "high",
- "temperature": 0.3,
- "top_p": 0.9,
- "maxTokens": 8192,
- "thinking": {
- "type": "disabled"
- }
- }
- ]
- }
- }
-}
-```
-
-In this example the explicit `"variant": "xhigh"` overrides the inline `(low)` suffix in `"model"`.
-
-This final example is a **complete shape reference**. In real configs, prefer provider-appropriate settings:
-
-- use `reasoningEffort` for OpenAI reasoning models
-- use `thinking` for Anthropic thinking-capable models
-- use `variant`, `temperature`, `top_p`, and `maxTokens` only when that fallback model supports them
-
-### Model Capabilities
-
-OmO can refresh a local models.dev capability snapshot on startup. This cache is controlled by `model_capabilities`.
-
-```jsonc
-{
- "model_capabilities": {
- "enabled": true,
- "auto_refresh_on_start": true,
- "refresh_timeout_ms": 5000,
- "source_url": "https://models.dev/api.json"
- }
-}
-```
-
-| Option | Default behavior | Description |
-| ------ | ---------------- | ----------- |
-| `enabled` | enabled unless explicitly set to `false` | Master switch for model capability refresh behavior |
-| `auto_refresh_on_start` | refresh on startup unless explicitly set to `false` | Refresh the local models.dev cache during startup checks |
-| `refresh_timeout_ms` | `5000` | Timeout for the startup refresh attempt |
-| `source_url` | `https://models.dev/api.json` | Override the models.dev source URL |
-
-Notes:
-
-- Startup refresh runs through the auto-update checker hook.
-- Manual refresh is available via `bunx oh-my-opencode refresh-model-capabilities`.
-- Provider runtime metadata still takes priority when OmO resolves capabilities for compatibility checks.
-
-### Hashline Edit
-
-Replaces the built-in `Edit` tool with a hash-anchored version using `LINE#ID` references to prevent stale-line edits. Disabled by default.
-
-```json
-{ "hashline_edit": true }
-```
-
-When enabled, two companion hooks are active: `hashline-read-enhancer` (annotates Read output) and `hashline-edit-diff-enhancer` (shows diffs). Opt-in by setting `hashline_edit: true`. Disable the companion hooks individually via `disabled_hooks` if needed.
-
-### Experimental
-
-```json
-{
- "experimental": {
- "truncate_all_tool_outputs": false,
- "aggressive_truncation": false,
- "auto_resume": false,
- "disable_omo_env": false,
- "task_system": true,
- "dynamic_context_pruning": {
- "enabled": false,
- "notification": "detailed",
- "turn_protection": { "enabled": true, "turns": 3 },
- "protected_tools": [
- "task",
- "todowrite",
- "todoread",
- "lsp_rename",
- "session_read",
- "session_write",
- "session_search"
- ],
- "strategies": {
- "deduplication": { "enabled": true },
- "supersede_writes": { "enabled": true, "aggressive": false },
- "purge_errors": { "enabled": true, "turns": 5 }
- }
- }
- }
-}
-```
-
-| Option | Default | Description |
-| ---------------------------------------- | ---------- | ------------------------------------------------------------------------------------ |
-| `truncate_all_tool_outputs` | `false` | Truncate all tool outputs (not just whitelisted) |
-| `aggressive_truncation` | `false` | Aggressively truncate when token limit exceeded |
-| `auto_resume` | `false` | Auto-resume after thinking block recovery |
-| `disable_omo_env` | `false` | Disable auto-injected `` block (date/time/locale). Improves cache hit rate. |
-| `task_system` | `false` | Enable Sisyphus task system |
-| `dynamic_context_pruning.enabled` | `false` | Auto-prune old tool outputs to manage context window |
-| `dynamic_context_pruning.notification` | `detailed` | Pruning notifications: `off` / `minimal` / `detailed` |
-| `turn_protection.turns` | `3` | Recent turns protected from pruning (1–10) |
-| `strategies.deduplication` | `true` | Remove duplicate tool calls |
-| `strategies.supersede_writes` | `true` | Prune write inputs when file later read |
-| `strategies.supersede_writes.aggressive` | `false` | Prune any write if ANY subsequent read exists |
-| `strategies.purge_errors.turns` | `5` | Turns before pruning errored tool inputs |
-
----
-
-## Reference
-
-### Environment Variables
-
-| Variable | Description |
-| --------------------- | ----------------------------------------------------------------- |
-| `OPENCODE_CONFIG_DIR` | Override OpenCode config directory (useful for profile isolation) |
-| `OMO_SEND_ANONYMOUS_TELEMETRY` | Set to `0`, `false`, or `no` to disable anonymous telemetry |
-| `OMO_DISABLE_POSTHOG` | Legacy telemetry opt-out flag. Set to `1` or `true` to disable PostHog |
-| `POSTHOG_API_KEY` | Optional override for the built-in PostHog project API key |
-| `POSTHOG_HOST` | Override the PostHog ingestion host. Defaults to `https://us.i.posthog.com` |
-
-### Provider-Specific
-
-#### Google Auth
-
-Install [`opencode-antigravity-auth`](https://github.com/NoeFabris/opencode-antigravity-auth) for Google Gemini. Provides multi-account load balancing, dual quota, and variant-based thinking.
-
-#### Ollama
-
-**Must** disable streaming to avoid JSON parse errors:
-
-```json
-{
- "agents": {
- "explore": { "model": "ollama/qwen3-coder" }
- }
-}
-```
-
-**Note:** The `stream` option should be configured in your OpenCode settings or via environment variables, not in the agent config. See [Ollama Troubleshooting](../troubleshooting/ollama.md) for details on disabling streaming.
-
-Common models: `ollama/qwen3-coder`, `ollama/ministral-3:14b`, `ollama/lfm2.5-thinking`
-
-See [Ollama Troubleshooting](../troubleshooting/ollama.md) for `JSON Parse error: Unexpected EOF` issues.
diff --git a/docs/reference/features.md b/docs/reference/features.md
index 301d0b5c4..2d6a3ad3f 100644
--- a/docs/reference/features.md
+++ b/docs/reference/features.md
@@ -100,6 +100,17 @@ Parallel multi-agent coordination modeled after Claude Code's experimental Agent
See the **[Team Mode Guide](../guide/team-mode.md)** for configuration, team spec format, lifecycle, bounds, and storage layout.
+### Architecture Snapshot (current)
+
+- **Feature modules**: `src/features/` has 20 modules.
+- **Tool system**: `src/tools/` has 16 tool directories that produce **20 to 39 tools** depending on config gates.
+- **Hook system**: 5-tier composition is **52 base hooks**. With team mode it becomes **59** (extra tool guard + transforms + direct team session event handlers).
+- **MCP system**: 3 tiers: built-in remote MCPs (`websearch`, `context7`, `grep_app`), `.mcp.json` loader, and skill-embedded MCP from `SKILL.md` frontmatter.
+- **Managers**: plugin startup creates 4 managers: TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler.
+- **Config pipeline**: 6 phases in order: provider, plugin-components, agents, tools, MCPs, commands.
+- **Canonical core agent order**: Sisyphus, Hephaestus, Prometheus, Atlas.
+- **OpenClaw**: bidirectional integrations for Discord, Telegram, HTTP, and shell with reply listener daemon.
+
## Category System
A Category is an agent configuration preset optimized for specific domains. Instead of delegating everything to a single AI agent, it is far more efficient to invoke specialists tailored to the nature of the task.
@@ -222,6 +233,11 @@ Configure per-agent fallback chains with arrays that can mix plain model strings
When a model errors, the runtime can move through the configured fallback array. Object entries let you tune the backup model itself instead of only swapping the model name.
+The plugin uses two independent fallback systems:
+
+- **model-fallback**: proactive model chain selection in chat params.
+- **runtime-fallback**: reactive recovery after runtime failures from provider/API behavior.
+
### File-Based Prompts
Load agent system prompts from external files using `file://` URLs in the `prompt` field, or append additional content with `prompt_append`. The `prompt_append` field also works on categories.
@@ -394,6 +410,8 @@ This content will be injected into the agent's system prompt.
Same-named skill at higher priority overrides lower.
+Loaded skill display priority follows this order: `project > user > opencode > builtin/plugin`.
+
Disable built-in skills via `disabled_skills: ["playwright"]` in config.
### Category + Skill Combo Strategies
@@ -561,6 +579,8 @@ Load custom commands from:
## Tools
+Tool registration is config-gated. `src/tools/` has 16 directories, and exposed tools range from **20 minimum to 39 maximum**.
+
### Code Search Tools
| Tool | Description |
@@ -572,7 +592,9 @@ Load custom commands from:
| Tool | Description |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **edit** | Hash-anchored edit tool. Uses `LINE#ID` format for precise, safe modifications. Validates content hashes before applying changes — zero stale-line errors. |
+| **edit** | Hash-anchored edit tool. Uses `LINE#ID` format for precise, safe modifications. Validates content hashes before applying changes and rejects stale hash edits. |
+
+Hashline IDs use characters from `ZPMQVRWSNKTXJBYH`.
### LSP Tools (IDE Features for Agents)
@@ -725,6 +747,16 @@ interactive_bash(tmux_command="capture-pane -p -t dev-app")
Hooks intercept and modify behavior at key points in the agent lifecycle across the full session, message, tool, and parameter pipeline.
+Current composition counts:
+
+- Session: 24
+- Tool Guard: 14
+- Transform: 5
+- Continuation: 7
+- Skill: 2
+- Total base: 52
+- With `team_mode.enabled`: +1 Tool Guard, +2 Transform, +4 direct team session event handlers in `src/plugin/event.ts` = 59
+
### Hook Events
| Event | When | Can |
@@ -753,7 +785,7 @@ Hooks intercept and modify behavior at key points in the agent lifecycle across
| Hook | Event | Description |
| --------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **keyword-detector** | Message + Transform | Detects keywords and activates modes: `ultrawork`/`ulw` (max performance), `search`/`find` (parallel exploration), `analyze`/`investigate` (deep analysis). |
+| **keyword-detector** | Message + Transform | IntentGate detector. Activates `ultrawork`/`ulw`, `search`, `analyze`, and `team` modes from message keywords. |
| **think-mode** | Params | Auto-detects extended thinking needs. Catches "think deeply", "ultrathink" and adjusts model settings. |
| **ralph-loop** | Event + Message | Manages self-referential loop continuation. |
| **start-work** | Message | Handles /start-work command execution. |
@@ -766,7 +798,7 @@ Hooks intercept and modify behavior at key points in the agent lifecycle across
| Hook | Event | Description |
| ------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------- |
-| **comment-checker** | PostToolUse | Reminds agents to reduce excessive comments. Smartly ignores BDD, directives, docstrings. |
+| **comment-checker** | PostToolUse | Runs `@code-yeongyu/comment-checker` to block AI-slop comment patterns. Bypass options: `// @allow` for a line, `// comment-checker-disable-file` at file top. |
| **thinking-block-validator** | Transform | Validates thinking blocks to prevent API errors. |
| **edit-error-recovery** | PostToolUse + Event | Recovers from edit tool failures. |
| **write-existing-file-guard** | PreToolUse | Prevents accidental overwrites of existing files without reading them first. |
@@ -869,6 +901,12 @@ Disable specific hooks in config:
## MCPs
+The plugin uses a three-tier MCP architecture:
+
+1. Built-in remote MCPs from `src/mcp/`
+2. Claude Code `.mcp.json` loader with `${VAR}` expansion
+3. Skill-embedded MCP servers declared in `SKILL.md` frontmatter
+
### Built-in MCPs
| MCP | Description |
@@ -893,6 +931,8 @@ mcp:
The `skill_mcp` tool invokes these operations with full schema discovery.
+Skill MCP clients are isolated per session by key `${sessionID}:${skillName}:${serverName}`.
+
#### OAuth-Enabled MCPs
Skills can define OAuth-protected remote MCP servers. OAuth 2.1 with full RFC compliance (RFC 9728, 8414, 8707, 7591) is supported: