pantheon-org/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.

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 — patterns, anti-patterns, SDK examples; sdk-api.md — SDK client API; plugin-api.md — plugin hooks
• basic-tool.ts — simple tool; 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
• Scenario 1: Use SDK client to create session and send prompt
• Scenario 2: Implement abort signal handling in long-running tools