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
126
127
|
---
title: Custom Tools
description: Create tools the LLM can call in opencode.
---
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`.
---
## Creating a tool
Tools are defined as **TypeScript** or **JavaScript** files.
---
### Location
They can defined:
- Locally by placing them in the `.opencode/tool/` directory of your project.
- Or globally, by placing them in `~/.config/opencode/tool/`.
---
### Structure
The easiest way to create tools is using the `tool()` helper which provides type-safety and validation.
```ts title=".opencode/tool/database.ts" {1}
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}`
},
})
```
The **filename** becomes the **tool name**. The above creates a `database` tool.
---
### Arguments
You can use `tool.schema`, which is just [Zod](https://zod.dev), to define argument types.
```ts "tool.schema"
args: {
query: tool.schema.string().describe("SQL query to execute")
}
```
You can also import [Zod](https://zod.dev) directly and return a plain object:
```ts {6}
import { z } from "zod"
export default {
description: "Tool description",
args: {
param: z.string().describe("Parameter description"),
},
async execute(args, context) {
// Tool implementation
return "result"
},
}
```
---
## Context
Tools receive context about the current session:
```ts title=".opencode/tool/project.ts" {8}
import { tool } from "@opencode-ai/plugin"
export default tool({
description: "Get project information",
args: {},
async execute(args, context) {
// Access context information
const { agent, sessionID, messageID } = context
return `Agent: ${agent}, Session: ${sessionID}, Message: ${messageID}`
},
})
```
---
## Multiple tools per file
You can also 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`.
|
