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
+112
-294
@@ -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.
|
||||
|
||||
+257
-1013
File diff suppressed because it is too large
Load Diff
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user