74 lines
3.2 KiB
Markdown
74 lines
3.2 KiB
Markdown
|
# TOOLS KNOWLEDGE BASE
|
||
|
|
|
||
|
|
## OVERVIEW
|
||
|
|
|
||
|
|
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)
|
||
|
|
│ ├── 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 (timeout-safe)
|
||
|
|
├── grep/ # Content search (timeout-safe)
|
||
|
|
├── interactive-bash/ # Tmux session management
|
||
|
|
├── look-at/ # Multimodal analysis (PDF, images)
|
||
|
|
├── lsp/ # 11 LSP tools
|
||
|
|
│ ├── client.ts # LSP connection lifecycle
|
||
|
|
│ ├── config.ts # Server configurations
|
||
|
|
│ ├── tools.ts # Tool implementations
|
||
|
|
│ └── types.ts
|
||
|
|
├── slashcommand/ # Slash command execution
|
||
|
|
└── index.ts # builtinTools export
|
||
|
|
```
|
||
|
|
|
||
|
|
## TOOL CATEGORIES
|
||
|
|
|
||
|
|
| 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 |
|
||
|
|
| Background | background_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 |
|
||
|
|
| Agents | call_omo_agent | Spawn explore/librarian |
|
||
|
|
|
||
|
|
## HOW TO ADD A TOOL
|
||
|
|
|
||
|
|
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
|
||
|
|
|
||
|
|
- **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 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 (TOOLS)
|
||
|
|
|
||
|
|
- **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
|