Skip to main content

​
Overview

Oh My OpenCode extends OpenCode with 26 specialized tools across 15 categories. Tools are registered via createToolRegistry() and follow two patterns:
  • Factory functions (createXXXTool): 19 tools that require context/dependencies
  • Direct ToolDefinition: 7 tools (LSP + interactive_bash) with static definitions

​
Tool Categories

​
Task Management (4 tools)

Manage tasks with dependencies, metadata, and lifecycle tracking.
ToolFactoryDescription
task_createcreateTaskCreateToolCreate new task with dependencies
task_listcreateTaskListList all active tasks
task_getcreateTaskGetToolGet task details by ID
task_updatecreateTaskUpdateToolUpdate task status/metadata

​
Delegation (1 tool)

Delegate work to specialized agents with category-based model selection.
ToolDescription
taskSpawn agent task with category or direct agent selection
Categories: visual-engineering, ultrabrain, deep, artistry, quick, unspecified-low, unspecified-high, writing See delegate-task for detailed documentation.

​
Agent Invocation (1 tool)

ToolDescription
call_omo_agentDirect agent invocation without category system

​
Background Tasks (2 tools)

Manage async agent execution with polling and cancellation.
ToolDescription
background_outputFetch results from running/completed background task
background_cancelCancel running task(s)
See background-task for detailed documentation.

​
LSP Refactoring (6 tools)

Language Server Protocol integration for code intelligence.
ToolDescription
lsp_goto_definitionJump to symbol definition
lsp_find_referencesFind all symbol usages
lsp_symbolsDocument outline or workspace symbols
lsp_diagnosticsGet errors/warnings before build
lsp_prepare_renameValidate rename operation
lsp_renameSafe cross-workspace rename
See lsp-tools for detailed documentation.

​
Code Search (4 tools)

AST-aware and regex-based code search with pattern matching.
ToolDescription
ast_grep_searchAST-aware pattern search (25 languages)
ast_grep_replaceAST-aware code rewriting
grepRegex content search (60s timeout, 10MB limit)
globFile pattern matching (60s timeout, 100 file limit)
See ast-grep for detailed documentation.

​
Session History (4 tools)

Query and navigate conversation history.
ToolDescription
session_listList all sessions
session_readRead session messages
session_searchSearch session content
session_infoGet session metadata

​
Skill/Command (2 tools)

Load specialized skills and MCP integrations.
ToolDescription
skillLoad built-in skill by name
skill_mcpInvoke MCP tool/resource/prompt

​
System (2 tools)

System interaction and multimodal capabilities.
ToolDescription
interactive_bashInteractive tmux session management
look_atVision model analysis of images/screenshots

​
Editing (1 tool)

Hash-anchored file editing with stale-line detection.
ToolDescription
hashline_editSafe file editing using LINE#ID validation
See hashline-edit for detailed documentation.

​
Tool Registry

Tools are registered in src/plugin/tool-registry.ts: 
import { createToolRegistry } from "@opencode-ai/plugin"
import { builtinTools } from "../tools"
import { createHashlineEditTool } from "../tools/hashline-edit"
import { createAstGrepTools } from "../tools/ast-grep"

export function createTools(ctx: PluginInput): Record<string, ToolDefinition> {
  return {
    ...builtinTools,
    hashline_edit: createHashlineEditTool(),
    ...createAstGrepTools(ctx),
    ...createBackgroundTools(manager, client),
    task: createDelegateTask(options),
    // ... other tools
  }
}

​
Adding a New Tool

  1. Create src/tools/{name}/index.ts exporting factory
  2. Create src/tools/{name}/types.ts for parameter schemas
  3. Create src/tools/{name}/tools.ts for implementation
  4. Register in src/plugin/tool-registry.ts

​
Example Structure

// src/tools/my-tool/tools.ts
import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool"

export function createMyTool(): ToolDefinition {
  return tool({
    description: "What this tool does",
    args: {
      param1: tool.schema.string().describe("Parameter description"),
      param2: tool.schema.number().optional(),
    },
    execute: async (args, context) => {
      // Implementation
      return "result"
    },
  })
}

​
Tool Execution Lifecycle

Tools participate in the hook system with pre/post execution hooks: 
tool.execute.before hooks
  ↓
Tool execution
  ↓
tool.execute.after hooks

​
Available Hooks

Before Hooks: commentChecker, rulesInjector, writeExistingFileGuard, hashlineReadEnhancer After Hooks: outputTruncation, metadataStore, labelTruncator See /api/hooks for hook documentation.

​
Configuration

Tools can be disabled via config: 
// .opencode/oh-my-opencode.jsonc
{
  "disabled_tools": ["hashline_edit", "lsp_rename"]
}

​
Source Location

All tool implementations: ~/workspace/source/src/tools/
  • Each tool has its own directory
  • Common pattern: index.ts (exports), tools.ts (implementation), types.ts (schemas)
  • Test files co-located: *.test.ts

Build docs developers (and LLMs) love

Get started for freeTalk to us