diff --git a/docs/reference/features.md b/docs/reference/features.md index 94d22d774..bd046276f 100644 --- a/docs/reference/features.md +++ b/docs/reference/features.md @@ -6,29 +6,29 @@ Oh-My-OpenCode provides 11 specialized AI agents. Each has distinct expertise, o ### Core Agents -| Agent | Model | Purpose | -|-------|-------|---------| -| **Sisyphus** | `claude-opus-4-6` | The default orchestrator. Plans, delegates, and executes complex tasks using specialized subagents with aggressive parallel execution. Todo-driven workflow with extended thinking (32k budget). Fallback: gpt-5.3-codex → deep quality chain. | -| **Hephaestus** | `gpt-5.3-codex` | The Legitimate Craftsman. Autonomous deep worker inspired by AmpCode's deep mode. Goal-oriented execution with thorough research before action. Explores codebase patterns, completes tasks end-to-end without premature stopping. Named after the Greek god of forge and craftsmanship. Fallback: deep quality chain (claude-opus-4-6-thinking → step-3.5-flash → glm-5 → ...). Requires at least one model in the chain to be available. | -| **Oracle** | `gpt-5.3-codex` | Architecture decisions, code review, debugging. Read-only consultation with stellar logical reasoning and deep analysis. Inspired by AmpCode. Fallback: claude-opus-4-6-thinking → claude-sonnet-4-5-thinking → deep quality chain. | -| **Librarian** | `claude-sonnet-4-5` | Multi-repo analysis, documentation lookup, OSS implementation examples. Deep codebase understanding with evidence-based answers. Fallback: speed chain (claude-haiku-4-5 → gpt-5-mini → ...) → quality chain. | -| **Explore** | `claude-haiku-4-5` | Fast codebase exploration and contextual grep. Fallback: oswe-vscode-prime → gpt-5-mini → gpt-4.1 → extended speed chain. | -| **Multimodal-Looker** | `gemini-3-pro-image` | Visual content specialist. Analyzes PDFs, images, diagrams to extract information. Fallback: gemini-3-pro-high → gemini-3-flash → kimi-k2.5 → claude-opus-4-6-thinking → claude-sonnet-4-5-thinking → claude-haiku-4-5 → gpt-5-nano. | +| Agent | Model | Purpose | +| --------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Sisyphus** | `claude-opus-4-6` | The default orchestrator. Plans, delegates, and executes complex tasks using specialized subagents with aggressive parallel execution. Todo-driven workflow with extended thinking (32k budget). Fallback: `glm-5` → `big-pickle`. | +| **Hephaestus** | `gpt-5.3-codex` | The Legitimate Craftsman. Autonomous deep worker inspired by AmpCode's deep mode. Goal-oriented execution with thorough research before action. Explores codebase patterns, completes tasks end-to-end without premature stopping. Named after the Greek god of forge and craftsmanship. Fallback: `gpt-5.2` on GitHub Copilot. Requires a GPT-capable provider. | +| **Oracle** | `gpt-5.2` | Architecture decisions, code review, debugging. Read-only consultation with stellar logical reasoning and deep analysis. Inspired by AmpCode. Fallback: `gemini-3.1-pro` → `claude-opus-4-6`. | +| **Librarian** | `gemini-3-flash` | Multi-repo analysis, documentation lookup, OSS implementation examples. Deep codebase understanding with evidence-based answers. Fallback: `minimax-m2.5-free` → `big-pickle`. | +| **Explore** | `grok-code-fast-1` | Fast codebase exploration and contextual grep. Fallback: `minimax-m2.5-free` → `claude-haiku-4-5` → `gpt-5-nano`. | +| **Multimodal-Looker** | `gpt-5.3-codex` | Visual content specialist. Analyzes PDFs, images, diagrams to extract information. Fallback: `k2p5` → `gemini-3-flash` → `glm-4.6v` → `gpt-5-nano`. | ### Planning Agents -| Agent | Model | Purpose | -|-------|-------|---------| -| **Prometheus** | `claude-opus-4-6-thinking` | Strategic planner with interview mode. Creates detailed work plans through iterative questioning. Fallback: gpt-5.3-codex → claude-sonnet-4-5-thinking → deep quality chain. | -| **Metis** | `claude-opus-4-6-thinking` | Plan consultant — pre-planning analysis. Identifies hidden intentions, ambiguities, and AI failure points. Fallback: gpt-5.3-codex → claude-sonnet-4-5-thinking → deep quality chain. | -| **Momus** | `gpt-5.3-codex` | Plan reviewer — validates plans against clarity, verifiability, and completeness standards. Fallback: claude-opus-4-6-thinking → deep quality chain. | +| Agent | Model | Purpose | +| -------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Prometheus** | `claude-opus-4-6` | Strategic planner with interview mode. Creates detailed work plans through iterative questioning. Fallback: `gpt-5.4` → `gemini-3.1-pro`. | +| **Metis** | `claude-opus-4-6` | Plan consultant — pre-planning analysis. Identifies hidden intentions, ambiguities, and AI failure points. Fallback: `gpt-5.2` → `gemini-3.1-pro`. | +| **Momus** | `gpt-5.4` | Plan reviewer — validates plans against clarity, verifiability, and completeness standards. Fallback: `claude-opus-4-6` → `gemini-3.1-pro`. | ### Orchestration Agents -| Agent | Model | Purpose | -|-------|-------|---------| -| **Atlas** | `claude-sonnet-4-5-thinking` | Todo-list orchestrator. Executes planned tasks systematically, managing todo items and coordinating work. Fallback: claude-opus-4-6-thinking → gpt-5.3-codex → deep quality chain. | -| **Sisyphus-Junior** | *(category-dependent)* | Category-spawned executor. Model is selected automatically based on the task category (visual-engineering, quick, deep, etc.). Used when the main agent delegates work via the `task` tool. | +| Agent | Model | Purpose | +| ------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Atlas** | `claude-sonnet-4-6` | Todo-list orchestrator. Executes planned tasks systematically, managing todo items and coordinating work. Fallback: `gpt-5.4` (medium). | +| **Sisyphus-Junior** | _(category-dependent)_ | Category-spawned executor. Model is selected automatically based on the task category (visual-engineering, quick, deep, etc.). Used when the main agent delegates work via the `task` tool. | ### Invoking Agents @@ -42,14 +42,14 @@ Ask @explore for the policy on this feature ### Tool Restrictions -| Agent | Restrictions | -|-------|-------------| -| oracle | Read-only: cannot write, edit, or delegate (blocked: write, edit, task, call_omo_agent) | -| librarian | Cannot write, edit, or delegate (blocked: write, edit, task, call_omo_agent) | -| explore | Cannot write, edit, or delegate (blocked: write, edit, task, call_omo_agent) | -| multimodal-looker | Allowlist: `read` only | -| atlas | Cannot delegate (blocked: task, call_omo_agent) | -| momus | Cannot write, edit, or delegate (blocked: write, edit, task) | +| Agent | Restrictions | +| ----------------- | --------------------------------------------------------------------------------------- | +| oracle | Read-only: cannot write, edit, or delegate (blocked: write, edit, task, call_omo_agent) | +| librarian | Cannot write, edit, or delegate (blocked: write, edit, task, call_omo_agent) | +| explore | Cannot write, edit, or delegate (blocked: write, edit, task, call_omo_agent) | +| multimodal-looker | Allowlist: `read` only | +| atlas | Cannot delegate (blocked: task, call_omo_agent) | +| momus | Cannot write, edit, or delegate (blocked: write, edit, task) | ### Background Agents @@ -84,6 +84,7 @@ Enable `tmux.enabled` to see background agents in separate tmux panes: ``` When running inside tmux: + - Background agents spawn in new panes - Watch multiple agents work in real-time - Each pane shows agent output live @@ -104,26 +105,26 @@ By combining these two concepts, you can generate optimal agents through `task`. ### Built-in Categories -| Category | Default Model | Use Cases | -|----------|---------------|-----------| -| `visual-engineering` | `google/gemini-3-pro` | Frontend, UI/UX, design, styling, animation | -| `ultrabrain` | `openai/gpt-5.3-codex` (xhigh) | Deep logical reasoning, complex architecture decisions requiring extensive analysis | -| `deep` | `openai/gpt-5.3-codex` (medium) | Goal-oriented autonomous problem-solving. Thorough research before action. For hairy problems requiring deep understanding. | -| `artistry` | `google/gemini-3-pro` (max) | Highly creative/artistic tasks, novel ideas | -| `quick` | `anthropic/claude-haiku-4-5` | Trivial tasks - single file changes, typo fixes, simple modifications | -| `unspecified-low` | `anthropic/claude-sonnet-4-6` | Tasks that don't fit other categories, low effort required | -| `unspecified-high` | `anthropic/claude-opus-4-6` (max) | Tasks that don't fit other categories, high effort required | -| `writing` | `kimi-for-coding/k2p5` | Documentation, prose, technical writing | +| Category | Default Model | Use Cases | +| -------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| `visual-engineering` | `google/gemini-3.1-pro` | Frontend, UI/UX, design, styling, animation | +| `ultrabrain` | `openai/gpt-5.3-codex` (xhigh) | Deep logical reasoning, complex architecture decisions requiring extensive analysis | +| `deep` | `openai/gpt-5.3-codex` (medium) | Goal-oriented autonomous problem-solving. Thorough research before action. For hairy problems requiring deep understanding. | +| `artistry` | `google/gemini-3.1-pro` (high) | Highly creative/artistic tasks, novel ideas | +| `quick` | `anthropic/claude-haiku-4-5` | Trivial tasks - single file changes, typo fixes, simple modifications | +| `unspecified-low` | `anthropic/claude-sonnet-4-6` | Tasks that don't fit other categories, low effort required | +| `unspecified-high` | `openai/gpt-5.4` (high) | Tasks that don't fit other categories, high effort required | +| `writing` | `google/gemini-3-flash` | Documentation, prose, technical writing | ### Usage Specify the `category` parameter when invoking the `task` tool. ```typescript -task( - category="visual-engineering", - prompt="Add a responsive chart component to the dashboard page" -) +task({ + category: "visual-engineering", + prompt: "Add a responsive chart component to the dashboard page", +}); ``` ### Custom Categories @@ -132,20 +133,20 @@ You can define custom categories in `oh-my-opencode.json`. #### Category Configuration Schema -| Field | Type | Description | -|-------|------|-------------| -| `description` | string | Human-readable description of the category's purpose. Shown in task prompt. | -| `model` | string | AI model ID to use (e.g., `anthropic/claude-opus-4-6`) | -| `variant` | string | Model variant (e.g., `max`, `xhigh`) | -| `temperature` | number | Creativity level (0.0 ~ 2.0). Lower is more deterministic. | -| `top_p` | number | Nucleus sampling parameter (0.0 ~ 1.0) | -| `prompt_append` | string | Content to append to system prompt when this category is selected | -| `thinking` | object | Thinking model configuration (`{ type: "enabled", budgetTokens: 16000 }`) | -| `reasoningEffort` | string | Reasoning effort level (`low`, `medium`, `high`) | -| `textVerbosity` | string | Text verbosity level (`low`, `medium`, `high`) | -| `tools` | object | Tool usage control (disable with `{ "tool_name": false }`) | -| `maxTokens` | number | Maximum response token count | -| `is_unstable_agent` | boolean | Mark agent as unstable - forces background mode for monitoring | +| Field | Type | Description | +| ------------------- | ------- | --------------------------------------------------------------------------- | +| `description` | string | Human-readable description of the category's purpose. Shown in task prompt. | +| `model` | string | AI model ID to use (e.g., `anthropic/claude-opus-4-6`) | +| `variant` | string | Model variant (e.g., `max`, `xhigh`) | +| `temperature` | number | Creativity level (0.0 ~ 2.0). Lower is more deterministic. | +| `top_p` | number | Nucleus sampling parameter (0.0 ~ 1.0) | +| `prompt_append` | string | Content to append to system prompt when this category is selected | +| `thinking` | object | Thinking model configuration (`{ type: "enabled", budgetTokens: 16000 }`) | +| `reasoningEffort` | string | Reasoning effort level (`low`, `medium`, `high`) | +| `textVerbosity` | string | Text verbosity level (`low`, `medium`, `high`) | +| `tools` | object | Tool usage control (disable with `{ "tool_name": false }`) | +| `maxTokens` | number | Maximum response token count | +| `is_unstable_agent` | boolean | Mark agent as unstable - forces background mode for monitoring | #### Example Configuration @@ -156,13 +157,13 @@ You can define custom categories in `oh-my-opencode.json`. "korean-writer": { "model": "google/gemini-3-flash", "temperature": 0.5, - "prompt_append": "You are a Korean technical writer. Maintain a friendly and clear tone." + "prompt_append": "You are a Korean technical writer. Maintain a friendly and clear tone.", }, - + // 2. Override existing category (change model) "visual-engineering": { - "model": "openai/gpt-5.2", - "temperature": 0.8 + "model": "openai/gpt-5.4", + "temperature": 0.8, }, // 3. Configure thinking model and restrict tools @@ -170,13 +171,13 @@ You can define custom categories in `oh-my-opencode.json`. "model": "anthropic/claude-opus-4-6", "thinking": { "type": "enabled", - "budgetTokens": 32000 + "budgetTokens": 32000, }, "tools": { - "websearch_web_search_exa": false - } - } - } + "websearch_web_search_exa": false, + }, + }, + }, } ``` @@ -193,15 +194,19 @@ Skills provide specialized workflows with embedded MCP servers and detailed inst ### Built-in Skills -| Skill | Trigger | Description | -|-------|---------|-------------| -| **git-master** | commit, rebase, squash, "who wrote", "when was X added" | Git expert. Detects commit styles, splits atomic commits, formulates rebase strategies. Three specializations: Commit Architect (atomic commits, dependency ordering, style detection), Rebase Surgeon (history rewriting, conflict resolution, branch cleanup), History Archaeologist (finding when/where specific changes were introduced). | -| **playwright** | Browser tasks, testing, screenshots | Browser automation via Playwright MCP. MUST USE for any browser-related tasks - verification, browsing, web scraping, testing, screenshots. | -| **frontend-ui-ux** | UI/UX tasks, styling | Designer-turned-developer persona. Crafts stunning UI/UX even without design mockups. Emphasizes bold aesthetic direction, distinctive typography, cohesive color palettes. | +| Skill | Trigger | Description | +| ------------------ | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **git-master** | commit, rebase, squash, "who wrote", "when was X added" | Git expert. Detects commit styles, splits atomic commits, formulates rebase strategies. Three specializations: Commit Architect (atomic commits, dependency ordering, style detection), Rebase Surgeon (history rewriting, conflict resolution, branch cleanup), History Archaeologist (finding when/where specific changes were introduced). | +| **playwright** | Browser tasks, testing, screenshots | Browser automation via Playwright MCP. MUST USE for browser verification, browsing, web scraping, testing, and screenshots. | +| **playwright-cli** | Browser tasks on Playwright CLI | Browser automation through the Playwright CLI integration. Useful when direct CLI scripting is preferred over MCP. | +| **agent-browser** | Browser tasks on agent-browser | Browser automation via the `agent-browser` CLI. Covers navigation, snapshots, screenshots, network inspection, and scripted interactions. | +| **dev-browser** | Stateful browser scripting | Browser automation with persistent page state for iterative workflows and authenticated sessions. | +| **frontend-ui-ux** | UI/UX tasks, styling | Designer-turned-developer persona. Crafts stunning UI/UX even without design mockups. Emphasizes bold aesthetic direction, distinctive typography, cohesive color palettes. | #### git-master Core Principles **Multiple Commits by Default**: + ``` 3+ files -> MUST be 2+ commits 5+ files -> MUST be 3+ commits @@ -209,10 +214,12 @@ Skills provide specialized workflows with embedded MCP servers and detailed inst ``` **Automatic Style Detection**: + - Analyzes last 30 commits for language (Korean/English) and style (semantic/plain/short) - Matches your repo's commit conventions automatically **Usage**: + ``` /git-master commit these changes /git-master rebase onto main @@ -242,6 +249,7 @@ mcp: ``` **Usage**: + ``` /playwright Navigate to example.com and take a screenshot ``` @@ -257,16 +265,19 @@ mcp: ``` **Requires installation**: + ```bash bun add -g agent-browser ``` **Usage**: + ``` Use agent-browser to navigate to example.com and extract the main heading ``` **Capabilities (Both Providers)**: + - Navigate and interact with web pages - Take screenshots and PDFs - Fill forms and click elements @@ -296,6 +307,7 @@ This content will be injected into the agent's system prompt. ``` **Skill Load Locations** (priority order, highest first): + - `.opencode/skills/*/SKILL.md` (project, OpenCode native) - `~/.config/opencode/skills/*/SKILL.md` (user, OpenCode native) - `.claude/skills/*/SKILL.md` (project, Claude Code compat) @@ -341,9 +353,11 @@ When delegating, **clear and specific** prompts are essential. Include these 7 e 7. **CONTEXT**: File paths, existing patterns, reference materials **Bad Example**: + > "Fix this" **Good Example**: + > **TASK**: Fix mobile layout breaking issue in `LoginButton.tsx` > **CONTEXT**: `src/components/LoginButton.tsx`, using Tailwind CSS > **MUST DO**: Change flex-direction at `md:` breakpoint @@ -356,27 +370,29 @@ Commands are slash-triggered workflows that execute predefined templates. ### Built-in Commands -| Command | Description | -|---------|-------------| -| `/init-deep` | Initialize hierarchical AGENTS.md knowledge base | -| `/ralph-loop` | Start self-referential development loop until completion | -| `/ulw-loop` | Start ultrawork loop - continues with ultrawork mode | -| `/cancel-ralph` | Cancel active Ralph Loop | -| `/refactor` | Intelligent refactoring with LSP, AST-grep, architecture analysis, and TDD verification | -| `/start-work` | Start Sisyphus work session from Prometheus plan | +| Command | Description | +| -------------------- | ------------------------------------------------------------------------------------------ | +| `/init-deep` | Initialize hierarchical AGENTS.md knowledge base | +| `/ralph-loop` | Start self-referential development loop until completion | +| `/ulw-loop` | Start ultrawork loop - continues with ultrawork mode | +| `/cancel-ralph` | Cancel active Ralph Loop | +| `/refactor` | Intelligent refactoring with LSP, AST-grep, architecture analysis, and TDD verification | +| `/start-work` | Start Sisyphus work session from Prometheus plan | | `/stop-continuation` | Stop all continuation mechanisms (ralph loop, todo continuation, boulder) for this session | -| `/handoff` | Create a detailed context summary for continuing work in a new session | +| `/handoff` | Create a detailed context summary for continuing work in a new session | ### /init-deep **Purpose**: Generate hierarchical AGENTS.md files throughout your project **Usage**: + ``` /init-deep [--create-new] [--max-depth=N] ``` Creates directory-specific context files that agents automatically read: + ``` project/ ├── AGENTS.md # Project-wide context @@ -393,12 +409,14 @@ project/ **Named after**: Anthropic's Ralph Wiggum plugin **Usage**: + ``` /ralph-loop "Build a REST API with authentication" /ralph-loop "Refactor the payment module" --max-iterations=50 ``` **Behavior**: + - Agent works continuously toward the goal - Detects `DONE` to know when complete - Auto-continues if agent stops without completion @@ -417,11 +435,13 @@ Everything runs at maximum intensity - parallel agents, background tasks, aggres **Purpose**: Intelligent refactoring with full toolchain **Usage**: + ``` /refactor [--scope=] [--strategy=] ``` **Features**: + - LSP-powered rename and navigation - AST-grep for pattern matching - Architecture analysis before changes @@ -433,6 +453,7 @@ Everything runs at maximum intensity - parallel agents, background tasks, aggres **Purpose**: Start execution from a Prometheus-generated plan **Usage**: + ``` /start-work [plan-name] ``` @@ -454,6 +475,7 @@ Generates a structured handoff document capturing the current state, what was do ### Custom Commands Load custom commands from: + - `.opencode/command/*.md` (project, OpenCode native) - `~/.config/opencode/command/*.md` (user, OpenCode native) - `.claude/commands/*.md` (project, Claude Code compat) @@ -463,94 +485,95 @@ Load custom commands from: ### Code Search Tools -| Tool | Description | -|------|-------------| +| Tool | Description | +| -------- | ----------------------------------------------------------------- | | **grep** | Content search using regular expressions. Filter by file pattern. | -| **glob** | Fast file pattern matching. Find files by name patterns. | +| **glob** | Fast file pattern matching. Find files by name patterns. | ### Edit Tools -| Tool | Description | -|------|-------------| +| 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. | ### LSP Tools (IDE Features for Agents) -| Tool | Description | -|------|-------------| -| **lsp_diagnostics** | Get errors/warnings before build | -| **lsp_prepare_rename** | Validate rename operation | -| **lsp_rename** | Rename symbol across workspace | -| **lsp_goto_definition** | Jump to symbol definition | -| **lsp_find_references** | Find all usages across workspace | -| **lsp_symbols** | Get file outline or workspace symbol search | +| Tool | Description | +| ----------------------- | ------------------------------------------- | +| **lsp_diagnostics** | Get errors/warnings before build | +| **lsp_prepare_rename** | Validate rename operation | +| **lsp_rename** | Rename symbol across workspace | +| **lsp_goto_definition** | Jump to symbol definition | +| **lsp_find_references** | Find all usages across workspace | +| **lsp_symbols** | Get file outline or workspace symbol search | ### AST-Grep Tools -| Tool | Description | -|------|-------------| -| **ast_grep_search** | AST-aware code pattern search (25 languages) | -| **ast_grep_replace** | AST-aware code replacement | +| Tool | Description | +| -------------------- | -------------------------------------------- | +| **ast_grep_search** | AST-aware code pattern search (25 languages) | +| **ast_grep_replace** | AST-aware code replacement | ### Delegation Tools -| Tool | Description | -|------|-------------| -| **call_omo_agent** | Spawn explore/librarian agents. Supports `run_in_background`. | -| **task** | Category-based task delegation. Supports categories (visual-engineering, deep, quick, ultrabrain) or direct agent targeting via `subagent_type`. | -| **background_output** | Retrieve background task results | -| **background_cancel** | Cancel running background tasks | +| Tool | Description | +| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **call_omo_agent** | Spawn explore/librarian agents. Supports `run_in_background`. | +| **task** | Category-based task delegation. Supports built-in categories like `visual-engineering`, `ultrabrain`, `deep`, `artistry`, `quick`, `unspecified-low`, `unspecified-high`, and `writing`, or direct agent targeting via `subagent_type`. | +| **background_output** | Retrieve background task results | +| **background_cancel** | Cancel running background tasks | ### Visual Analysis Tools -| Tool | Description | -|------|-------------| +| Tool | Description | +| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **look_at** | Analyze media files (PDFs, images, diagrams) via Multimodal-Looker agent. Extracts specific information or summaries from documents, describes visual content. | ### Skill Tools -| Tool | Description | -|------|-------------| -| **skill** | Load and execute a skill or slash command by name. Returns detailed instructions with context applied. | -| **skill_mcp** | Invoke MCP server operations from skill-embedded MCPs. | +| Tool | Description | +| ------------- | ------------------------------------------------------------------------------------------------------ | +| **skill** | Load and execute a skill or slash command by name. Returns detailed instructions with context applied. | +| **skill_mcp** | Invoke MCP server operations from skill-embedded MCPs. | ### Session Tools -| Tool | Description | -|------|-------------| -| **session_list** | List all OpenCode sessions | -| **session_read** | Read messages and history from a session | +| Tool | Description | +| ------------------ | ---------------------------------------- | +| **session_list** | List all OpenCode sessions | +| **session_read** | Read messages and history from a session | | **session_search** | Full-text search across session messages | -| **session_info** | Get session metadata and statistics | +| **session_info** | Get session metadata and statistics | ### Task Management Tools Requires `experimental.task_system: true` in config. -| Tool | Description | -|------|-------------| +| Tool | Description | +| --------------- | ---------------------------------------- | | **task_create** | Create a new task with auto-generated ID | -| **task_get** | Retrieve a task by ID | -| **task_list** | List all active tasks | -| **task_update** | Update an existing task | +| **task_get** | Retrieve a task by ID | +| **task_list** | List all active tasks | +| **task_update** | Update an existing task | #### Task System Details **Note on Claude Code Alignment**: This implementation follows Claude Code's internal Task tool signatures (`TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet`) and field naming conventions (`subject`, `blockedBy`, `blocks`, etc.). However, Anthropic has not published official documentation for these tools. This is Oh My OpenCode's own implementation based on observed Claude Code behavior and internal specifications. **Task Schema**: + ```ts interface Task { - id: string // T-{uuid} - subject: string // Imperative: "Run tests" - description: string - status: "pending" | "in_progress" | "completed" | "deleted" - activeForm?: string // Present continuous: "Running tests" - blocks: string[] // Tasks this blocks - blockedBy: string[] // Tasks blocking this - owner?: string // Agent name - metadata?: Record - threadID: string // Session ID (auto-set) + id: string; // T-{uuid} + subject: string; // Imperative: "Run tests" + description: string; + status: "pending" | "in_progress" | "completed" | "deleted"; + activeForm?: string; // Present continuous: "Running tests" + blocks: string[]; // Tasks this blocks + blockedBy: string[]; // Tasks blocking this + owner?: string; // Agent name + metadata?: Record; + threadID: string; // Session ID (auto-set) } ``` @@ -566,19 +589,19 @@ interface Task { - Dependent tasks wait until blockers complete **Example Workflow**: -```ts -TaskCreate({ subject: "Build frontend" }) // T-001 -TaskCreate({ subject: "Build backend" }) // T-002 -TaskCreate({ subject: "Run integration tests", - blockedBy: ["T-001", "T-002"] }) // T-003 -TaskList() +```ts +TaskCreate({ subject: "Build frontend" }); // T-001 +TaskCreate({ subject: "Build backend" }); // T-002 +TaskCreate({ subject: "Run integration tests", blockedBy: ["T-001", "T-002"] }); // T-003 + +TaskList(); // T-001 [pending] Build frontend blockedBy: [] // T-002 [pending] Build backend blockedBy: [] // T-003 [pending] Integration tests blockedBy: [T-001, T-002] -TaskUpdate({ id: "T-001", status: "completed" }) -TaskUpdate({ id: "T-002", status: "completed" }) +TaskUpdate({ id: "T-001", status: "completed" }); +TaskUpdate({ id: "T-002", status: "completed" }); // T-003 now unblocked ``` @@ -586,22 +609,23 @@ TaskUpdate({ id: "T-002", status: "completed" }) **Difference from TodoWrite**: -| Feature | TodoWrite | Task System | -|---------|-----------|-------------| -| Storage | Session memory | File system | -| Persistence | Lost on close | Survives restart | -| Dependencies | None | Full support (`blockedBy`) | -| Parallel execution | Manual | Automatic optimization | +| Feature | TodoWrite | Task System | +| ------------------ | -------------- | -------------------------- | +| Storage | Session memory | File system | +| Persistence | Lost on close | Survives restart | +| Dependencies | None | Full support (`blockedBy`) | +| Parallel execution | Manual | Automatic optimization | **When to Use**: Use Tasks when work has multiple steps with dependencies, multiple subagents will collaborate, or progress should persist across sessions. ### Interactive Terminal Tools -| Tool | Description | -|------|-------------| +| Tool | Description | +| -------------------- | -------------------------------------------------------------------------------------------------- | | **interactive_bash** | Tmux-based terminal for TUI apps (vim, htop, pudb). Pass tmux subcommands directly without prefix. | **Usage Examples**: + ```bash # Create a new session interactive_bash(tmux_command="new-session -d -s dev-app") @@ -614,122 +638,123 @@ interactive_bash(tmux_command="capture-pane -p -t dev-app") ``` **Key Points**: + - Commands are tmux subcommands (no `tmux` prefix) - Use for interactive apps that need persistent sessions - One-shot commands should use regular `Bash` tool with `&` ## Hooks -Hooks intercept and modify behavior at key points in the agent lifecycle. 44 hooks across 5 tiers. +Hooks intercept and modify behavior at key points in the agent lifecycle across the full session, message, tool, and parameter pipeline. ### Hook Events -| Event | When | Can | -|-------|------|-----| -| **PreToolUse** | Before tool execution | Block, modify input, inject context | -| **PostToolUse** | After tool execution | Add warnings, modify output, inject messages | -| **Message** | During message processing | Transform content, detect keywords, activate modes | -| **Event** | On session lifecycle changes | Recovery, fallback, notifications | -| **Transform** | During context transformation | Inject context, validate blocks | -| **Params** | When setting API parameters | Adjust model settings, effort level | +| Event | When | Can | +| --------------- | ----------------------------- | -------------------------------------------------- | +| **PreToolUse** | Before tool execution | Block, modify input, inject context | +| **PostToolUse** | After tool execution | Add warnings, modify output, inject messages | +| **Message** | During message processing | Transform content, detect keywords, activate modes | +| **Event** | On session lifecycle changes | Recovery, fallback, notifications | +| **Transform** | During context transformation | Inject context, validate blocks | +| **Params** | When setting API parameters | Adjust model settings, effort level | ### Built-in Hooks #### Context & Injection -| Hook | Event | Description | -|------|-------|-------------| -| **directory-agents-injector** | PreToolUse + PostToolUse | Auto-injects AGENTS.md when reading files. Walks from file to project root, collecting all AGENTS.md files. Deprecated for OpenCode 1.1.37+ — Auto-disabled when native AGENTS.md injection is available. | -| **directory-readme-injector** | PreToolUse + PostToolUse | Auto-injects README.md for directory context. | -| **rules-injector** | PreToolUse + PostToolUse | Injects rules from `.claude/rules/` when conditions match. Supports globs and alwaysApply. | -| **compaction-context-injector** | Event | Preserves critical context during session compaction. | -| **context-window-monitor** | Event | Monitors context window usage and tracks token consumption. | -| **preemptive-compaction** | Event | Proactively compacts sessions before hitting token limits. | +| Hook | Event | Description | +| ------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **directory-agents-injector** | PreToolUse + PostToolUse | Auto-injects AGENTS.md when reading files. Walks from file to project root, collecting all AGENTS.md files. Deprecated for OpenCode 1.1.37+ — Auto-disabled when native AGENTS.md injection is available. | +| **directory-readme-injector** | PreToolUse + PostToolUse | Auto-injects README.md for directory context. | +| **rules-injector** | PreToolUse + PostToolUse | Injects rules from `.claude/rules/` when conditions match. Supports globs and alwaysApply. | +| **compaction-context-injector** | Event | Preserves critical context during session compaction. | +| **context-window-monitor** | Event | Monitors context window usage and tracks token consumption. | +| **preemptive-compaction** | Event | Proactively compacts sessions before hitting token limits. | #### Productivity & Control -| Hook | Event | Description | -|------|-------|-------------| -| **keyword-detector** | Message + Transform | Detects keywords and activates modes: `ultrawork`/`ulw` (max performance), `search`/`find` (parallel exploration), `analyze`/`investigate` (deep analysis). | -| **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. | -| **auto-slash-command** | Message | Automatically executes slash commands from prompts. | -| **stop-continuation-guard** | Event + Message | Guards the stop-continuation mechanism. | -| **category-skill-reminder** | Event + PostToolUse | Reminds agents about available category skills for delegation. | -| **anthropic-effort** | Params | Adjusts Anthropic API effort level based on context. | +| Hook | Event | Description | +| --------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **keyword-detector** | Message + Transform | Detects keywords and activates modes: `ultrawork`/`ulw` (max performance), `search`/`find` (parallel exploration), `analyze`/`investigate` (deep analysis). | +| **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. | +| **auto-slash-command** | Message | Automatically executes slash commands from prompts. | +| **stop-continuation-guard** | Event + Message | Guards the stop-continuation mechanism. | +| **category-skill-reminder** | Event + PostToolUse | Reminds agents about available category skills for delegation. | +| **anthropic-effort** | Params | Adjusts Anthropic API effort level based on context. | #### Quality & Safety -| Hook | Event | Description | -|------|-------|-------------| -| **comment-checker** | PostToolUse | Reminds agents to reduce excessive comments. Smartly ignores BDD, directives, docstrings. | -| **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. | -| **hashline-read-enhancer** | PostToolUse | Enhances read output with hash-anchored line markers for the hashline edit tool. | -| **hashline-edit-diff-enhancer** | PreToolUse + PostToolUse | Enhances edit operations with diff markers for the hashline edit tool. | +| Hook | Event | Description | +| ------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------- | +| **comment-checker** | PostToolUse | Reminds agents to reduce excessive comments. Smartly ignores BDD, directives, docstrings. | +| **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. | +| **hashline-read-enhancer** | PostToolUse | Enhances read output with hash-anchored line markers for the hashline edit tool. | +| **hashline-edit-diff-enhancer** | PreToolUse + PostToolUse | Enhances edit operations with diff markers for the hashline edit tool. | #### Recovery & Stability -| Hook | Event | Description | -|------|-------|-------------| -| **session-recovery** | Event | Recovers from session errors — missing tool results, thinking block issues, empty messages. | -| **anthropic-context-window-limit-recovery** | Event | Handles Claude context window limits gracefully. | -| **runtime-fallback** | Event + Message | Automatically switches to backup models on retryable API errors (e.g., 429, 503, 529), provider key misconfiguration errors (e.g., missing API key), and auto-retry signals (when `timeout_seconds > 0`). Configurable retry logic with per-model cooldown. | -| **model-fallback** | Event + Message | Manages model fallback chain when primary model is unavailable. | -| **json-error-recovery** | PostToolUse | Recovers from JSON parse errors in tool outputs. | +| Hook | Event | Description | +| ------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **session-recovery** | Event | Recovers from session errors — missing tool results, thinking block issues, empty messages. | +| **anthropic-context-window-limit-recovery** | Event | Handles Claude context window limits gracefully. | +| **runtime-fallback** | Event + Message | Automatically switches to backup models on retryable API errors (e.g., 429, 503, 529), provider key misconfiguration errors (e.g., missing API key), and auto-retry signals (when `timeout_seconds > 0`). Configurable retry logic with per-model cooldown. | +| **model-fallback** | Event + Message | Manages model fallback chain when primary model is unavailable. | +| **json-error-recovery** | PostToolUse | Recovers from JSON parse errors in tool outputs. | #### Truncation & Context Management -| Hook | Event | Description | -|------|-------|-------------| +| Hook | Event | Description | +| ------------------------- | ----------- | --------------------------------------------------------------------------------------------------- | | **tool-output-truncator** | PostToolUse | Truncates output from Grep, Glob, LSP, AST-grep tools. Dynamically adjusts based on context window. | #### Notifications & UX -| Hook | Event | Description | -|------|-------|-------------| -| **auto-update-checker** | Event | Checks for new versions on session creation, shows startup toast with version and Sisyphus status. | -| **background-notification** | Event | Notifies when background agent tasks complete. | -| **session-notification** | Event | OS notifications when agents go idle. Works on macOS, Linux, Windows. | -| **agent-usage-reminder** | PostToolUse + Event | Reminds you to leverage specialized agents for better results. | -| **question-label-truncator** | PreToolUse | Truncates long question labels in the Question tool UI. | +| Hook | Event | Description | +| ---------------------------- | ------------------- | -------------------------------------------------------------------------------------------------- | +| **auto-update-checker** | Event | Checks for new versions on session creation, shows startup toast with version and Sisyphus status. | +| **background-notification** | Event | Notifies when background agent tasks complete. | +| **session-notification** | Event | OS notifications when agents go idle. Works on macOS, Linux, Windows. | +| **agent-usage-reminder** | PostToolUse + Event | Reminds you to leverage specialized agents for better results. | +| **question-label-truncator** | PreToolUse | Truncates long question labels in the Question tool UI. | #### Task Management -| Hook | Event | Description | -|------|-------|-------------| -| **task-resume-info** | PostToolUse | Provides task resume information for continuity. | -| **delegate-task-retry** | PostToolUse + Event | Retries failed task delegation calls. | -| **empty-task-response-detector** | PostToolUse | Detects empty responses from delegated tasks. | -| **tasks-todowrite-disabler** | PreToolUse | Disables TodoWrite tool when task system is active. | +| Hook | Event | Description | +| -------------------------------- | ------------------- | --------------------------------------------------- | +| **task-resume-info** | PostToolUse | Provides task resume information for continuity. | +| **delegate-task-retry** | PostToolUse + Event | Retries failed task delegation calls. | +| **empty-task-response-detector** | PostToolUse | Detects empty responses from delegated tasks. | +| **tasks-todowrite-disabler** | PreToolUse | Disables TodoWrite tool when task system is active. | #### Continuation -| Hook | Event | Description | -|------|-------|-------------| +| Hook | Event | Description | +| ------------------------------ | ----- | ---------------------------------------------------------- | | **todo-continuation-enforcer** | Event | Enforces todo completion — yanks idle agents back to work. | -| **compaction-todo-preserver** | Event | Preserves todo state during session compaction. | -| **unstable-agent-babysitter** | Event | Handles unstable agent behavior with recovery strategies. | +| **compaction-todo-preserver** | Event | Preserves todo state during session compaction. | +| **unstable-agent-babysitter** | Event | Handles unstable agent behavior with recovery strategies. | #### Integration -| Hook | Event | Description | -|------|-------|-------------| -| **claude-code-hooks** | All | Executes hooks from Claude Code's settings.json. | -| **atlas** | Multiple | Main orchestration logic for todo-driven work sessions. | -| **interactive-bash-session** | PostToolUse + Event | Manages tmux sessions for interactive CLI. | -| **non-interactive-env** | PreToolUse | Handles non-interactive environment constraints. | +| Hook | Event | Description | +| ---------------------------- | ------------------- | ------------------------------------------------------- | +| **claude-code-hooks** | All | Executes hooks from Claude Code's settings.json. | +| **atlas** | Multiple | Main orchestration logic for todo-driven work sessions. | +| **interactive-bash-session** | PostToolUse + Event | Manages tmux sessions for interactive CLI. | +| **non-interactive-env** | PreToolUse | Handles non-interactive environment constraints. | #### Specialized -| Hook | Event | Description | -|------|-------|-------------| -| **prometheus-md-only** | PreToolUse | Enforces markdown-only output for Prometheus planner. | -| **no-sisyphus-gpt** | Message | Prevents Sisyphus from running on incompatible GPT models. | -| **no-hephaestus-non-gpt** | Message | Prevents Hephaestus from running on non-GPT models. | -| **sisyphus-junior-notepad** | PreToolUse | Manages notepad state for Sisyphus-Junior agents. | +| Hook | Event | Description | +| --------------------------- | ---------- | ---------------------------------------------------------- | +| **prometheus-md-only** | PreToolUse | Enforces markdown-only output for Prometheus planner. | +| **no-sisyphus-gpt** | Message | Prevents Sisyphus from running on incompatible GPT models. | +| **no-hephaestus-non-gpt** | Message | Prevents Hephaestus from running on non-GPT models. | +| **sisyphus-junior-notepad** | PreToolUse | Manages notepad state for Sisyphus-Junior agents. | ### Claude Code Hooks Integration @@ -749,6 +774,7 @@ Run custom scripts via Claude Code's `settings.json`: ``` **Hook locations**: + - `~/.claude/settings.json` (user) - `./.claude/settings.json` (project) - `./.claude/settings.local.json` (local, git-ignored) @@ -759,10 +785,7 @@ Disable specific hooks in config: ```json { - "disabled_hooks": [ - "comment-checker", - "auto-update-checker" - ] + "disabled_hooks": ["comment-checker", "auto-update-checker"] } ``` @@ -770,11 +793,11 @@ Disable specific hooks in config: ### Built-in MCPs -| MCP | Description | -|-----|-------------| -| **websearch** | Real-time web search powered by Exa AI | -| **context7** | Official documentation lookup for any library/framework | -| **grep_app** | Ultra-fast code search across public GitHub repos. Great for finding implementation examples. | +| MCP | Description | +| ------------- | --------------------------------------------------------------------------------------------- | +| **websearch** | Real-time web search powered by Exa AI | +| **context7** | Official documentation lookup for any library/framework | +| **grep_app** | Ultra-fast code search across public GitHub repos. Great for finding implementation examples. | ### Skill-Embedded MCPs @@ -809,6 +832,7 @@ mcp: ``` When a skill MCP has `oauth` configured: + - **Auto-discovery**: Fetches `/.well-known/oauth-protected-resource` (RFC 9728), falls back to `/.well-known/oauth-authorization-server` (RFC 8414) - **Dynamic Client Registration**: Auto-registers with servers supporting RFC 7591 (clientId becomes optional) - **PKCE**: Mandatory for all flows @@ -848,11 +872,13 @@ Inject rules from `.claude/rules/` when conditions match: globs: ["*.ts", "src/**/*.js"] description: "TypeScript/JavaScript coding rules" --- + - Use PascalCase for interface names - Use camelCase for function names ``` Supports: + - `.md` and `.mdc` files - `globs` field for pattern matching - `alwaysApply: true` for unconditional rules @@ -864,12 +890,12 @@ Full compatibility layer for Claude Code configurations. ### Config Loaders -| Type | Locations | -|------|-----------| -| **Commands** | `~/.config/opencode/commands/`, `.claude/commands/` | -| **Skills** | `~/.config/opencode/skills/*/SKILL.md`, `.claude/skills/*/SKILL.md` | -| **Agents** | `~/.config/opencode/agents/*.md`, `.claude/agents/*.md` | -| **MCPs** | `~/.claude.json`, `~/.config/opencode/.mcp.json`, `.mcp.json`, `.claude/.mcp.json` | +| Type | Locations | +| ------------ | ---------------------------------------------------------------------------------- | +| **Commands** | `~/.config/opencode/commands/`, `.claude/commands/` | +| **Skills** | `~/.config/opencode/skills/*/SKILL.md`, `.claude/skills/*/SKILL.md` | +| **Agents** | `~/.config/opencode/agents/*.md`, `.claude/agents/*.md` | +| **MCPs** | `~/.claude.json`, `~/.config/opencode/.mcp.json`, `.mcp.json`, `.claude/.mcp.json` | MCP configs support environment variable expansion: `${VAR}`. @@ -890,14 +916,14 @@ Disable specific features: } ``` -| Toggle | Disables | -|--------|----------| -| `mcp` | `.mcp.json` files (keeps built-in MCPs) | -| `commands` | Command loading from Claude Code paths | -| `skills` | Skill loading from Claude Code paths | -| `agents` | Agent loading from Claude Code paths (keeps built-in agents) | -| `hooks` | settings.json hooks | -| `plugins` | Claude Code marketplace plugins | +| Toggle | Disables | +| ---------- | ------------------------------------------------------------ | +| `mcp` | `.mcp.json` files (keeps built-in MCPs) | +| `commands` | Command loading from Claude Code paths | +| `skills` | Skill loading from Claude Code paths | +| `agents` | Agent loading from Claude Code paths (keeps built-in agents) | +| `hooks` | settings.json hooks | +| `plugins` | Claude Code marketplace plugins | Disable specific plugins: