From 29ffdccbe687fe35609f5b58a66610f138170fb4 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Mon, 5 Jan 2026 13:52:30 +0900 Subject: [PATCH] docs: update documentation for Prometheus and new features MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update documentation across all language versions: - Rename Planner-Sisyphus to Prometheus (Planner) - Add Metis (Plan Consultant) agent documentation - Add Categories section with usage examples - Add sisyphus_task tool documentation - Update AGENTS.md with new structure and complexity hotspots - Update src/tools/AGENTS.md with sisyphus_task category 🤖 GENERATED WITH ASSISTANCE OF [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode) --- AGENTS.md | 99 +++++++++++++++++++++++++++++++-------------- README.ja.md | 12 ++++-- README.md | 66 ++++++++++++++++++++++++++---- README.zh-cn.md | 12 ++++-- src/tools/AGENTS.md | 79 +++++++++++++++++++++--------------- 5 files changed, 190 insertions(+), 78 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bc06684f..1e27efd9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,16 +6,16 @@ ## OVERVIEW -OpenCode plugin: multi-model agent orchestration (Claude Opus 4.5, GPT-5.2, Gemini 3, Grok), 11 LSP tools, AST-Grep, Claude Code compatibility layer. "oh-my-zsh" for OpenCode. +OpenCode plugin implementing Claude Code/AmpCode features. Multi-model agent orchestration (GPT-5.2, Claude, Gemini, Grok), LSP tools (11), AST-Grep search, MCP integrations (context7, websearch_exa, grep_app). "oh-my-zsh" for OpenCode. ## STRUCTURE ``` oh-my-opencode/ ├── src/ -│ ├── agents/ # 7 AI agents - see src/agents/AGENTS.md +│ ├── agents/ # AI agents (7): Sisyphus, oracle, librarian, explore, frontend, document-writer, multimodal-looker │ ├── hooks/ # 22 lifecycle hooks - see src/hooks/AGENTS.md -│ ├── tools/ # LSP, AST-Grep, session mgmt - see src/tools/AGENTS.md +│ ├── tools/ # LSP, AST-Grep, Grep, Glob, session mgmt - see src/tools/AGENTS.md │ ├── features/ # Claude Code compat layer - see src/features/AGENTS.md │ ├── auth/ # Google Antigravity OAuth - see src/auth/AGENTS.md │ ├── shared/ # Cross-cutting utilities - see src/shared/AGENTS.md @@ -24,6 +24,7 @@ oh-my-opencode/ │ ├── config/ # Zod schema, TypeScript types │ └── index.ts # Main plugin entry (464 lines) ├── script/ # build-schema.ts, publish.ts, generate-changelog.ts +├── assets/ # JSON schema └── dist/ # Build output (ESM + .d.ts) ``` @@ -31,13 +32,24 @@ oh-my-opencode/ | Task | Location | Notes | |------|----------|-------| -| Add agent | `src/agents/` | Create .ts, add to builtinAgents, update types.ts | -| Add hook | `src/hooks/` | Dir with createXXXHook(), export from index.ts | -| Add tool | `src/tools/` | Dir with constants/types/tools.ts, add to builtinTools | -| Add MCP | `src/mcp/` | Create config, add to index.ts | -| Add skill | `src/features/builtin-skills/` | Dir with SKILL.md | -| Config schema | `src/config/schema.ts` | Run `bun run build:schema` after | +| Add agent | `src/agents/` | Create .ts, add to builtinAgents in index.ts, update types.ts | +| Add hook | `src/hooks/` | Create dir with createXXXHook(), export from index.ts | +| Add tool | `src/tools/` | Dir with index/types/constants/tools.ts, add to builtinTools | +| Add MCP | `src/mcp/` | Create config, add to index.ts and types.ts | +| Add skill | `src/features/builtin-skills/` | Create skill dir with SKILL.md | +| LSP behavior | `src/tools/lsp/` | client.ts (connection), tools.ts (handlers) | +| AST-Grep | `src/tools/ast-grep/` | napi.ts for @ast-grep/napi binding | +| Google OAuth | `src/auth/antigravity/` | OAuth plugin for Google/Gemini models | +| Config schema | `src/config/schema.ts` | Zod schema, run `bun run build:schema` after changes | | Claude Code compat | `src/features/claude-code-*-loader/` | Command, skill, agent, mcp loaders | +| Background agents | `src/features/background-agent/` | manager.ts for task management | +| Skill MCP | `src/features/skill-mcp-manager/` | MCP servers embedded in skills | +| Interactive terminal | `src/tools/interactive-bash/` | tmux session management | +| CLI installer | `src/cli/install.ts` | Interactive TUI installation | +| Doctor checks | `src/cli/doctor/checks/` | Health checks for environment | +| Shared utilities | `src/shared/` | Cross-cutting utilities | +| Slash commands | `src/hooks/auto-slash-command/` | Auto-detect and execute `/command` patterns | +| Ralph Loop | `src/hooks/ralph-loop/` | Self-referential dev loop until completion | ## TDD (Test-Driven Development) @@ -64,7 +76,7 @@ oh-my-opencode/ ## CONVENTIONS -- **Bun only**: `bun run`, `bun test`, `bunx` (NEVER npm/npx) +- **Package manager**: Bun only (`bun run`, `bun build`, `bunx`) - **Types**: bun-types (not @types/node) - **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly` - **Exports**: Barrel pattern in index.ts; explicit named exports for tools/hooks @@ -72,26 +84,41 @@ oh-my-opencode/ - **Testing**: BDD comments `#given`, `#when`, `#then` (same as AAA); TDD workflow (RED-GREEN-REFACTOR) - **Temperature**: 0.1 for code agents, max 0.3 -## ANTI-PATTERNS +## ANTI-PATTERNS (THIS PROJECT) -| Category | Forbidden | -|----------|-----------| -| Type Safety | `as any`, `@ts-ignore`, `@ts-expect-error` | -| Package Manager | npm, yarn, npx | -| File Ops | Bash mkdir/touch/rm for code file creation | -| Publishing | Direct `bun publish`, local version bump | -| Agent Behavior | High temp (>0.3), broad tool access, sequential agent calls | -| Hooks | Heavy PreToolUse logic, blocking without reason | -| Year | 2024 in code/prompts (use current year) | +- **npm/yarn**: Use bun exclusively +- **@types/node**: Use bun-types +- **Bash file ops**: Never mkdir/touch/rm/cp/mv for file creation in code +- **Direct bun publish**: GitHub Actions workflow_dispatch only (OIDC provenance) +- **Local version bump**: Version managed by CI workflow +- **Year 2024**: NEVER use 2024 in code/prompts (use current year) +- **Rush completion**: Never mark tasks complete without verification +- **Over-exploration**: Stop searching when sufficient context found +- **High temperature**: Don't use >0.3 for code-related agents +- **Broad tool access**: Prefer explicit `include` over unrestricted access +- **Sequential agent calls**: Use `sisyphus_task` for parallel execution +- **Heavy PreToolUse logic**: Slows every tool call +- **Self-planning for complex tasks**: Spawn planning agent (Prometheus) instead + +## UNIQUE STYLES + +- **Platform**: Union type `"darwin" | "linux" | "win32" | "unsupported"` +- **Optional props**: Extensive `?` for optional interface properties +- **Flexible objects**: `Record` for dynamic configs +- **Error handling**: Consistent try/catch with async/await +- **Agent tools**: `tools: { include: [...] }` or `tools: { exclude: [...] }` +- **Temperature**: Most agents use `0.1` for consistency +- **Hook naming**: `createXXXHook` function convention +- **Factory pattern**: Components created via `createXXX()` functions ## AGENT MODELS | Agent | Default Model | Purpose | |-------|-------|---------| | Sisyphus | anthropic/claude-opus-4-5 | Primary orchestrator | -| oracle | openai/gpt-5.2 | Strategy, code review | -| librarian | anthropic/claude-sonnet-4-5 | Docs, OSS research | -| explore | opencode/grok-code | Fast codebase grep | +| oracle | openai/gpt-5.2 | Strategic advisor, code review | +| librarian | anthropic/claude-sonnet-4-5 | Multi-repo analysis, docs | +| explore | opencode/grok-code | Fast codebase exploration | | frontend-ui-ux-engineer | google/gemini-3-pro-preview | UI generation | | document-writer | google/gemini-3-pro-preview | Technical docs | | multimodal-looker | google/gemini-3-flash | PDF/image analysis | @@ -102,7 +129,8 @@ oh-my-opencode/ bun run typecheck # Type check bun run build # ESM + declarations + schema bun run rebuild # Clean + Build -bun test # Run tests (380+) +bun run build:schema # Schema only +bun test # Run tests ``` ## DEPLOYMENT @@ -110,10 +138,16 @@ bun test # Run tests (380+) **GitHub Actions workflow_dispatch only** 1. Never modify package.json version locally -2. Commit & push to dev -3. Trigger: `gh workflow run publish -f bump=patch|minor|major` +2. Commit & push changes +3. Trigger `publish` workflow: `gh workflow run publish -f bump=patch` -CI auto-commits schema changes on master, maintains rolling `next` draft release on dev. +**Critical**: Never `bun publish` directly. Never bump version locally. + +## CI PIPELINE + +- **ci.yml**: Parallel test/typecheck, build verification, auto-commit schema on master, rolling `next` draft release +- **publish.yml**: Manual workflow_dispatch, version bump, changelog, OIDC npm publish +- **sisyphus-agent.yml**: Agent-in-CI for automated issue handling via `@sisyphus-dev-ai` mentions ## COMPLEXITY HOTSPOTS @@ -123,13 +157,18 @@ CI auto-commits schema changes on master, maintains rolling `next` draft release | `src/cli/config-manager.ts` | 669 | JSONC parsing, env detection | | `src/auth/antigravity/fetch.ts` | 621 | Token refresh, URL rewriting | | `src/tools/lsp/client.ts` | 611 | LSP protocol, JSON-RPC | +| `src/auth/antigravity/response.ts` | 598 | Response transformation, streaming | +| `src/auth/antigravity/thinking.ts` | 571 | Thinking block extraction/transformation | | `src/hooks/anthropic-context-window-limit-recovery/executor.ts` | 564 | Multi-stage recovery | | `src/agents/sisyphus.ts` | 504 | Orchestrator prompt | ## NOTES +- **Testing**: Bun native test (`bun test`), BDD-style `#given/#when/#then`, 360+ tests - **OpenCode**: Requires >= 1.0.150 -- **Config**: `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json` -- **JSONC**: Config files support comments and trailing commas -- **Claude Code**: Full compat layer for settings.json hooks, commands, skills, agents, MCPs +- **Multi-lang docs**: README.md (EN), README.ko.md (KO), README.ja.md (JA), README.zh-cn.md (ZH-CN) +- **Config**: `~/.config/opencode/oh-my-opencode.json` (user) or `.opencode/oh-my-opencode.json` (project) +- **Trusted deps**: @ast-grep/cli, @ast-grep/napi, @code-yeongyu/comment-checker +- **JSONC support**: Config files support comments (`// comment`, `/* block */`) and trailing commas +- **Claude Code Compat**: Full compatibility layer for settings.json hooks, commands, skills, agents, MCPs - **Skill MCP**: Skills can embed MCP server configs in YAML frontmatter diff --git a/README.ja.md b/README.ja.md index 162efc41..b14c3026 100644 --- a/README.ja.md +++ b/README.ja.md @@ -862,7 +862,8 @@ Oh My OpenCode は以下の場所からフックを読み込んで実行しま - **Sisyphus**: プライマリオーケストレーターエージェント (Claude Opus 4.5) - **OpenCode-Builder**: OpenCode のデフォルトビルドエージェント（SDK 制限により名前変更、デフォルトで無効） -- **Planner-Sisyphus**: OpenCode のデフォルトプランエージェント（SDK 制限により名前変更、デフォルトで有効） +- **Prometheus (Planner)**: OpenCode のデフォルトプランエージェント + work-planner 方法論（デフォルトで有効） +- **Metis (Plan Consultant)**: 隠された要件と AI 失敗ポイントを特定する事前計画分析エージェント **設定オプション：** @@ -911,8 +912,11 @@ Oh My OpenCode は以下の場所からフックを読み込んで実行しま "OpenCode-Builder": { "model": "anthropic/claude-opus-4" }, - "Planner-Sisyphus": { + "Prometheus (Planner)": { "model": "openai/gpt-5.2" + }, + "Metis (Plan Consultant)": { + "model": "anthropic/claude-sonnet-4-5" } } } @@ -922,8 +926,8 @@ Oh My OpenCode は以下の場所からフックを読み込んで実行しま | --------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `disabled` | `false` | `true` の場合、すべての Sisyphus オーケストレーションを無効化し、元の build/plan をプライマリとして復元します。 | | `default_builder_enabled` | `false` | `true` の場合、OpenCode-Builder エージェントを有効化します（OpenCode build と同じ、SDK 制限により名前変更）。デフォルトでは無効です。 | -| `planner_enabled` | `true` | `true` の場合、Planner-Sisyphus エージェントを有効化します（OpenCode plan と同じ、SDK 制限により名前変更）。デフォルトで有効です。 | -| `replace_plan` | `true` | `true` の場合、デフォルトのプランエージェントをサブエージェントモードに降格させます。`false` に設定すると、Planner-Sisyphus とデフォルトのプランの両方を利用できます。 | +| `planner_enabled` | `true` | `true` の場合、Prometheus (Planner) エージェントを有効化します（work-planner 方法論を含む）。デフォルトで有効です。 | +| `replace_plan` | `true` | `true` の場合、デフォルトのプランエージェントをサブエージェントモードに降格させます。`false` に設定すると、Prometheus (Planner) とデフォルトのプランの両方を利用できます。 | ### Background Tasks diff --git a/README.md b/README.md index 391fffed..40bd45e1 100644 --- a/README.md +++ b/README.md @@ -127,6 +127,7 @@ No stupid token consumption massive subagents here. No bloat tools here. - [Built-in Skills](#built-in-skills) - [Sisyphus Agent](#sisyphus-agent) - [Background Tasks](#background-tasks) + - [Categories](#categories) - [Hooks](#hooks) - [MCPs](#mcps) - [LSP](#lsp) @@ -553,6 +554,7 @@ Hand your best tools to your best colleagues. Now they can properly refactor, na - **ast_grep_search**: AST-aware code pattern search (25 languages) - **ast_grep_replace**: AST-aware code replacement - **call_omo_agent**: Spawn specialized explore/librarian agents. Supports `run_in_background` parameter for async execution. +- **sisyphus_task**: Category-based task delegation with specialized agents. Supports pre-configured categories (visual, business-logic) or direct agent targeting. Use `background_output` to retrieve results and `background_cancel` to cancel tasks. See [Categories](#categories). #### Session Management @@ -932,7 +934,8 @@ When enabled (default), Sisyphus provides a powerful orchestrator with optional - **Sisyphus**: Primary orchestrator agent (Claude Opus 4.5) - **OpenCode-Builder**: OpenCode's default build agent, renamed due to SDK limitations (disabled by default) -- **Planner-Sisyphus**: OpenCode's default plan agent, renamed due to SDK limitations (enabled by default) +- **Prometheus (Planner)**: OpenCode's default plan agent with work-planner methodology (enabled by default) +- **Metis (Plan Consultant)**: Pre-planning analysis agent that identifies hidden requirements and AI failure points **Configuration Options:** @@ -981,19 +984,22 @@ You can also customize Sisyphus agents like other agents: "OpenCode-Builder": { "model": "anthropic/claude-opus-4" }, - "Planner-Sisyphus": { + "Prometheus (Planner)": { "model": "openai/gpt-5.2" + }, + "Metis (Plan Consultant)": { + "model": "anthropic/claude-sonnet-4-5" } } } ``` -| Option | Default | Description | -| ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `disabled` | `false` | When `true`, disables all Sisyphus orchestration and restores original build/plan as primary. | -| `default_builder_enabled` | `false` | When `true`, enables OpenCode-Builder agent (same as OpenCode build, renamed due to SDK limitations). Disabled by default. | -| `planner_enabled` | `true` | When `true`, enables Planner-Sisyphus agent (same as OpenCode plan, renamed due to SDK limitations). Enabled by default. | -| `replace_plan` | `true` | When `true`, demotes default plan agent to subagent mode. Set to `false` to keep both Planner-Sisyphus and default plan available. | +| Option | Default | Description | +| --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| `disabled` | `false` | When `true`, disables all Sisyphus orchestration and restores original build/plan as primary. | +| `default_builder_enabled` | `false` | When `true`, enables OpenCode-Builder agent (same as OpenCode build, renamed due to SDK limitations). Disabled by default. | +| `planner_enabled` | `true` | When `true`, enables Prometheus (Planner) agent with work-planner methodology. Enabled by default. | +| `replace_plan` | `true` | When `true`, demotes default plan agent to subagent mode. Set to `false` to keep both Prometheus (Planner) and default plan available. | ### Background Tasks @@ -1029,6 +1035,50 @@ Configure concurrency limits for background agent tasks. This controls how many - Allow more concurrent tasks for fast/cheap models (e.g., Gemini Flash) - Respect provider rate limits by setting provider-level caps +### Categories + +Categories enable domain-specific task delegation via the `sisyphus_task` tool. Each category pre-configures a specialized `Sisyphus-Junior-{category}` agent with optimized model settings and prompts. + +**Default Categories:** + +| Category | Model | Description | +|----------|-------|-------------| +| `visual` | `google/gemini-3-pro-preview` | Frontend, UI/UX, design-focused tasks. High creativity (temp 0.7). | +| `business-logic` | `openai/gpt-5.2` | Backend logic, architecture, strategic reasoning. Low creativity (temp 0.1). | + +**Usage:** + +``` +// Via sisyphus_task tool +sisyphus_task(category="visual", prompt="Create a responsive dashboard component") +sisyphus_task(category="business-logic", prompt="Design the payment processing flow") + +// Or target a specific agent directly +sisyphus_task(agent="oracle", prompt="Review this architecture") +``` + +**Custom Categories:** + +Add custom categories in `oh-my-opencode.json`: + +```json +{ + "categories": { + "data-science": { + "model": "anthropic/claude-sonnet-4-5", + "temperature": 0.2, + "prompt_append": "Focus on data analysis, ML pipelines, and statistical methods." + }, + "visual": { + "model": "google/gemini-3-pro-high", + "prompt_append": "Use shadcn/ui components and Tailwind CSS." + } + } +} +``` + +Each category supports: `model`, `temperature`, `top_p`, `maxTokens`, `thinking`, `reasoningEffort`, `textVerbosity`, `tools`, `prompt_append`. + ### Hooks Disable specific built-in hooks via `disabled_hooks` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`: diff --git a/README.zh-cn.md b/README.zh-cn.md index f4b42e04..185cd3e2 100644 --- a/README.zh-cn.md +++ b/README.zh-cn.md @@ -863,7 +863,8 @@ Agent 爽了，你自然也爽。但我还想直接让你爽。 - **Sisyphus**：主编排 Agent（Claude Opus 4.5） - **OpenCode-Builder**：OpenCode 默认构建 Agent（因 SDK 限制仅改名，默认禁用） -- **Planner-Sisyphus**：OpenCode 默认计划 Agent（因 SDK 限制仅改名，默认启用） +- **Prometheus (Planner)**：OpenCode 默认计划 Agent + work-planner 方法论（默认启用） +- **Metis (Plan Consultant)**：识别隐藏需求和 AI 失败点的预规划分析 Agent **配置选项：** @@ -912,8 +913,11 @@ Sisyphus Agent 也能自定义： "OpenCode-Builder": { "model": "anthropic/claude-opus-4" }, - "Planner-Sisyphus": { + "Prometheus (Planner)": { "model": "openai/gpt-5.2" + }, + "Metis (Plan Consultant)": { + "model": "anthropic/claude-sonnet-4-5" } } } @@ -923,8 +927,8 @@ Sisyphus Agent 也能自定义： | --------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `disabled` | `false` | 设为 `true` 就禁用所有 Sisyphus 编排，恢复原来的 build/plan。 | | `default_builder_enabled` | `false` | 设为 `true` 就启用 OpenCode-Builder Agent（与 OpenCode build 相同，因 SDK 限制仅改名）。默认禁用。 | -| `planner_enabled` | `true` | 设为 `true` 就启用 Planner-Sisyphus Agent（与 OpenCode plan 相同，因 SDK 限制仅改名）。默认启用。 | -| `replace_plan` | `true` | 设为 `true` 就把默认计划 Agent 降级为子 Agent 模式。设为 `false` 可以同时保留 Planner-Sisyphus 和默认计划。 | +| `planner_enabled` | `true` | 设为 `true` 就启用 Prometheus (Planner) Agent（含 work-planner 方法论）。默认启用。 | +| `replace_plan` | `true` | 设为 `true` 就把默认计划 Agent 降级为子 Agent 模式。设为 `false` 可以同时保留 Prometheus (Planner) 和默认计划。 | ### Background Tasks（后台任务） diff --git a/src/tools/AGENTS.md b/src/tools/AGENTS.md index 5d9595af..cd79d1c5 100644 --- a/src/tools/AGENTS.md +++ b/src/tools/AGENTS.md @@ -2,26 +2,33 @@ ## OVERVIEW -Custom tools: 11 LSP tools, AST-aware search/replace, file ops with timeouts, background task management, session navigation. +Custom tools extending agent capabilities: LSP integration (11 tools), AST-aware code search/replace, file operations with timeouts, background task management. ## STRUCTURE ``` tools/ ├── ast-grep/ # AST-aware code search/replace (25 languages) -│ ├── napi.ts # @ast-grep/napi binding (preferred) -│ └── cli.ts # @ast-grep/cli fallback +│ ├── cli.ts # @ast-grep/cli subprocess +│ ├── napi.ts # @ast-grep/napi native binding (preferred) +│ ├── constants.ts, types.ts, tools.ts, utils.ts ├── background-task/ # Async agent task management ├── call-omo-agent/ # Spawn explore/librarian agents -├── glob/ # File pattern matching (60s timeout) -├── grep/ # Content search (60s timeout) +├── glob/ # File pattern matching (timeout-safe) +├── grep/ # Content search (timeout-safe) ├── interactive-bash/ # Tmux session management ├── look-at/ # Multimodal analysis (PDF, images) -├── lsp/ # 11 LSP tools (611 lines client.ts) +├── lsp/ # 11 LSP tools │ ├── client.ts # LSP connection lifecycle │ ├── config.ts # Server configurations +│ ├── tools.ts # Tool implementations +│ └── types.ts +├── session-manager/ # OpenCode session file management +│ ├── constants.ts # Storage paths, descriptions +│ ├── types.ts # Session data interfaces +│ ├── storage.ts # File I/O operations +│ ├── utils.ts # Formatting, filtering │ └── tools.ts # Tool implementations -├── session-manager/ # OpenCode session file ops ├── skill/ # Skill loading and execution ├── skill-mcp/ # Skill-embedded MCP invocation ├── slashcommand/ # Slash command execution @@ -30,39 +37,47 @@ tools/ ## TOOL CATEGORIES -| Category | Tools | -|----------|-------| -| LSP | lsp_hover, lsp_goto_definition, lsp_find_references, lsp_document_symbols, lsp_workspace_symbols, lsp_diagnostics, lsp_servers, lsp_prepare_rename, lsp_rename, lsp_code_actions, lsp_code_action_resolve | -| AST | ast_grep_search, ast_grep_replace | -| File Search | grep, glob | -| Session | session_list, session_read, session_search, session_info | -| Background | background_task, background_output, background_cancel | -| Multimodal | look_at | -| Terminal | interactive_bash | -| Skills | skill, skill_mcp | -| Agents | call_omo_agent | +| Category | Tools | Purpose | +|----------|-------|---------| +| LSP | lsp_hover, lsp_goto_definition, lsp_find_references, lsp_document_symbols, lsp_workspace_symbols, lsp_diagnostics, lsp_servers, lsp_prepare_rename, lsp_rename, lsp_code_actions, lsp_code_action_resolve | IDE-like code intelligence | +| AST | ast_grep_search, ast_grep_replace | Pattern-based code search/replace | +| File Search | grep, glob | Content and file pattern matching | +| Session | session_list, session_read, session_search, session_info | OpenCode session file management | +| Background | sisyphus_task, background_output, background_cancel | Async agent orchestration | +| Multimodal | look_at | PDF/image analysis via Gemini | +| Terminal | interactive_bash | Tmux session control | +| Commands | slashcommand | Execute slash commands | +| Skills | skill, skill_mcp | Load skills, invoke skill-embedded MCPs | +| Agents | call_omo_agent | Spawn explore/librarian | -## HOW TO ADD +## HOW TO ADD A TOOL -1. Create `src/tools/my-tool/` -2. Files: `constants.ts`, `types.ts`, `tools.ts`, `index.ts` +1. Create directory: `src/tools/my-tool/` +2. Create files: + - `constants.ts`: `TOOL_NAME`, `TOOL_DESCRIPTION` + - `types.ts`: Parameter/result interfaces + - `tools.ts`: Tool implementation (returns OpenCode tool object) + - `index.ts`: Barrel export + - `utils.ts`: Helpers (optional) 3. Add to `builtinTools` in `src/tools/index.ts` ## LSP SPECIFICS -- Lazy init on first use, auto-shutdown on idle -- Config priority: opencode.json > oh-my-opencode.json > defaults -- Servers: typescript-language-server, pylsp, gopls, rust-analyzer +- **Client lifecycle**: Lazy init on first use, auto-shutdown on idle +- **Config priority**: opencode.json > oh-my-opencode.json > defaults +- **Supported servers**: typescript-language-server, pylsp, gopls, rust-analyzer, etc. +- **Custom servers**: Add via `lsp` config in oh-my-opencode.json ## AST-GREP SPECIFICS -- Meta-variables: `$VAR` (single), `$$$` (multiple) -- Pattern must be valid AST node, not fragment -- Prefers napi binding for performance +- **Meta-variables**: `$VAR` (single node), `$$$` (multiple nodes) +- **Languages**: 25 supported (typescript, tsx, python, rust, go, etc.) +- **Binding**: Prefers @ast-grep/napi (native), falls back to @ast-grep/cli +- **Pattern must be valid AST**: `export async function $NAME($$$) { $$$ }` not fragments -## ANTI-PATTERNS +## ANTI-PATTERNS (TOOLS) -- No timeout on file ops (always use, default 60s) -- Sync file operations (use async/await) -- Ignoring LSP errors (graceful handling required) -- Raw subprocess for ast-grep (prefer napi) +- **No timeout**: Always use timeout for file operations (default 60s) +- **Blocking main thread**: Use async/await, never sync file ops +- **Ignoring LSP errors**: Gracefully handle server not found/crashed +- **Raw subprocess for ast-grep**: Prefer napi binding for performance