elias/oh-my-opencode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update documentation for Prometheus and new features

Browse Source 
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)
This commit is contained in:
YeonGyu-Kim 2026-01-05 13:52:30 +09:00
parent b9b8adc11c
commit 29ffdccbe6
5 changed files with 190 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
AGENTS.md
View File

@ -6,16 +6,16 @@
## OVERVIEW ## 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 ## STRUCTURE
``` ```
oh-my-opencode/ oh-my-opencode/
├── src/ ├── 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 │ ├── 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 │ ├── features/ # Claude Code compat layer - see src/features/AGENTS.md
│ ├── auth/ # Google Antigravity OAuth - see src/auth/AGENTS.md │ ├── auth/ # Google Antigravity OAuth - see src/auth/AGENTS.md
│ ├── shared/ # Cross-cutting utilities - see src/shared/AGENTS.md │ ├── shared/ # Cross-cutting utilities - see src/shared/AGENTS.md
@ -24,6 +24,7 @@ oh-my-opencode/
│ ├── config/ # Zod schema, TypeScript types │ ├── config/ # Zod schema, TypeScript types
│ └── index.ts # Main plugin entry (464 lines) │ └── index.ts # Main plugin entry (464 lines)
├── script/ # build-schema.ts, publish.ts, generate-changelog.ts ├── script/ # build-schema.ts, publish.ts, generate-changelog.ts
├── assets/ # JSON schema
└── dist/ # Build output (ESM + .d.ts) └── dist/ # Build output (ESM + .d.ts)
``` ```
@ -31,13 +32,24 @@ oh-my-opencode/
| Task | Location | Notes | | Task | Location | Notes |
|------|----------|-------| |------|----------|-------|
| Add agent | `src/agents/` | Create .ts, add to builtinAgents, update types.ts | | Add agent | `src/agents/` | Create .ts, add to builtinAgents in index.ts, update types.ts |
| Add hook | `src/hooks/` | Dir with createXXXHook(), export from index.ts | | Add hook | `src/hooks/` | Create dir with createXXXHook(), export from index.ts |
| Add tool | `src/tools/` | Dir with constants/types/tools.ts, add to builtinTools | | Add tool | `src/tools/` | Dir with index/types/constants/tools.ts, add to builtinTools |
| Add MCP | `src/mcp/` | Create config, add to index.ts | | Add MCP | `src/mcp/` | Create config, add to index.ts and types.ts |
| Add skill | `src/features/builtin-skills/` | Dir with SKILL.md | | Add skill | `src/features/builtin-skills/` | Create skill dir with SKILL.md |
| Config schema | `src/config/schema.ts` | Run `bun run build:schema` after | | 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 | | 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) ## TDD (Test-Driven Development)
@ -64,7 +76,7 @@ oh-my-opencode/
## CONVENTIONS ## 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) - **Types**: bun-types (not @types/node)
- **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly` - **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly`
- **Exports**: Barrel pattern in index.ts; explicit named exports for tools/hooks - **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) - **Testing**: BDD comments `#given`, `#when`, `#then` (same as AAA); TDD workflow (RED-GREEN-REFACTOR)
- **Temperature**: 0.1 for code agents, max 0.3 - **Temperature**: 0.1 for code agents, max 0.3
## ANTI-PATTERNS ## ANTI-PATTERNS (THIS PROJECT)
| Category | Forbidden | - **npm/yarn**: Use bun exclusively
|----------|-----------| - **@types/node**: Use bun-types
| Type Safety | `as any`, `@ts-ignore`, `@ts-expect-error` | - **Bash file ops**: Never mkdir/touch/rm/cp/mv for file creation in code
| Package Manager | npm, yarn, npx | - **Direct bun publish**: GitHub Actions workflow_dispatch only (OIDC provenance)
| File Ops | Bash mkdir/touch/rm for code file creation | - **Local version bump**: Version managed by CI workflow
| Publishing | Direct `bun publish`, local version bump | - **Year 2024**: NEVER use 2024 in code/prompts (use current year)
| Agent Behavior | High temp (>0.3), broad tool access, sequential agent calls | - **Rush completion**: Never mark tasks complete without verification
| Hooks | Heavy PreToolUse logic, blocking without reason | - **Over-exploration**: Stop searching when sufficient context found
| Year | 2024 in code/prompts (use current year) | - **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<string, unknown>` 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 MODELS
| Agent | Default Model | Purpose | | Agent | Default Model | Purpose |
|-------|-------|---------| |-------|-------|---------|
| Sisyphus | anthropic/claude-opus-4-5 | Primary orchestrator | | Sisyphus | anthropic/claude-opus-4-5 | Primary orchestrator |
| oracle | openai/gpt-5.2 | Strategy, code review | | oracle | openai/gpt-5.2 | Strategic advisor, code review |
| librarian | anthropic/claude-sonnet-4-5 | Docs, OSS research | | librarian | anthropic/claude-sonnet-4-5 | Multi-repo analysis, docs |
| explore | opencode/grok-code | Fast codebase grep | | explore | opencode/grok-code | Fast codebase exploration |
| frontend-ui-ux-engineer | google/gemini-3-pro-preview | UI generation | | frontend-ui-ux-engineer | google/gemini-3-pro-preview | UI generation |
| document-writer | google/gemini-3-pro-preview | Technical docs | | document-writer | google/gemini-3-pro-preview | Technical docs |
| multimodal-looker | google/gemini-3-flash | PDF/image analysis | | multimodal-looker | google/gemini-3-flash | PDF/image analysis |
@ -102,7 +129,8 @@ oh-my-opencode/
bun run typecheck # Type check bun run typecheck # Type check
bun run build # ESM + declarations + schema bun run build # ESM + declarations + schema
bun run rebuild # Clean + Build bun run rebuild # Clean + Build
bun test # Run tests (380+) bun run build:schema # Schema only
bun test # Run tests
``` ```
## DEPLOYMENT ## DEPLOYMENT
@ -110,10 +138,16 @@ bun test # Run tests (380+)
**GitHub Actions workflow_dispatch only** **GitHub Actions workflow_dispatch only**
1. Never modify package.json version locally 1. Never modify package.json version locally
2. Commit & push to dev 2. Commit & push changes
3. Trigger: `gh workflow run publish -f bump=patch|minor|major` 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 ## 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/cli/config-manager.ts` | 669 | JSONC parsing, env detection |
| `src/auth/antigravity/fetch.ts` | 621 | Token refresh, URL rewriting | | `src/auth/antigravity/fetch.ts` | 621 | Token refresh, URL rewriting |
| `src/tools/lsp/client.ts` | 611 | LSP protocol, JSON-RPC | | `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/hooks/anthropic-context-window-limit-recovery/executor.ts` | 564 | Multi-stage recovery |
| `src/agents/sisyphus.ts` | 504 | Orchestrator prompt | | `src/agents/sisyphus.ts` | 504 | Orchestrator prompt |
## NOTES ## NOTES
- **Testing**: Bun native test (`bun test`), BDD-style `#given/#when/#then`, 360+ tests
- **OpenCode**: Requires >= 1.0.150 - **OpenCode**: Requires >= 1.0.150
- **Config**: `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json` - **Multi-lang docs**: README.md (EN), README.ko.md (KO), README.ja.md (JA), README.zh-cn.md (ZH-CN)
- **JSONC**: Config files support comments and trailing commas - **Config**: `~/.config/opencode/oh-my-opencode.json` (user) or `.opencode/oh-my-opencode.json` (project)
- **Claude Code**: Full compat layer for settings.json hooks, commands, skills, agents, MCPs - **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 - **Skill MCP**: Skills can embed MCP server configs in YAML frontmatter

