Creating Custom Tools
Learn how to build, define, and integrate custom tools to extend OpenCode with project-specific capabilities.
We'll cover the following...
- What are custom tools?
- Where do custom tools live?
- How do we create a tool?
- How does OpenCode know when to use our tool?
- Can we define multiple tools in one file?
- How do we define arguments?
- What context does a tool receive?
- Can we write tools in other languages?
- What are some practical custom tool examples?
- How do custom tools interact with permissions?
- When should we create custom tools?
- What’s the difference between custom commands and custom tools?
- What’s next?
We’ve learned how to use OpenCode’s built-in tools, such as read, write, and bash. We’ve created custom commands that compose these tools into higher-level workflows. But what if you need OpenCode to do something the built-in tools don’t support?
Custom tools let us extend OpenCode with entirely new capabilities. We can integrate with databases, call external APIs, run custom scripts, or interact with any service our project needs.
What are custom tools?
Custom tools are functions we write that OpenCode can call during conversations. They work exactly like built-in tools. OpenCode decides when to use them based on the conversation context.
The key difference is that built-in tools are general-purpose (reading files, running commands), while custom tools are specific to our needs (querying our database, calling our API, processing our data format).
For example, we might create a database tool that lets OpenCode query our project’s database, or a deploy tool that triggers deployment workflows. These tools become part of OpenCode’s toolkit and are available whenever the model needs them.
Where do custom tools live?
Tools are defined as TypeScript or JavaScript files in specific directories:
Project-specific tools:
.opencode/tools/in our project root. These tools are available only in this project and can be committed to version control so the whole team uses them.Global tools:
~/.config/opencode/tools/in our home directory. These tools ...