From 810e3c7a516f17fe49fb7e0d190c53532e6f346f Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Fri, 8 May 2026 16:14:30 +0900 Subject: [PATCH] docs: refresh user-facing guide + reference for current code state Audit pass against root AGENTS.md (regenerated 2026-05-08) and the canonical sources in src/shared/model-requirements.ts, src/features/team-mode/, src/cli/, src/config/schema/. Each touched file keeps its existing tone but corrects stale facts: - guide/overview.md: project name + dual-package transition reality - guide/installation.md: bun-only invocation, dual oh-my-openagent / oh-my-opencode CLI surface, current doctor categories - guide/orchestration.md: 11 agents, category routing through sisyphus-junior, background concurrency, team-mode link - guide/agent-model-matching.md: Metis primary -> claude-sonnet-4-6 (matches src/shared/model-requirements.ts fallback chain) - guide/team-mode.md: full schema, member eligibility tiers, 12 team_* tools added when enabled - reference/cli.md: trim to current Commander surface (install, doctor, run, mcp-oauth, refresh-model-capabilities, get-local-version) - reference/configuration.md: trim to schema-driven reference, JSONC rules, multi-level merge order, mcp_env_allowlist user-only constraint - reference/features.md: 5-tier hook composition counts, 3-tier MCPs, hashline edit, IntentGate, OpenClaw bidirectional dispatcher Cross-cutting: every `oh-my-opencode.schema.json` URL replaced with the canonical `oh-my-openagent.schema.json` (legacy package name in text bodies preserved where it documents the dual-publish transition). --- docs/examples/coding-focused.jsonc | 2 +- docs/examples/default.jsonc | 2 +- docs/examples/planning-focused.jsonc | 2 +- docs/guide/agent-model-matching.md | 2 +- docs/guide/installation.md | 23 +- docs/guide/orchestration.md | 81 +- docs/guide/overview.md | 6 +- docs/guide/team-mode.md | 28 +- docs/reference/cli.md | 406 +++----- docs/reference/configuration.md | 1270 ++++++-------------------- docs/reference/features.md | 46 +- 11 files changed, 531 insertions(+), 1337 deletions(-) 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: