Opencode Build Tool

OpenCode SDK Development

Quick Start: Custom Tool in 3 Steps

1. Create .opencode/tool/my-tool.ts:

import { tool } from "@opencode-ai/plugin"

export default tool({
  description: "Brief description of what the tool does",
  args: {
    query: tool.schema.string().describe("Search query")
  },
  async execute({ query }, { abort }) {
    return `Result for: ${query}`
  }
})

1. Restart OpenCode — tools are auto-discovered.
2. Filename = tool name: my-tool.ts → my-tool.

Mindset

• @opencode-ai/plugin — Tools + Hooks: Add LLM-callable tools, intercept execution, react to events
• @opencode-ai/sdk — Client API: Control OpenCode from external scripts, session management

When to use: Adding new capabilities the agent doesn't have, automating OpenCode from CI/scripts, or integrating external APIs as first-class tools. When NOT to use: Built-in tool exists (client.tool.list()). Need shell (use $ from Bun). Logic belongs in system prompt (AGENTS.md). Need MCP.

> Full decision guide in [advanced-patterns.md](references/advanced-patterns.md).

Tool File Locations

.opencode/tool/*.ts          # project-specific
~/.config/opencode/tool/*.ts  # global

Multiple named exports per file → multiple tools: filename_exportname

Anti-Patterns

NEVER return non-string from execute. WHY: The tool runtime expects a string response; returning an object throws at runtime.

// BAD - throws at runtime
async execute({ query }) { return { results: [] } }
// GOOD - serialize first
async execute({ query }) { return JSON.stringify({ results: [] }) }

NEVER import { tool } from "@opencode-ai/sdk". WHY: The SDK package has no tool() export. The tool factory is only in @opencode-ai/plugin.

// BAD - import error at runtime
import { tool } from "@opencode-ai/sdk"
// GOOD
import { tool } from "@opencode-ai/plugin"

NEVER ignore the abort signal in long-running operations. WHY: Ignoring abort leaves processes dangling after the user cancels, consuming resources.

// BAD - dangling fetch after cancel
async execute({ url }) { return await fetch(url).then(r => r.text()) }
// GOOD - propagate abort
async execute({ url }, { abort }) { return await fetch(url, { signal: abort }).then(r => r.text()) }

Reference Files

• [advanced-patterns.md](references/advanced-patterns.md) — patterns, anti-patterns, SDK examples; [sdk-api.md](references/sdk-api.md) — SDK client API; [plugin-api.md](references/plugin-api.md) — plugin hooks
• [basic-tool.ts](references/basic-tool.ts) — simple tool; [full-plugin.ts](references/full-plugin.ts) — complete plugin

Run bun run opencode run "list tools" to verify your tool is discovered and named correctly.

---
description: custom tools opencode SDK plugin execute handler abort signal Zod schema session management event streaming
---

Eval Scenarios

• [Scenario 0: Create a custom todo-search tool with schema validation](evals/scenario-0/task.md)
• [Scenario 1: Use SDK client to create session and send prompt](evals/scenario-1/task.md)
• [Scenario 2: Implement abort signal handling in long-running tools](evals/scenario-2/task.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pantheon-org
• Source: pantheon-org/tekhne
• License: MIT
• Homepage: https://pantheon-org.github.io/tekhne/

Install and usage instructions live in the source repository linked above.