1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
---
title: Custom tools
description: Create custom tools to extend opencode capabilities.
---
Custom tools are functions you create that the LLM can call during conversations. They work alongside opencode's built-in tools like `read`, `write`, and `bash`.
---
## Tool structure
Tools are defined as `.ts/.js` files in the `.opencode/tool/` directory. They
can also be defined globally in `~/.config/opencode/tool/`.
The easiest way to create tools is using the `tool()` helper which provides type safety and validation. Use `tool.schema` (which is just [Zod](https://zod.dev)) to define argument types:
```ts title=".opencode/tool/database.ts"
import { tool } from "@opencode-ai/plugin"
export default tool({
description: "Query the project database",
args: {
query: tool.schema.string().describe("SQL query to execute"),
},
async execute(args) {
// Your database logic here
return `Executed query: ${args.query}`
},
})
```
You can also import [Zod](https://zod.dev) directly and return a plain object:
```ts
import { z } from "zod"
export default {
description: "Tool description",
args: {
param: z.string().describe("Parameter description"),
},
async execute(args, context) {
// Tool implementation
return "result"
},
}
```
The filename becomes the tool name. This creates a `database` tool.
---
## Multiple tools per file
You can export multiple tools from a single file. Each export becomes a separate tool with the name `<filename>_<exportname>`:
```ts title=".opencode/tool/math.ts"
import { tool } from "@opencode-ai/plugin"
export const add = tool({
description: "Add two numbers",
args: {
a: tool.schema.number().describe("First number"),
b: tool.schema.number().describe("Second number"),
},
async execute(args) {
return args.a + args.b
},
})
export const multiply = tool({
description: "Multiply two numbers",
args: {
a: tool.schema.number().describe("First number"),
b: tool.schema.number().describe("Second number"),
},
async execute(args) {
return args.a * args.b
},
})
```
This creates two tools: `math_add` and `math_multiply`.
---
## Arguments
Use `tool.schema` (which is just [Zod](https://zod.dev)) to define tool arguments with validation and descriptions:
```ts title=".opencode/tool/calculator.ts"
import { tool } from "@opencode-ai/plugin"
export default tool({
description: "Perform mathematical calculations",
args: {
expression: tool.schema.string().describe("Mathematical expression to evaluate"),
precision: tool.schema.number().optional().describe("Decimal precision"),
},
async execute(args) {
// Your calculation logic here
return `Result: ${eval(args.expression).toFixed(args.precision || 2)}`
},
})
```
---
## Context
Tools receive context about the current session:
```ts title=".opencode/tool/project.ts"
import { tool } from "@opencode-ai/plugin"
export default tool({
description: "Get project information",
args: {},
async execute(args, context) {
// Access context information
const { project, directory, worktree } = context
return `Project: ${project.name}, Directory: ${directory}`
},
})
```
|
