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).
This commit is contained in:
YeonGyu-Kim
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
+68
-13
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
+24
-4
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user