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/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.