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

docs(agents): regenerate hierarchical AGENTS.md with init-deep

Browse Source 
- Root AGENTS.md: Updated timestamp, commit hash, line counts
- src/agents/AGENTS.md: Updated to 50 lines, current structure
- src/cli/AGENTS.md: Updated to 57 lines, current structure
- src/features/AGENTS.md: Updated to 65 lines, current structure
- src/hooks/AGENTS.md: Updated to 53 lines, current structure
- src/shared/AGENTS.md: Updated to 52 lines, core utilities
- src/tools/AGENTS.md: Updated to 50 lines, tool categories

🤖 Generated with assistance of [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode)
This commit is contained in:
justsisyphus 2026-01-17 19:16:49 +09:00
parent 987ae46841
commit 36b665ed89
7 changed files with 119 additions and 166 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
AGENTS.md
View File

@ -1,7 +1,7 @@
# PROJECT KNOWLEDGE BASE # PROJECT KNOWLEDGE BASE
**Generated:** 2026-01-15T14:53:00+09:00 **Generated:** 2026-01-17T19:00:25+09:00
**Commit:** 89fa9ff1 **Commit:** 987ae468
**Branch:** dev **Branch:** dev
## OVERVIEW ## OVERVIEW
@ -21,7 +21,7 @@ oh-my-opencode/
│ ├── cli/ # CLI installer, doctor - see src/cli/AGENTS.md │ ├── cli/ # CLI installer, doctor - see src/cli/AGENTS.md
│ ├── mcp/ # MCP configs: context7, grep_app, websearch │ ├── mcp/ # MCP configs: context7, grep_app, websearch
│ ├── config/ # Zod schema, TypeScript types │ ├── config/ # Zod schema, TypeScript types
│ └── index.ts # Main plugin entry (580 lines) │ └── index.ts # Main plugin entry (568 lines)
├── script/ # build-schema.ts, publish.ts, generate-changelog.ts ├── script/ # build-schema.ts, publish.ts, generate-changelog.ts
├── assets/ # JSON schema ├── assets/ # JSON schema
└── dist/ # Build output (ESM + .d.ts) └── dist/ # Build output (ESM + .d.ts)
@ -48,7 +48,7 @@ oh-my-opencode/
| Shared utilities | `src/shared/` | Cross-cutting utilities | | Shared utilities | `src/shared/` | Cross-cutting utilities |
| Slash commands | `src/hooks/auto-slash-command/` | Auto-detect and execute `/command` patterns | | 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 | | Ralph Loop | `src/hooks/ralph-loop/` | Self-referential dev loop until completion |
| Orchestrator | `src/hooks/sisyphus-orchestrator/` | Main orchestration hook (684 lines) | | Orchestrator | `src/hooks/sisyphus-orchestrator/` | Main orchestration hook (771 lines) |
## TDD (Test-Driven Development) ## TDD (Test-Driven Development)
@ -160,18 +160,17 @@ bun test # Run tests (80+ test files, 2500+ BDD assertions)
| File | Lines | Description | | File | Lines | Description |
|------|-------|-------------| |------|-------|-------------|
| `src/agents/orchestrator-sisyphus.ts` | 1485 | Orchestrator agent, 7-section delegation, accumulated wisdom | | `src/agents/orchestrator-sisyphus.ts` | 1531 | Orchestrator agent, 7-section delegation, accumulated wisdom |
| `src/features/builtin-skills/skills.ts` | 1230 | Skill definitions (frontend-ui-ux, playwright) | | `src/features/builtin-skills/skills.ts` | 1203 | Skill definitions (frontend-ui-ux, playwright) |
| `src/agents/prometheus-prompt.ts` | 991 | Planning agent, interview mode, multi-agent validation | | `src/agents/prometheus-prompt.ts` | 1196 | Planning agent, interview mode, multi-agent validation |
| `src/features/background-agent/manager.ts` | 928 | Task lifecycle, concurrency | | `src/features/background-agent/manager.ts` | 1165 | Task lifecycle, concurrency |
| `src/hooks/sisyphus-orchestrator/index.ts` | 771 | Orchestrator hook impl |
| `src/tools/delegate-task/tools.ts` | 770 | Category-based task delegation |
| `src/cli/config-manager.ts` | 730 | JSONC parsing, multi-level config, env detection | | `src/cli/config-manager.ts` | 730 | JSONC parsing, multi-level config, env detection |
| `src/hooks/sisyphus-orchestrator/index.ts` | 684 | Orchestrator hook impl | | `src/agents/sisyphus.ts` | 640 | Main Sisyphus prompt |
| `src/tools/sisyphus-task/tools.ts` | 667 | Category-based task delegation |
| `src/agents/sisyphus.ts` | 643 | Main Sisyphus prompt |
| `src/tools/lsp/client.ts` | 632 | LSP protocol, JSON-RPC |
| `src/features/builtin-commands/templates/refactor.ts` | 619 | Refactoring command template | | `src/features/builtin-commands/templates/refactor.ts` | 619 | Refactoring command template |
| `src/index.ts` | 580 | Main plugin, all hook/tool init | | `src/tools/lsp/client.ts` | 596 | LSP protocol, JSON-RPC |
| `src/hooks/anthropic-context-window-limit-recovery/executor.ts` | 554 | Multi-stage recovery | | `src/index.ts` | 568 | Main plugin, all hook/tool init |
## MCP ARCHITECTURE ## MCP ARCHITECTURE

31
src/agents/AGENTS.md
View File

@ -6,8 +6,8 @@ AI agent definitions for multi-model orchestration, delegating tasks to speciali
## STRUCTURE ## STRUCTURE
``` ```
agents/ agents/
├── orchestrator-sisyphus.ts # Orchestrator agent (1485 lines) - 7-section delegation, wisdom ├── orchestrator-sisyphus.ts # Orchestrator agent (1531 lines) - 7-section delegation, wisdom
├── sisyphus.ts # Main Sisyphus prompt (643 lines) ├── sisyphus.ts # Main Sisyphus prompt (640 lines)
├── sisyphus-junior.ts # Junior variant for delegated tasks ├── sisyphus-junior.ts # Junior variant for delegated tasks
├── oracle.ts # Strategic advisor (GPT-5.2) ├── oracle.ts # Strategic advisor (GPT-5.2)
├── librarian.ts # Multi-repo research (GLM-4.7-free) ├── librarian.ts # Multi-repo research (GLM-4.7-free)
@ -15,7 +15,7 @@ agents/
├── frontend-ui-ux-engineer.ts # UI generation (Gemini 3 Pro Preview) ├── frontend-ui-ux-engineer.ts # UI generation (Gemini 3 Pro Preview)
├── document-writer.ts # Technical docs (Gemini 3 Pro Preview) ├── document-writer.ts # Technical docs (Gemini 3 Pro Preview)
├── multimodal-looker.ts # PDF/image analysis (Gemini 3 Flash) ├── multimodal-looker.ts # PDF/image analysis (Gemini 3 Flash)
├── prometheus-prompt.ts # Planning agent prompt (991 lines) - interview mode ├── prometheus-prompt.ts # Planning agent prompt (1196 lines) - interview mode
├── metis.ts # Plan Consultant agent - pre-planning analysis ├── metis.ts # Plan Consultant agent - pre-planning analysis
├── momus.ts # Plan Reviewer agent - plan validation ├── momus.ts # Plan Reviewer agent - plan validation
├── build-prompt.ts # Shared build agent prompt ├── build-prompt.ts # Shared build agent prompt
@ -26,19 +26,6 @@ agents/
└── index.ts # builtinAgents export └── index.ts # builtinAgents export
``` ```
## AGENT MODELS
| Agent | Default Model | Purpose |
|-------|---------------|---------|
| Sisyphus | anthropic/claude-opus-4-5 | Primary orchestrator. 32k extended thinking budget. |
| oracle | openai/gpt-5.2 | High-IQ debugging, architecture, strategic consultation. |
| librarian | opencode/glm-4.7-free | Multi-repo analysis, docs research, GitHub examples. |
| explore | opencode/grok-code | Fast contextual grep. Fallbacks: Gemini-3-Flash, Haiku-4-5. |
| frontend-ui-ux | google/gemini-3-pro-preview | Production-grade UI/UX generation and styling. |
| document-writer | google/gemini-3-pro-preview | Technical writing, guides, API documentation. |
| Prometheus | anthropic/claude-opus-4-5 | Strategic planner. Interview mode, orchestrates Metis/Momus. |
| Metis | anthropic/claude-sonnet-4-5 | Plan Consultant. Pre-planning risk/requirement analysis. |
| Momus | anthropic/claude-sonnet-4-5 | Plan Reviewer. Validation and quality enforcement. |
## HOW TO ADD AN AGENT ## HOW TO ADD AN AGENT
1. Create `src/agents/my-agent.ts` exporting `AgentConfig`. 1. Create `src/agents/my-agent.ts` exporting `AgentConfig`.
2. Add to `builtinAgents` in `src/agents/index.ts`. 2. Add to `builtinAgents` in `src/agents/index.ts`.
@ -50,12 +37,14 @@ agents/
2. Environment-specific settings (max20, antigravity). 2. Environment-specific settings (max20, antigravity).
3. Hardcoded defaults in `index.ts`. 3. Hardcoded defaults in `index.ts`.
## SHARED PROMPTS
- **7-Section Delegation**: `orchestrator-sisyphus.ts` uses strict phases (0-6) for classification, research, planning, validation.
- **Wisdom Notepad**: Persistent scratchpad preserving project-specific learnings across turns.
- **Interview Mode**: `Prometheus` defaults to conversational consultant mode for requirement extraction.
- **build-prompt.ts**: Unified base for Sisyphus and Builder variants.
- **plan-prompt.ts**: Core planning logic shared across planning agents.
## ANTI-PATTERNS ## ANTI-PATTERNS
- **Trusting reports**: NEVER trust subagent self-reports; always verify outputs. - **Trusting reports**: NEVER trust subagent self-reports; always verify outputs.
- **High temp**: Don't use >0.3 for code agents (Sisyphus/Prometheus use 0.1). - **High temp**: Don't use >0.3 for code agents (Sisyphus/Prometheus use 0.1).
- **Sequential calls**: Prefer `delegate_task` with `run_in_background` for parallelism. - **Sequential calls**: Prefer `delegate_task` with `run_in_background` for parallelism.
## SHARED PROMPTS
- **build-prompt.ts**: Unified base for Sisyphus and Builder variants.
- **plan-prompt.ts**: Core planning logic shared across planning agents.
- **orchestrator-sisyphus.ts**: Uses a 7-section prompt structure and "wisdom notepad" to preserve learnings across turns.

2
src/cli/AGENTS.md
View File

@ -6,7 +6,7 @@ CLI for oh-my-opencode: interactive installer, health diagnostics (doctor), runt
## STRUCTURE ## STRUCTURE
``` ```
cli/ cli/
├── index.ts # Commander.js entry, subcommand routing (146 lines) ├── index.ts # Commander.js entry, subcommand routing
├── install.ts # Interactive TUI installer (462 lines) ├── install.ts # Interactive TUI installer (462 lines)
├── config-manager.ts # JSONC parsing, env detection (730 lines) ├── config-manager.ts # JSONC parsing, env detection (730 lines)
├── types.ts # CLI-specific types ├── types.ts # CLI-specific types

52
src/features/AGENTS.md
View File

@ -6,25 +6,23 @@ Claude Code compatibility layer + core feature modules. Commands, skills, agents
## STRUCTURE ## STRUCTURE
``` ```
features/ features/
├── background-agent/ # Task lifecycle, notifications (928 lines manager.ts) ├── background-agent/ # Task lifecycle, notifications (1165 lines manager.ts)
├── boulder-state/ # Boulder state persistence ├── boulder-state/ # Boulder/Todo state persistence
├── builtin-commands/ # Built-in slash commands ├── builtin-commands/ # Built-in slash commands (ralph-loop, refactor, init-deep)
│ └── templates/ # start-work, refactor, init-deep, ralph-loop ├── builtin-skills/ # Built-in skills (1203 lines skills.ts)
├── builtin-skills/ # Built-in skills (1230 lines skills.ts) │ ├── git-master/ # Atomic commits, history search
│ ├── git-master/ # Atomic commits, rebase, history search │ ├── playwright/ # Browser automation
│ ├── playwright # Browser automation skill │ └── frontend-ui-ux/ # Designer-developer skill
│ └── frontend-ui-ux/ # Designer-turned-developer skill
├── claude-code-agent-loader/ # ~/.claude/agents/*.md ├── claude-code-agent-loader/ # ~/.claude/agents/*.md
├── claude-code-command-loader/ # ~/.claude/commands/*.md ├── claude-code-command-loader/ # ~/.claude/commands/*.md
├── claude-code-mcp-loader/ # .mcp.json files ├── claude-code-mcp-loader/ # .mcp.json files with ${VAR} expansion
│ └── env-expander.ts # ${VAR} expansion
├── claude-code-plugin-loader/ # installed_plugins.json ├── claude-code-plugin-loader/ # installed_plugins.json
├── claude-code-session-state/ # Session state persistence ├── claude-code-session-state/ # Session state persistence
├── context-injector/ # Context collection and injection ├── context-injector/ # AGENTS.md/README.md/Rules injection
├── opencode-skill-loader/ # Skills from OpenCode + Claude paths ├── opencode-skill-loader/ # Skills from OpenCode + Claude paths
├── skill-mcp-manager/ # MCP servers in skill YAML ├── skill-mcp-manager/ # MCP servers in skill YAML (stdio/http transports)
├── task-toast-manager/ # Task toast notifications ├── task-toast-manager/ # Task status toast notifications
└── hook-message-injector/ # Inject messages into conversation └── hook-message-injector/ # Message injection into conversation streams
``` ```
## LOADER PRIORITY ## LOADER PRIORITY
@ -36,7 +34,7 @@ features/
| MCPs | `.claude/.mcp.json` > `.mcp.json` > `~/.claude/.mcp.json` | | MCPs | `.claude/.mcp.json` > `.mcp.json` > `~/.claude/.mcp.json` |
## CONFIG TOGGLES ## CONFIG TOGGLES
```json ```jsonc
{ {
"claude_code": { "claude_code": {
"mcp": false, // Skip .mcp.json "mcp": false, // Skip .mcp.json
@ -49,19 +47,19 @@ features/
``` ```
## BACKGROUND AGENT ## BACKGROUND AGENT
- Lifecycle: pending → running → completed/failed - **Lifecycle**: `launch` → `poll` (idle/stability detection) → `complete`.
- Concurrency limits per provider/model (manager.ts) - **Concurrency**: Per-provider/model limits in `concurrency.ts`.
- `background_output` to retrieve results, `background_cancel` for cleanup - **Notification**: Auto-injects system reminders into parent session on task completion.
- Automatic task expiration and cleanup logic - **Cleanup**: Shutdown handler cancels pending waiters; idle tasks pruning (30m TTL).
## SKILL MCP ## SKILL MCP
- MCP servers embedded in skill YAML frontmatter - **Lazy Loading**: Clients connect on first tool call via `SkillMcpManager`.
- Lazy client loading via `skill-mcp-manager` - **Transports**: `stdio` (local process) or `http` (SSE/Streamable HTTP).
- `skill_mcp` tool for cross-skill tool discovery - **Environment**: `${VAR}` expansion in config via `env-expander.ts`.
- Session-scoped MCP server lifecycle management - **Lifecycle**: Session-scoped clients; auto-cleanup after 5m idle.
## ANTI-PATTERNS ## ANTI-PATTERNS
- Sequential execution for independent tasks (use `delegate_task`) - **Sequential Delegation**: Calling agents one-by-one; use `delegate_task` for parallel runs.
- Trusting agent self-reports without verification - **Self-Report Trust**: Trusting agent's "I'm done" without verifying against session state.
- Blocking main thread during loader initialization - **Main Thread Blocks**: Heavy I/O or long-running logic during loader initialization.
- Manual version bumping in `package.json` - **Manual Versioning**: Updating `package.json` version field; managed exclusively by CI.

13
src/hooks/AGENTS.md
View File

@ -6,12 +6,12 @@
## STRUCTURE ## STRUCTURE
``` ```
hooks/ hooks/
├── sisyphus-orchestrator/ # Main orchestration & agent delegation (684 lines) ├── sisyphus-orchestrator/ # Main orchestration & agent delegation (771 lines)
├── anthropic-context-window-limit-recovery/ # Auto-summarize at token limit (554 lines) ├── anthropic-context-window-limit-recovery/ # Auto-summarize at token limit (14 files)
├── todo-continuation-enforcer.ts # Force completion of [ ] items (445 lines) ├── todo-continuation-enforcer.ts # Force completion of [ ] items
├── ralph-loop/ # Self-referential dev loop (364 lines) ├── ralph-loop/ # Self-referential dev loop (7 files)
├── claude-code-hooks/ # settings.json hook compatibility layer ├── claude-code-hooks/ # settings.json hook compatibility layer (13 files)
├── comment-checker/ # Prevents AI slop/excessive comments ├── comment-checker/ # Prevents AI slop/excessive comments (13 files)
├── auto-slash-command/ # Detects and executes /command patterns ├── auto-slash-command/ # Detects and executes /command patterns
├── rules-injector/ # Conditional rules from .claude/rules/ ├── rules-injector/ # Conditional rules from .claude/rules/
├── directory-agents-injector/ # Auto-injects local AGENTS.md files ├── directory-agents-injector/ # Auto-injects local AGENTS.md files
@ -21,7 +21,6 @@ hooks/
├── thinking-block-validator/ # Ensures valid <thinking> format ├── thinking-block-validator/ # Ensures valid <thinking> format
├── context-window-monitor.ts # Reminds agents of remaining headroom ├── context-window-monitor.ts # Reminds agents of remaining headroom
├── session-recovery/ # Auto-recovers from session crashes ├── session-recovery/ # Auto-recovers from session crashes
├── start-work/ # Initializes work sessions (ulw/ulw)
├── think-mode/ # Dynamic thinking budget adjustment ├── think-mode/ # Dynamic thinking budget adjustment
├── background-notification/ # OS notification on task completion ├── background-notification/ # OS notification on task completion
└── tool-output-truncator.ts # Prevents context bloat from verbose tools └── tool-output-truncator.ts # Prevents context bloat from verbose tools

84
src/shared/AGENTS.md
View File

@ -1,74 +1,52 @@
# SHARED UTILITIES KNOWLEDGE BASE # SHARED UTILITIES KNOWLEDGE BASE
## OVERVIEW ## OVERVIEW
Cross-cutting utilities for path resolution, config management, text processing, and Claude Code compatibility. Core cross-cutting utilities for path resolution, token-safe text processing, and Claude Code compatibility.
## STRUCTURE ## STRUCTURE
``` ```
shared/ shared/
├── index.ts # Barrel export ├── logger.ts # Persistent file-based logging (tmpdir/oh-my-opencode.log)
├── agent-variant.ts # Agent model/prompt variation logic ├── permission-compat.ts # Agent tool restrictions (ask/allow/deny)
├── claude-config-dir.ts # ~/.claude resolution ├── dynamic-truncator.ts # Token-aware truncation with context headroom
├── command-executor.ts # Shell exec with variable expansion ├── frontmatter.ts # YAML frontmatter parsing with JSON_SCHEMA safety
├── config-errors.ts # Global error tracking ├── jsonc-parser.ts # JSON with Comments support for config files
├── config-path.ts # User/project config paths ├── data-path.ts # XDG-compliant storage paths (~/.local/share)
├── data-path.ts # XDG data directory ├── opencode-config-dir.ts # Resolve ~/.config/opencode for CLI/Desktop
├── deep-merge.ts # Type-safe recursive merge ├── claude-config-dir.ts # Resolve ~/.claude for compatibility
├── dynamic-truncator.ts # Token-aware truncation ├── migration.ts # Legacy name mapping (omo -> Sisyphus)
├── external-plugin-detector.ts # Detect marketplace plugins └── opencode-version.ts # Version comparison logic (e.g., >= 1.0.150)
├── file-reference-resolver.ts # @filename syntax
├── file-utils.ts # Symlink, markdown detection
├── first-message-variant.ts # Initial prompt variations
├── frontmatter.ts # YAML frontmatter parsing
├── hook-disabled.ts # Check if hook disabled
├── jsonc-parser.ts # JSON with Comments
├── logger.ts # File-based logging
├── migration.ts # Legacy name compat (omo → Sisyphus)
├── model-sanitizer.ts # Normalize model names
├── opencode-config-dir.ts # ~/.config/opencode resolution
├── opencode-version.ts # Version comparison logic
├── pattern-matcher.ts # Tool name matching
├── permission-compat.ts # Legacy permission mapping
├── session-cursor.ts # Track message history pointer
├── snake-case.ts # Case conversion
├── tool-name.ts # PascalCase normalization
└── zip-extractor.ts # Plugin installation utility
``` ```
## WHEN TO USE ## WHEN TO USE
| Task | Utility | | Task | Utility |
|------|---------| |------|---------|
| Find ~/.claude | `getClaudeConfigDir()` | | Debugging/Auditing | `log(message, data)` in `logger.ts` |
| Find ~/.config/opencode | `getOpenCodeConfigDir()` | | Limit agent context | `dynamicTruncate(ctx, sessionId, output)` |
| Merge configs | `deepMerge(base, override)` | | Parse rule meta | `parseFrontmatter(content)` |
| Parse user files | `parseJsonc()` | | Load user configs | `parseJsonc(text)` or `readJsoncFile(path)` |
| Check hook enabled | `isHookDisabled(name, list)` | | Restrict tools | `createAgentToolAllowlist(tools)` |
| Truncate output | `dynamicTruncate(text, budget)` | | Resolve app paths | `getOpenCodeConfigDir()` or `getClaudeConfigDir()` |
| Resolve @file | `resolveFileReferencesInText()` | | Update legacy config | `migrateConfigFile(path, rawConfig)` |
| Execute shell | `resolveCommandsInText()` |
| Legacy names | `migrateLegacyAgentNames()` |
| Version check | `isOpenCodeVersionAtLeast(version)` |
| Map permissions | `normalizePermission()` |
| Track session | `SessionCursor` |
## CRITICAL PATTERNS ## CRITICAL PATTERNS
```typescript ```typescript
// Dynamic truncation with context budget // Truncate large output based on 50% remaining context window
const output = dynamicTruncate(result, remainingTokens, 0.5) const { result } = await dynamicTruncate(ctx, sessionID, largeBuffer);
// Config resolution priority // Safe config loading with comment/trailing comma support
const final = deepMerge(deepMerge(defaults, userConfig), projectConfig) const settings = readJsoncFile<Settings>(configPath);
// Safe JSONC parsing for user-edited files // Version-gated logic for OpenCode 1.1.0+
const { config, error } = parseJsoncSafe(content) if (isOpenCodeVersionAtLeast("1.1.0")) { /* ... */ }
// Version-gated features // Permission normalization for agent tools
if (isOpenCodeVersionAtLeast('1.0.150')) { /* ... */ } const permissions = migrateToolsToPermission(legacyTools);
``` ```
## ANTI-PATTERNS ## ANTI-PATTERNS
- Hardcoding paths (use `getClaudeConfigDir`, `getOpenCodeConfigDir`) - Raw `JSON.parse` for configs (use `jsonc-parser.ts`)
- Using `JSON.parse` for user configs (always use `parseJsonc`) - Hardcoded `~/.claude` (use `claude-config-dir.ts`)
- Ignoring output size (large tool outputs MUST use `dynamicTruncate`) - `console.log` for background agents (use `logger.ts`)
- Manual version parsing (use `opencode-version.ts` utilities) - Unbounded tool output (always use `dynamic-truncator.ts`)
- Raw permission checks (use `permission-compat.ts`) - Manual version parsing (use `opencode-version.ts`)

76
src/tools/AGENTS.md
View File

@ -1,60 +1,50 @@
# TOOLS KNOWLEDGE BASE # TOOLS KNOWLEDGE BASE
## OVERVIEW ## OVERVIEW
Custom tools extending agent capabilities: LSP (3 tools), AST-aware search/replace, background tasks, and multimodal analysis. Core toolset implementing LSP, structural search, and system orchestration. Extends OpenCode with high-performance C++ bindings and multi-agent delegation.
## STRUCTURE ## STRUCTURE
``` ```
tools/ tools/
├── ast-grep/ # AST-aware search/replace (25 languages) ├── [tool-name]/
│ ├── cli.ts # @ast-grep/cli fallback │ ├── index.ts # Tool factory entry
│ └── napi.ts # @ast-grep/napi native binding (preferred) │ ├── tools.ts # Business logic & implementation
├── background-task/ # Async agent task management │ ├── types.ts # Zod schemas & TS types
├── call-omo-agent/ # Spawn explore/librarian agents │ └── constants.ts # Tool-specific fixed values
├── glob/ # File pattern matching (timeout-safe) ├── lsp/ # 11 tools via JSON-RPC client (596 lines client.ts)
├── grep/ # Content search (timeout-safe) ├── ast-grep/ # Structural search (NAPI bindings)
├── interactive-bash/ # Tmux session management ├── delegate-task/ # Category-based agent routing (770 lines tools.ts)
├── look-at/ # Multimodal analysis (PDF, images) ├── session-manager/ # OpenCode session history (9 files)
├── lsp/ # IDE-like code intelligence └── interactive-bash/ # Tmux session management (5 files)
│ ├── client.ts # LSP connection lifecycle (632 lines)
│ ├── tools.ts # Tool implementations
│ └── config.ts, types.ts, utils.ts
├── session-manager/ # OpenCode session history management
├── sisyphus-task/ # Category-based delegation (667 lines)
├── skill/ # Skill loading/execution
├── skill-mcp/ # Skill-embedded MCP invocation
├── slashcommand/ # Slash command execution
└── index.ts # builtinTools export (75 lines)
``` ```
## TOOL CATEGORIES ## TOOL CATEGORIES
| Category | Tools | Purpose | | Category | Purpose | Key Implementations |
|----------|-------|---------| |----------|---------|---------------------|
| LSP | lsp_diagnostics, lsp_prepare_rename, lsp_rename | IDE-grade code intelligence (3 tools) | | **LSP** | Semantic code intelligence | `lsp_goto_definition`, `lsp_find_references`, `lsp_rename` |
| AST | ast_grep_search, ast_grep_replace | Structural pattern matching/rewriting | | **Search** | Fast discovery & matching | `glob`, `grep`, `ast_grep_search`, `ast_grep_replace` |
| Search | grep, glob | Timeout-safe file and content search | | **System** | CLI & Environment | `bash`, `interactive_bash` (tmux), `look_at` (vision) |
| Session | session_list, session_read, session_search, session_info | History navigation and retrieval | | **Session** | History & Context | `session_read`, `session_search`, `session_select` |
| Background | delegate_task, background_output, background_cancel | Parallel agent orchestration | | **Agent** | Task Orchestration | `delegate_task`, `call_omo_agent` |
| UI/Terminal | look_at, interactive_bash | Visual analysis and tmux control |
| Execution | slashcommand, skill, skill_mcp | Command and skill-based extensibility |
## HOW TO ADD A TOOL ## HOW TO ADD
1. Create directory `src/tools/my-tool/`. 1. **Directory**: Create `src/tools/[name]/` with standard files.
2. Implement `tools.ts` (factory), `types.ts`, and `constants.ts`. 2. **Factory**: Use `tool()` from `@opencode-ai/plugin/tool`.
3. Export via `index.ts` and register in `src/tools/index.ts`. 3. **Parameters**: Define strict Zod schemas in `types.ts`.
4. **Registration**: Export from `src/tools/index.ts` and add to `builtinTools`.
## LSP SPECIFICS ## LSP SPECIFICS
- **Lifecycle**: Lazy initialization on first call; auto-shutdown on idle. - **Client**: `lsp/client.ts` manages stdio lifecycle and JSON-RPC.
- **Config**: Merges `opencode.json` and `oh-my-opencode.json`. - **Capabilities**: Supports definition, references, symbols, diagnostics, and workspace-wide rename.
- **Capability**: Supports full LSP spec including `rename` and `prepareRename`. - **Protocol**: Maps standard LSP methods to tool-compatible responses.
## AST-GREP SPECIFICS ## AST-GREP SPECIFICS
- **Precision**: Uses tree-sitter for structural matching (avoids regex pitfalls). - **Engine**: Uses `@ast-grep/napi` for 25+ language support.
- **Binding**: Uses `@ast-grep/napi` for performance; ensure patterns are valid AST nodes. - **Patterns**: Supports meta-variables (`$VAR`) and multi-node matching (`$$$`).
- **Variables**: Supports `$VAR` and `$$$` meta-variables for capture. - **Performance**: Structural matching executed in Rust/C++ layer.
## ANTI-PATTERNS ## ANTI-PATTERNS
- **Sync Ops**: Never use synchronous file I/O; blocking the main thread kills responsiveness. - **Sequential Calls**: Don't call `bash` in loops; use `&&` or delegation.
- **No Timeouts**: Always wrap external CLI/LSP calls in timeouts (default 60s). - **Raw File Ops**: Never use `mkdir/touch` inside tool logic.
- **Direct Subprocess**: Avoid raw `spawn` for ast-grep; use NAPI binding. - **Heavy Sync**: Keep `PreToolUse` light; heavy computation belongs in `tools.ts`.
- **Manual Pathing**: Use `shared/utils` for path normalization across platforms. - **Sleep**: Never use `sleep N`; use polling loops or tool-specific wait flags.