Tools

Manage the tools an LLM can use.

Tools allow the LLM to perform actions in your codebase. OpenCode comes with a set of built-in tools, but you can extend it with custom tools or MCP servers.

By default, all tools are enabled and don’t need permission to run. But you can configure this and control the permissions through your config.

Configure

You can configure tools globally or per agent. Agent-specific configs override global settings.

By default, all tools are set to true. To disable a tool, set it to false.

Global

Disable or enable tools globally using the tools option.

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": false,
    "bash": false,
    "webfetch": true
  }
}

You can also use wildcards to control multiple tools at once. For example, to disable all tools from an MCP server:

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "mymcp_*": false
  }
}

Per agent

Override global tool settings for specific agents using the tools config in the agent definition.

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

For example, here the plan agent overrides the global config to disable write and bash tools.

You can also configure tools for agents in Markdown.

---
description: Read-only analysis agent
mode: subagent
tools:
  write: false
  edit: false
  bash: false
---

Analyze code without making any modifications.

Learn more about configuring tools per agent.

Built-in

Here are all the built-in tools available in OpenCode.

bash

Execute shell commands in your project environment.

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "bash": true
  }
}

This tool allows the LLM to run terminal commands like npm install, git status, or any other shell command.

edit

Modify existing files using exact string replacements.

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "edit": true
  }
}

This tool performs precise edits to files by replacing exact text matches. It’s the primary way the LLM modifies code.

write

Create new files or overwrite existing ones.

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true
  }
}

Use this to allow the LLM to create new files. It will overwrite existing files if they already exist.

read

Read file contents from your codebase.

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "read": true
  }
}

This tool reads files and returns their contents. It supports reading specific line ranges for large files.

grep

Search file contents using regular expressions.

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "grep": true
  }
}

Fast content search across your codebase. Supports full regex syntax and file pattern filtering.

glob

Find files by pattern matching.

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "glob": true
  }
}

Search for files using glob patterns like **/*.js or src/**/*.ts. Returns matching file paths sorted by modification time.

list

List files and directories in a given path.

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "list": true
  }
}

This tool lists directory contents. It accepts glob patterns to filter results.

patch

Apply patches to files.

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "patch": true
  }
}

This tool applies patch files to your codebase. Useful for applying diffs and patches from various sources.

todowrite

Manage todo lists during coding sessions.

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "todowrite": true
  }
}

Creates and updates task lists to track progress during complex operations. The LLM uses this to organize multi-step tasks.

todoread

Read existing todo lists.

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "todoread": true
  }
}

Reads the current todo list state. Used by the LLM to track what tasks are pending or completed.

webfetch

Fetch web content.

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "webfetch": true
  }
}

Allows the LLM to fetch and read web pages. Useful for looking up documentation or researching online resources.

!node_modules/
!dist/
!build/

For example, this .ignore file allows ripgrep to search within node_modules/, dist/, and build/ directories even if they’re listed in .gitignore.