12
README.ja.md
View File

@ -862,7 +862,8 @@ Oh My OpenCode は以下の場所からフックを読み込んで実行しま
- **Sisyphus**: プライマリオーケストレーターエージェント (Claude Opus 4.5) - **Sisyphus**: プライマリオーケストレーターエージェント (Claude Opus 4.5)
- **OpenCode-Builder**: OpenCode のデフォルトビルドエージェント（SDK 制限により名前変更、デフォルトで無効） - **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": { "OpenCode-Builder": {
"model": "anthropic/claude-opus-4" "model": "anthropic/claude-opus-4"
}, },
"Planner-Sisyphus": { "Prometheus (Planner)": {
"model": "openai/gpt-5.2" "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 をプライマリとして復元します。 | | `disabled` | `false` | `true` の場合、すべての Sisyphus オーケストレーションを無効化し、元の build/plan をプライマリとして復元します。 |
| `default_builder_enabled` | `false` | `true` の場合、OpenCode-Builder エージェントを有効化します（OpenCode build と同じ、SDK 制限により名前変更）。デフォルトでは無効です。 | | `default_builder_enabled` | `false` | `true` の場合、OpenCode-Builder エージェントを有効化します（OpenCode build と同じ、SDK 制限により名前変更）。デフォルトでは無効です。 |
| `planner_enabled` | `true` | `true` の場合、Planner-Sisyphus エージェントを有効化します（OpenCode plan と同じ、SDK 制限により名前変更）。デフォルトで有効です。 | | `planner_enabled` | `true` | `true` の場合、Prometheus (Planner) エージェントを有効化します（work-planner 方法論を含む）。デフォルトで有効です。 |
| `replace_plan` | `true` | `true` の場合、デフォルトのプランエージェントをサブエージェントモードに降格させます。`false` に設定すると、Planner-Sisyphus とデフォルトのプランの両方を利用できます。 | | `replace_plan` | `true` | `true` の場合、デフォルトのプランエージェントをサブエージェントモードに降格させます。`false` に設定すると、Prometheus (Planner) とデフォルトのプランの両方を利用できます。 |
### Background Tasks ### Background Tasks

66
README.md
View File

@ -127,6 +127,7 @@ No stupid token consumption massive subagents here. No bloat tools here.
- [Built-in Skills](#built-in-skills) - [Built-in Skills](#built-in-skills)
- [Sisyphus Agent](#sisyphus-agent) - [Sisyphus Agent](#sisyphus-agent)
- [Background Tasks](#background-tasks) - [Background Tasks](#background-tasks)
- [Categories](#categories)
- [Hooks](#hooks) - [Hooks](#hooks)
- [MCPs](#mcps) - [MCPs](#mcps)
- [LSP](#lsp) - [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_search**: AST-aware code pattern search (25 languages)
- **ast_grep_replace**: AST-aware code replacement - **ast_grep_replace**: AST-aware code replacement
- **call_omo_agent**: Spawn specialized explore/librarian agents. Supports `run_in_background` parameter for async execution. - **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 #### Session Management
@ -932,7 +934,8 @@ When enabled (default), Sisyphus provides a powerful orchestrator with optional
- **Sisyphus**: Primary orchestrator agent (Claude Opus 4.5) - **Sisyphus**: Primary orchestrator agent (Claude Opus 4.5)
- **OpenCode-Builder**: OpenCode's default build agent, renamed due to SDK limitations (disabled by default) - **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:** **Configuration Options:**
@ -981,19 +984,22 @@ You can also customize Sisyphus agents like other agents:
"OpenCode-Builder": { "OpenCode-Builder": {
"model": "anthropic/claude-opus-4" "model": "anthropic/claude-opus-4"
}, },
"Planner-Sisyphus": { "Prometheus (Planner)": {
"model": "openai/gpt-5.2" "model": "openai/gpt-5.2"
},
"Metis (Plan Consultant)": {
"model": "anthropic/claude-sonnet-4-5"
} }
} }
} }
``` ```
| Option | Default | Description | | Option | Default | Description |
| ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- | | --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | `false` | When `true`, disables all Sisyphus orchestration and restores original build/plan as primary. | | `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. | | `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. | | `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 Planner-Sisyphus and default plan available. | | `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 ### 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) - Allow more concurrent tasks for fast/cheap models (e.g., Gemini Flash)
- Respect provider rate limits by setting provider-level caps - 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 ### Hooks
Disable specific built-in hooks via `disabled_hooks` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`: Disable specific built-in hooks via `disabled_hooks` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:

12
README.zh-cn.md
View File

@ -863,7 +863,8 @@ Agent 爽了，你自然也爽。但我还想直接让你爽。
- **Sisyphus**：主编排 Agent（Claude Opus 4.5） - **Sisyphus**：主编排 Agent（Claude Opus 4.5）
- **OpenCode-Builder**：OpenCode 默认构建 Agent（因 SDK 限制仅改名，默认禁用） - **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": { "OpenCode-Builder": {
"model": "anthropic/claude-opus-4" "model": "anthropic/claude-opus-4"
}, },
"Planner-Sisyphus": { "Prometheus (Planner)": {
"model": "openai/gpt-5.2" "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。 | | `disabled` | `false` | 设为 `true` 就禁用所有 Sisyphus 编排，恢复原来的 build/plan。 |
| `default_builder_enabled` | `false` | 设为 `true` 就启用 OpenCode-Builder Agent（与 OpenCode build 相同，因 SDK 限制仅改名）。默认禁用。 | | `default_builder_enabled` | `false` | 设为 `true` 就启用 OpenCode-Builder Agent（与 OpenCode build 相同，因 SDK 限制仅改名）。默认禁用。 |
| `planner_enabled` | `true` | 设为 `true` 就启用 Planner-Sisyphus Agent（与 OpenCode plan 相同，因 SDK 限制仅改名）。默认启用。 | | `planner_enabled` | `true` | 设为 `true` 就启用 Prometheus (Planner) Agent（含 work-planner 方法论）。默认启用。 |
| `replace_plan` | `true` | 设为 `true` 就把默认计划 Agent 降级为子 Agent 模式。设为 `false` 可以同时保留 Planner-Sisyphus 和默认计划。 | | `replace_plan` | `true` | 设为 `true` 就把默认计划 Agent 降级为子 Agent 模式。设为 `false` 可以同时保留 Prometheus (Planner) 和默认计划。 |
### Background Tasks（后台任务） ### Background Tasks（后台任务）

79
src/tools/AGENTS.md
View File

@ -2,26 +2,33 @@
## OVERVIEW ## 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 ## STRUCTURE
``` ```
tools/ tools/
├── ast-grep/ # AST-aware code search/replace (25 languages) ├── ast-grep/ # AST-aware code search/replace (25 languages)
│ ├── napi.ts # @ast-grep/napi binding (preferred) │ ├── cli.ts # @ast-grep/cli subprocess
│ └── cli.ts # @ast-grep/cli fallback │ ├── napi.ts # @ast-grep/napi native binding (preferred)
│ ├── constants.ts, types.ts, tools.ts, utils.ts
├── background-task/ # Async agent task management ├── background-task/ # Async agent task management
├── call-omo-agent/ # Spawn explore/librarian agents ├── call-omo-agent/ # Spawn explore/librarian agents
├── glob/ # File pattern matching (60s timeout) ├── glob/ # File pattern matching (timeout-safe)
├── grep/ # Content search (60s timeout) ├── grep/ # Content search (timeout-safe)
├── interactive-bash/ # Tmux session management ├── interactive-bash/ # Tmux session management
├── look-at/ # Multimodal analysis (PDF, images) ├── look-at/ # Multimodal analysis (PDF, images)
├── lsp/ # 11 LSP tools (611 lines client.ts) ├── lsp/ # 11 LSP tools
│ ├── client.ts # LSP connection lifecycle │ ├── client.ts # LSP connection lifecycle
│ ├── config.ts # Server configurations │ ├── 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 │ └── tools.ts # Tool implementations
├── session-manager/ # OpenCode session file ops
├── skill/ # Skill loading and execution ├── skill/ # Skill loading and execution
├── skill-mcp/ # Skill-embedded MCP invocation ├── skill-mcp/ # Skill-embedded MCP invocation
├── slashcommand/ # Slash command execution ├── slashcommand/ # Slash command execution
@ -30,39 +37,47 @@ tools/
## TOOL CATEGORIES ## TOOL CATEGORIES
| Category | Tools | | 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 | | 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 | | AST | ast_grep_search, ast_grep_replace | Pattern-based code search/replace |
| File Search | grep, glob | | File Search | grep, glob | Content and file pattern matching |
| Session | session_list, session_read, session_search, session_info | | Session | session_list, session_read, session_search, session_info | OpenCode session file management |
| Background | background_task, background_output, background_cancel | | Background | sisyphus_task, background_output, background_cancel | Async agent orchestration |
| Multimodal | look_at | | Multimodal | look_at | PDF/image analysis via Gemini |
| Terminal | interactive_bash | | Terminal | interactive_bash | Tmux session control |
| Skills | skill, skill_mcp | | Commands | slashcommand | Execute slash commands |
| Agents | call_omo_agent | | 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/` 1. Create directory: `src/tools/my-tool/`
2. Files: `constants.ts`, `types.ts`, `tools.ts`, `index.ts` 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` 3. Add to `builtinTools` in `src/tools/index.ts`
## LSP SPECIFICS ## LSP SPECIFICS
- Lazy init on first use, auto-shutdown on idle - **Client lifecycle**: Lazy init on first use, auto-shutdown on idle
- Config priority: opencode.json > oh-my-opencode.json > defaults - **Config priority**: opencode.json > oh-my-opencode.json > defaults
- Servers: typescript-language-server, pylsp, gopls, rust-analyzer - **Supported servers**: typescript-language-server, pylsp, gopls, rust-analyzer, etc.
- **Custom servers**: Add via `lsp` config in oh-my-opencode.json
## AST-GREP SPECIFICS ## AST-GREP SPECIFICS
- Meta-variables: `$VAR` (single), `$$$` (multiple) - **Meta-variables**: `$VAR` (single node), `$$$` (multiple nodes)
- Pattern must be valid AST node, not fragment - **Languages**: 25 supported (typescript, tsx, python, rust, go, etc.)
- Prefers napi binding for performance - **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) - **No timeout**: Always use timeout for file operations (default 60s)
- Sync file operations (use async/await) - **Blocking main thread**: Use async/await, never sync file ops
- Ignoring LSP errors (graceful handling required) - **Ignoring LSP errors**: Gracefully handle server not found/crashed
- Raw subprocess for ast-grep (prefer napi) - **Raw subprocess for ast-grep**: Prefer napi binding for performance