Tool Registry
Relevant source files
The following files were used as context for generating this wiki page:
The Tool Registry serves as the central management system for all executable capabilities within the OhMyOpenCode ecosystem. It enables agents to interact with the file system, manage asynchronous tasks, perform deep codebase searches, and delegate work to specialized sub-agents. The registry is initialized via a createToolRegistry() function, which aggregates various tool categories into a unified interface for the primary orchestrators like Sisyphus and Hephaestus.
Sources: src/tools/AGENTS.md:1-10, CONTRIBUTING.md:73-85
Architecture and Tool Lifecycle
The registry architecture follows a modular pattern where tools are either defined directly as ToolDefinition objects or generated via factory functions (e.g., createXXXTool). This design allows for conditional tool registration, such as the hashline_edit tool which is only available under specific configurations.
Tool Integration Flow
The diagram shows how createToolRegistry aggregates factory-produced and directly defined tools to provide a functional context for AI agents.
Sources: src/tools/AGENTS.md:7-15, CONTRIBUTING.md:130-140
Tool Categories and Catalog
The registry organizes 26 distinct tools across several specialized categories. Each tool is designed to be called by agents using specific parameters to perform atomic operations.
Task and Background Management
These tools are critical for agents that operate over multiple turns or handle complex, non-trivial work.
| Tool | Purpose | Key Parameters |
|---|---|---|
task_create | Initializes a new trackable task. | subject, description, blocks |
task_update | Modifies status or metadata. | id, status, owner |
task | Primary delegation tool for sub-agents. | category, prompt, run_in_background |
background_output | Retrieves results from async tasks. | task_id, block, timeout |
background_cancel | Terminates active background tasks. | taskId, all |
Sources: src/tools/AGENTS.md:19-45, src/agents/hephaestus/gpt.ts:31-45
Codebase Exploration and LSP
The registry provides advanced search capabilities through AST (Abstract Syntax Tree) patterns and Language Server Protocol (LSP) integrations.
- LSP Tools: Includes
lsp_goto_definition,lsp_diagnostics, andlsp_renamefor precise symbol manipulation. - Search Tools:
ast_grep_searchandast_grep_replaceallow for structural code modifications, while standardgrepandglobhandle text-based discovery.
Sources: src/tools/AGENTS.md:55-75, src/agents/sisyphus.ts:250-265
Delegation and Agent Invocation
One of the most powerful features of the registry is the task tool, which allows primary agents to spawn specialized sub-agents. The registry maps these calls to specific model configurations based on the requested category.
Agent Delegation Matrix
| Category | Recommended Model | Use Case |
|---|---|---|
visual-engineering | Gemini 3.1 Pro | Frontend, UI/UX, and CSS |
ultrabrain | GPT-5.4 | Hard logic and complex algorithms |
deep | GPT-5.4 | Autonomous problem-solving |
librarian | (Sub-agent Type) | External docs and OS research |
writing | Gemini 3 Flash | Documentation and prose |
Sources: src/tools/AGENTS.md:90-105, src/agents/librarian.ts:10-25, src/agents/prometheus/gpt.ts:110-125
Sequence of a Tool Call
When an agent like Prometheus needs to gather context, it follows a strict sequence of tool interactions managed by the registry.
This sequence illustrates the asynchronous delegation pattern where the Registry manages the handoff between a primary agent and a background search task.
Sources: src/agents/sisyphus.ts:280-310, src/agents/prometheus/gpt.ts:120-140
Implementation Guidelines
Adding a new tool to the registry requires following a standardized structure to ensure compatibility with the agent prompting system:
- Factory Definition: Create a factory in
src/tools/{name}/index.ts. - Schema Definition: Define parameter types in
types.tsusing Zod or equivalent for validation. - Core Logic: Implement the tool execution in
tools.ts. - Registration: Import and include the factory in
src/plugin/tool-registry.ts.
Sources: src/tools/AGENTS.md:110-115, CONTRIBUTING.md:145-155
Summary
The Tool Registry is the engine that transforms an LLM into an autonomous software engineer. By providing structured access to system commands, codebase intelligence, and agent-to-agent delegation, it allows the OhMyOpenCode system to handle multi-step engineering goals with a high degree of precision and verification. The reliance on parallel execution and background result collection ensures that agents remain responsive while performing deep research.
Sources: src/agents/hephaestus/gpt.ts:200-210, src/agents/sisyphus.ts:500-510