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

docs: refresh user-facing guide + reference for current code state

Browse Source 
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).
This commit is contained in:
YeonGyu-Kim
2026-05-08 16:14:30 +09:00
parent 457836b965
commit 810e3c7a51
11 changed files with 531 additions and 1337 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/examples/coding-focused.jsonc
+1 -1
View File
@@ -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.
docs/examples/default.jsonc
+1 -1
View File
@@ -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.
docs/examples/planning-focused.jsonc
+1 -1
View File
@@ -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.
docs/guide/agent-model-matching.md
+1 -1
View File
@@ -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
docs/guide/installation.md
+20 -3
View File
@@ -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
docs/guide/orchestration.md
+68 -13
View File
@@ -41,11 +41,11 @@ flowchart TB
end
subgraph Execution["Execution Layer (Orchestrator)"]
Orchestrator[" Atlas<br/>(Conductor)<br/>claude-sonnet-4-6 / kimi-k2.5 / gpt-5.5 / minimax-m2.7"]
Orchestrator[" Atlas<br/>(Conductor)<br/>claude-sonnet-4-6 / kimi-k2.6 / gpt-5.5 / minimax-m2.7"]
end
subgraph Workers["Worker Layer (Specialized Agents)"]
Junior[" Sisyphus-Junior<br/>(Task Executor)<br/>claude-sonnet-4-6 / kimi-k2.5 / gpt-5.5 / minimax-m2.7"]
Junior[" Sisyphus-Junior<br/>(Task Executor)<br/>claude-sonnet-4-6 / kimi-k2.6 / gpt-5.5 / minimax-m2.7"]
Oracle[" Oracle<br/>(Architecture)<br/>gpt-5.5 / gemini-3.1-pro / claude-opus-4-7 / glm-5"]
Explore[" Explore<br/>(Codebase Grep)<br/>gpt-5.4-mini-fast / minimax-m2.7-highspeed / claude-haiku-4-5"]
Librarian[" Librarian<br/>(Docs/OSS)<br/>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
docs/guide/overview.md
+3 -3
View File
@@ -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.
docs/guide/team-mode.md
+24 -4
View File
@@ -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 `<project>/.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: `<project>/.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: `<project>/.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
docs/reference/cli.md
+112 -294
View File
@@ -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 <message>` | 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 <no\|yes\|max20>` | Claude subscription mode |
| `--openai <no\|yes>` | OpenAI / ChatGPT subscription |
| `--gemini <no\|yes>` | Gemini integration |
| `--copilot <no\|yes>` | GitHub Copilot subscription |
| `--opencode-zen <no\|yes>` | OpenCode Zen access |
| `--zai-coding-plan <no\|yes>` | Z.ai Coding Plan subscription |
| `--kimi-for-coding <no\|yes>` | Kimi for Coding subscription |
| `--opencode-go <no\|yes>` | OpenCode Go subscription |
| `--vercel-ai-gateway <no\|yes>` | Vercel AI Gateway: no, yes (default: no) |
| --- | --- |
| `--no-tui` | Run in non-interactive mode (requires all needed options) |
| `--claude <value>` | Claude subscription: `no`, `yes`, `max20` |
| `--openai <value>` | OpenAI/ChatGPT subscription: `no`, `yes` |
| `--gemini <value>` | Gemini integration: `no`, `yes` |
| `--copilot <value>` | GitHub Copilot subscription: `no`, `yes` |
| `--opencode-zen <value>` | OpenCode Zen access: `no`, `yes` |
| `--zai-coding-plan <value>` | Z.ai Coding Plan subscription: `no`, `yes` |
| `--kimi-for-coding <value>` | Kimi For Coding subscription: `no`, `yes` |
| `--opencode-go <value>` | OpenCode Go subscription: `no`, `yes` |
| `--vercel-ai-gateway <value>` | 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 <message>
bunx oh-my-openagent run <message>
```
### Options
| Option | Description |
| --------------------- | ------------------------------------------------------------------- |
| `-a, --agent <name>` | Agent to use (default: from CLI/env/config, fallback: Sisyphus) |
| `-m, --model <provider/model>` | Model override (e.g., anthropic/claude-sonnet-4) |
| `-d, --directory <path>` | Working directory |
| `-p, --port <port>` | Server port (attaches if port already in use) |
| `--attach <url>` | Attach to existing opencode server URL |
| `--on-complete <command>` | 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 <id>` | Resume existing session instead of creating new one |
| Option | Description |
| --- | --- |
| `-a, --agent <name>` | Agent to use (default resolution chain applies) |
| `-m, --model <provider/model>` | Model override (example: `anthropic/claude-sonnet-4`) |
| `-d, --directory <path>` | Working directory |
| `-p, --port <port>` | Server port (attaches if already in use) |
| `--attach <url>` | Attach to an existing OpenCode server URL |
| `--on-complete <command>` | 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 <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 <path>` | 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-name> --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-name> --server-url https://api.example.com
# Check OAuth token status
bunx oh-my-opencode mcp oauth status [server-name]
```
### Options
| Option | Description |
| -------------------- | ------------------------------------------------------------------------- |
| `--server-url <url>` | MCP server URL (required for login) |
| `--client-id <id>` | OAuth client ID (optional if server supports Dynamic Client Registration) |
| `--scopes <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 <url>` | Override the models.dev source URL |
| `--json` | Output refresh summary as JSON |
| Option | Description |
| --- | --- |
| `-d, --directory <path>` | Working directory used to read plugin config |
| `--source-url <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-name> --server-url https://api.example.com
# Authenticate with explicit client ID and scopes
bunx oh-my-openagent mcp oauth login <server-name> --server-url https://api.example.com --client-id my-client --scopes read write
# Remove stored tokens
bunx oh-my-openagent mcp oauth logout <server-name> --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 <url>` | OAuth server URL (required by `login`, and required by `logout`) |
| `--client-id <id>` | OAuth client ID (optional if server supports DCR) |
| `--scopes <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.
docs/reference/configuration.md
+257 -1013
View File
File diff suppressed because it is too large Load Diff
docs/reference/features.md
+43 -3
View File
@@ -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: