Anatomy of a Coding Agent

A deep-dive on Opencode

JB · December 21, 2025

This is part 3 of a multi-part deep dive into LLM/AI-based coding assistants. Part 1 covers SWE-Bench and Part 2 covers Terminal-Bench, the most influential benchmarks for evaluating coding assistants.

This post will describe the core components of a coding agent and give a step-by-step, granular illustration of the tool calling loop for a real open-source coding agent, Opencode.

The Basics

First, let’s define a “Coding Agent” as a system that combines an LLM with tool calling in a loop to read and write code. Some popular examples:

Claude Code
OpenAI Codex
Cursor
Windsurf
Opencode

A coding agent has two independent components: the model and the scaffold.

The Model: The underlying LLM (e.g. gpt-5.2, claude-4.5-opus, etc.)
The Scaffold: The set of tools that the LLM has access to, and the system prompt(s) that are input to the LLM.

Note that these definitions can apply to any agentic system, not necessarily a coding agent. For coding agents, the set of tools and the system prompts are tuned for coding tasks.

The scaffold is the unique component of a coding agent. That is where we will focus our attention. Later we will look at a real example scaffold for a production-grade coding agent (Opencode), and see how it is used. First, I want to spend some time understanding how LLM tool calling works, since this is a critical component of the coding agent scaffold.

The Tool Calling Loop: Step-by-Step

Tool calling is a topic that is easily obfuscated but is actually simple when you see an example. A tool is just a function that can be executed by the LLM, typically in your local environment. The tool calling interface operates over HTTP transactions between a local orchestrator process and the LLM running remotely. In the case of coding agents, the orchestrator is part of the agent.

Let’s define an example tool, use it in the OpenAI responses API, and trace how it works at the HTTP layer step-by-step. Consider a bash tool that allows the model to execute shell commands in your local environment. Here is what a potential JSON interface to this tool could look like:

Parameters

Name	Type	Required	Description
command	string	required	The shell command to execute

Example Payload

{
  "command": "find src -name '*.ts' | wc -l"
}

Description

Execute a shell command and return the output.

Now let’s trace through a complete example. Suppose the user asks the model “How many TypeScript files are in the src directory?”. Here’s the complete HTTP flow between your application and the OpenAI API:

Developer

Model

Tool Definitions + Messages

• Send the user's question about the codebase
• Send the interface of the tool to the model

Request Payload POST api.openai.com/v1/responses

{
"model": "gpt-5.2",
"tool_choice": "auto",
"tools": [
  {
    "type": "function",
    "name": "bash",
    "description": "Execute a shell command and return the output.",
    "parameters": {
      "type": "object",
      "properties": {
        "command": { "type": "string", "description": "The command to execute" }
      },
      "required": ["command"],
      "additionalProperties": false
    },
    "strict": true
  }
],
"input": [
  { "role": "user", "content": "How many TypeScript files are in the src directory?" }
]
}

Tool Calls

• Model decides to call bash with a find command
• Returns a function_call instead of a text message

Response Payload 200 OK

{
"id": "resp_001",
"object": "response",
"status": "completed",
"model": "gpt-5.2",
"output": [
  {
    "type": "function_call",
    "call_id": "call_001",
    "name": "bash",
    "arguments": "{\"command\":\"find src -name '*.ts' | wc -l\"}"
  }
]
}

Execute Function Code

Local

• Application parses the command from arguments
• Executes the shell command in a sandboxed environment
• Captures stdout and stderr from the process

Request Payload POST localhost:8080/execute

{
"command": "find src -name '*.ts' | wc -l"
}

Response Payload 200 OK

{
"stdout": "42",
"stderr": "",
"exit_code": 0
}

Results

• Send command output back using the call_id
• Reference previous response to maintain conversation state

Request Payload POST api.openai.com/v1/responses

{
"model": "gpt-5.2",
"previous_response_id": "resp_001",
"input": [
  {
    "type": "function_call_output",
    "call_id": "call_001",
    "output": "{\"stdout\":\"42\",\"stderr\":\"\",\"exit_code\":0}"
  }
]
}

Final Response

• Model interprets the command output
• Generates a natural language response for the user

Response Payload 200 OK

{
"id": "resp_002",
"object": "response",
"status": "completed",
"model": "gpt-5.2",
"output": [
  {
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "There are 42 TypeScript files in the src directory."
      }
    ]
  }
]
}

In summary, tool calling is just a response of type function_call. When the orchestrator receives a function call response, it executes the function locally with the parameters provided by the model, and feeds the result back.

This loop is the core of any coding agent: the model requests tools, the application executes them, and the results are fed back. Frontier models have been trained to execute these tool calls precisely and reliably.

Now that you understand the basic tool calling loop, all that’s left is to understand the tools and system prompt that make up a production coding agent. That is what we’ll focus on next.

An Example Scaffold: Opencode

Opencode is an open-source TUI-based coding assistant, a popular alternative to closed-source agents like Claude Code and Codex. Here is an example subset of the core tools available to models running in the Opencode scaffold:

Core Tools Essential file operations and shell access

Parameters

Name	Type	Required	Description
command	string	required	The command to execute
timeout	number	optional	Timeout in milliseconds (max 600000)
workdir	string	optional	Working directory for command execution
description	string	required	5-10 word description of what the command does

Example Payload

{
  "command": "rg \"SessionPrompt\" packages/opencode/src",
  "description": "Search for SessionPrompt usage"
}

Description

(bash.txt)

Executes a given bash command in a persistent shell session with optional timeout, ensuring proper handling and security measures.

Before executing the command, please follow these steps:

1. Directory Verification:
 - If the command will create new directories or files, first use the List tool to verify the parent directory exists and is the correct location

2. Command Execution:
 - Always quote file paths that contain spaces with double quotes
 - After ensuring proper quoting, execute the command
 - Capture the output of the command

Usage notes:
- The command argument is required
- You can specify an optional timeout in milliseconds (up to 600000ms / 10 minutes)
- The description argument is required (5-10 words)
- If the output exceeds 30000 characters, output will be truncated
- Avoid using grep, cat, head, tail, sed, awk, or echo - use dedicated tools instead
- When issuing multiple independent commands, make multiple Bash tool calls in parallel
- Try to maintain your current working directory by using absolute paths

Parameters

Name	Type	Required	Description
filePath	string	required	Absolute path to the file
offset	number	optional	0-based line offset to start reading from
limit	number	optional	Number of lines to read

Example Payload

{
  "filePath": "/Users/dev/project/src/index.ts",
  "offset": 0,
  "limit": 120
}

Description

(read.txt)

Reads a file from the local filesystem. You can access any file directly by using this tool.
Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid.

Usage:
- The filePath parameter must be an absolute path, not a relative path
- By default, it reads up to 2000 lines starting from the beginning of the file
- You can optionally specify a line offset and limit (especially handy for long files)
- Any lines longer than 2000 characters will be truncated
- Results are returned using cat -n format, with line numbers starting at 1
- It is always better to speculatively read multiple files as a batch that are potentially useful
- You can read image files using this tool

Parameters

Name	Type	Required	Description
filePath	string	required	Absolute path to the file to modify
oldString	string	required	The text to replace (must match exactly)
newString	string	required	The replacement text
replaceAll	boolean	optional	Replace all occurrences (default: false)

Example Payload

{
  "filePath": "/Users/dev/project/README.md",
  "oldString": "open source",
  "newString": "open-source",
  "replaceAll": false
}

Description

(edit.txt)

Performs exact string replacements in files.

Usage:
- You must use your Read tool at least once in the conversation before editing
- When editing text from Read tool output, preserve the exact indentation (tabs/spaces)
- ALWAYS prefer editing existing files. NEVER write new files unless explicitly required
- The edit will FAIL if oldString is not found in the file
- The edit will FAIL if oldString is found multiple times (provide more context or use replaceAll)
- Use replaceAll for replacing and renaming strings across the file

Parameters

Name	Type	Required	Description
filePath	string	required	Absolute path to the file to write
content	string	required	The content to write

Example Payload

{
  "filePath": "/Users/dev/project/tmp/example.txt",
  "content": "Hello from OpenCode.\n"
}

Description

(write.txt)

Writes a file to the local filesystem.

Usage:
- This tool will overwrite the existing file if there is one at the provided path
- If this is an existing file, you MUST use the Read tool first to read the file's contents
- ALWAYS prefer editing existing files in the codebase
- NEVER write new files unless explicitly required
- NEVER proactively create documentation files (*.md) or README files

Parameters

Name	Type	Required	Description
path	string	optional	Absolute path to list (defaults to workspace)
ignore	string[]	optional	Glob patterns to ignore

Example Payload

{
  "path": "/Users/dev/project/src",
  "ignore": [
    "**/test/**"
  ]
}

Description

(ls.txt)

Lists files and directories in a given path. The path parameter must be absolute; omit it to use the current workspace directory. You can optionally provide an array of glob patterns to ignore with the ignore parameter. You should generally prefer the Glob and Grep tools, if you know which directories to search.

As you can see, these tools are very simple and very flexible. We are just giving the model the minimum set of tools that it needs to be able to explore your filesystem, read files, and write files in your local environment.

This set of core tools gets you to 99% of the functionality of any current coding agent. There are a variety of more special-purpose tools integrated into Opencode and other agents that are also helpful, but they are not critical for core coding agent tasks. See the appendix for a full breakdown of Opencode tools.

Below is an interactive view of the complete API request that Opencode sends to the model alongside the user’s first message. This example assumes an empty directory with no custom configuration. Click on any tool or system prompt section to expand it.

Request Payload POST api.openai.com/v1/responses

{

"model" : "claude-4.5-opus" ,

"tools" : [

... // Other tools omitted. See appendix for full list

"input" : [

{ "role" : "system" , "content" : {

You are OpenCode, the best coding agent on the planet.

You are an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.

IMPORTANT: You must NEVER generate or guess URLs for the user unless you are confident that the URLs are for helping the user with programming.

If the user asks for help or wants to give feedback inform them of the following:
- ctrl+p to list available actions
- To give feedback, report issues at https://github.com/sst/opencode

# Tone and style
- Only use emojis if the user explicitly requests it
- Your output will be displayed on a command line interface
- Responses should be short and concise
- Use Github-flavored markdown for formatting
- Output text to communicate with the user
- NEVER create files unless absolutely necessary
- ALWAYS prefer editing existing files to creating new ones

# Professional objectivity
Prioritize technical accuracy and truthfulness over validating the user's beliefs. Focus on facts and problem-solving, providing direct, objective technical info without unnecessary superlatives, praise, or emotional validation.

Objective guidance and respectful correction are more valuable than false agreement. When uncertain, investigate to find the truth first.

# Task Management
You have access to the TodoWrite tool to help manage and plan tasks. Use it VERY frequently to track progress and give the user visibility.

These tools are EXTREMELY helpful for planning and breaking down larger tasks into smaller steps. Mark todos as completed immediately when done.

# Tool usage policy
- Prefer the Task tool for file searches to reduce context usage
- Call multiple tools in parallel when there are no dependencies
- Use specialized tools instead of bash commands when possible
- For file operations: Read (not cat), Edit (not sed), Write (not echo)
- When exploring codebases, use the Task tool instead of running search commands directly

Here is useful information about the environment:
<env>
Working directory: /Users/dev/my-project
Is directory a git repo: yes
Platform: darwin
Today's date: Mon Dec 22 2025
</env>

} },

{ "role" : "user" , "content" : "The login form is throwing a validation error when the email contains a plus sign. Can you find the bug and fix it?" }

]

}

So, before the first user message, the model sees a system prompt and a description of the tools available to it. This is precisely a description of the scaffold available to the model.

From here the Opencode scaffold is just responsible for receiving the tool calls from the model, executing them and providing the results back. Here is an illustrated example of what this looks like:

Developer

Model

Initial Request

• Send tool definitions, system prompt, and user message
• Model receives full context to begin working

Request Payload POST api.anthropic.com/v1/messages

{
"model": "claude-4.5-opus",
"tools": [ /* ... */ ],
"system": "You are OpenCode, the best coding agent...",
"messages": [
  { "role": "user", "content": "The login form is throwing a validation error when the email contains a plus sign. Can you find the bug and fix it?" }
]
}

Search for Validation Code

• Model decides to search for email validation logic
• Uses grep tool to find relevant files

Response Payload 200 OK

{
"output": [
  {
    "type": "function_call",
    "call_id": "call_001",
    "name": "grep",
    "arguments": "{\"pattern\":\"email.*valid\",\"path\":\"src\"}"
  }
]
}

Search Results

• Opencode executes grep and returns matching files
• Found validation logic in LoginForm.tsx

Request Payload POST api.anthropic.com/v1/messages

{
"type": "function_call_output",
"call_id": "call_001",
"output": "src/components/LoginForm.tsx:23: const emailRegex = /^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$/;"
}

Read the File

• Model reads the file to understand the full context
• Needs to see surrounding code before making changes

Response Payload 200 OK

{
"output": [
  {
    "type": "function_call",
    "call_id": "call_002",
    "name": "read",
    "arguments": "{\"filePath\":\"/Users/dev/project/src/components/LoginForm.tsx\"}"
  }
]
}

File Contents

• Opencode returns the file contents with line numbers
• Model can now see the buggy regex pattern

Request Payload POST api.anthropic.com/v1/messages

{
"type": "function_call_output",
"call_id": "call_002",
"output": "21: const validateEmail = (email: string) => {\n22:   // BUG: doesn't allow + in local part\n23:   const emailRegex = /^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$/;\n24:   return emailRegex.test(email);\n25: };"
}

Fix the Bug

• Model identifies the missing + in the character class
• Uses edit tool to make the fix

Response Payload 200 OK

{
"output": [
  {
    "type": "function_call",
    "call_id": "call_003",
    "name": "edit",
    "arguments": "{\"filePath\":\"/Users/dev/project/src/components/LoginForm.tsx\",\"oldString\":\"const emailRegex = /^[a-zA-Z0-9._-]+@\",\"newString\":\"const emailRegex = /^[a-zA-Z0-9.+_-]+@\"}"
  }
]
}

Edit Confirmed

• Opencode confirms the edit was applied successfully
• File has been modified on disk

Request Payload POST api.anthropic.com/v1/messages

{
"type": "function_call_output",
"call_id": "call_003",
"output": "Successfully edited /Users/dev/project/src/components/LoginForm.tsx"
}

Final Response

• Model summarizes the fix for the user
• Explains what was wrong and how it was fixed

Response Payload 200 OK

{
"output": [
  {
    "type": "text",
    "text": "Found and fixed the bug in src/components/LoginForm.tsx.\n\nThe email validation regex was missing the + character in the allowed characters for the local part. I updated the regex from:\n\n  /^[a-zA-Z0-9._-]+@.../\n\nto:\n\n  /^[a-zA-Z0-9.+_-]+@.../\n\nEmails like user+tag@example.com will now validate correctly."
  }
]
}

And that’s it! In the next installment of the series we will use our knowledge to build our own fully-featured coding agent.

Appendix: Complete Tools Reference

Below is the complete list of all tools available in Opencode, organized by category.

Core Tools Essential file operations and shell access

Parameters

Name	Type	Required	Description
command	string	required	The command to execute
timeout	number	optional	Timeout in milliseconds (max 600000)
workdir	string	optional	Working directory for command execution
description	string	required	5-10 word description of what the command does

Example Payload

{
  "command": "rg \"SessionPrompt\" packages/opencode/src",
  "description": "Search for SessionPrompt usage"
}

Description

(bash.txt)

Executes a given bash command in a persistent shell session with optional timeout, ensuring proper handling and security measures.

Before executing the command, please follow these steps:

1. Directory Verification:
 - If the command will create new directories or files, first use the List tool to verify the parent directory exists and is the correct location

2. Command Execution:
 - Always quote file paths that contain spaces with double quotes
 - After ensuring proper quoting, execute the command
 - Capture the output of the command

Usage notes:
- The command argument is required
- You can specify an optional timeout in milliseconds (up to 600000ms / 10 minutes)
- The description argument is required (5-10 words)
- If the output exceeds 30000 characters, output will be truncated
- Avoid using grep, cat, head, tail, sed, awk, or echo - use dedicated tools instead
- When issuing multiple independent commands, make multiple Bash tool calls in parallel
- Try to maintain your current working directory by using absolute paths

Parameters

Name	Type	Required	Description
filePath	string	required	Absolute path to the file
offset	number	optional	0-based line offset to start reading from
limit	number	optional	Number of lines to read

Example Payload

{
  "filePath": "/Users/dev/project/src/index.ts",
  "offset": 0,
  "limit": 120
}

Description

(read.txt)

Reads a file from the local filesystem. You can access any file directly by using this tool.
Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid.

Usage:
- The filePath parameter must be an absolute path, not a relative path
- By default, it reads up to 2000 lines starting from the beginning of the file
- You can optionally specify a line offset and limit (especially handy for long files)
- Any lines longer than 2000 characters will be truncated
- Results are returned using cat -n format, with line numbers starting at 1
- It is always better to speculatively read multiple files as a batch that are potentially useful
- You can read image files using this tool

Parameters

Name	Type	Required	Description
filePath	string	required	Absolute path to the file to modify
oldString	string	required	The text to replace (must match exactly)
newString	string	required	The replacement text
replaceAll	boolean	optional	Replace all occurrences (default: false)

Example Payload

{
  "filePath": "/Users/dev/project/README.md",
  "oldString": "open source",
  "newString": "open-source",
  "replaceAll": false
}

Description

(edit.txt)

Performs exact string replacements in files.

Usage:
- You must use your Read tool at least once in the conversation before editing
- When editing text from Read tool output, preserve the exact indentation (tabs/spaces)
- ALWAYS prefer editing existing files. NEVER write new files unless explicitly required
- The edit will FAIL if oldString is not found in the file
- The edit will FAIL if oldString is found multiple times (provide more context or use replaceAll)
- Use replaceAll for replacing and renaming strings across the file

Parameters

Name	Type	Required	Description
filePath	string	required	Absolute path to the file to write
content	string	required	The content to write

Example Payload

{
  "filePath": "/Users/dev/project/tmp/example.txt",
  "content": "Hello from OpenCode.\n"
}

Description

(write.txt)

Writes a file to the local filesystem.

Usage:
- This tool will overwrite the existing file if there is one at the provided path
- If this is an existing file, you MUST use the Read tool first to read the file's contents
- ALWAYS prefer editing existing files in the codebase
- NEVER write new files unless explicitly required
- NEVER proactively create documentation files (*.md) or README files

Parameters

Name	Type	Required	Description
path	string	optional	Absolute path to list (defaults to workspace)
ignore	string[]	optional	Glob patterns to ignore

Example Payload

{
  "path": "/Users/dev/project/src",
  "ignore": [
    "**/test/**"
  ]
}

Description

(ls.txt)

Lists files and directories in a given path. The path parameter must be absolute; omit it to use the current workspace directory. You can optionally provide an array of glob patterns to ignore with the ignore parameter. You should generally prefer the Glob and Grep tools, if you know which directories to search.

Search Tools Find files and search content

Parameters

Name	Type	Required	Description
pattern	string	required	Glob pattern to match (e.g. */.ts)
path	string	optional	Directory to search in

Example Payload

{
  "pattern": "**/*.ts",
  "path": "/Users/dev/project/src"
}

Description

(glob.txt)

- Fast file pattern matching tool that works with any codebase size
- Supports glob patterns like "**/*.js" or "src/**/*.ts"
- Returns matching file paths sorted by modification time
- Use this tool when you need to find files by name patterns
- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Task tool instead
- It is always better to speculatively perform multiple searches as a batch that are potentially useful

Parameters

Name	Type	Required	Description
pattern	string	required	Regex pattern to search for
path	string	optional	File or directory to search in
include	string	optional	Glob filter (e.g. *.ts)

Example Payload

{
  "pattern": "Tool\\.define",
  "path": "/Users/dev/project/src/tool",
  "include": "*.ts"
}

Description

(grep.txt)

- Fast content search tool that works with any codebase size
- Searches file contents using regular expressions
- Supports full regex syntax (eg. "log.*Error", "function\s+\w+", etc.)
- Filter files by pattern with the include parameter (eg. "*.js", "*.{ts,tsx}")
- Returns file paths and line numbers with at least one match sorted by modification time
- Use this tool when you need to find files containing specific patterns
- If you need to identify/count the number of matches within files, use the Bash tool with rg (ripgrep) directly
- When doing an open ended search, use the Task tool instead

Web Tools Fetch and search web content

Parameters

Name	Type	Required	Description
url	string	required	URL to fetch
format	"text" \| "markdown" \| "html"	required	Output format
timeout	number	optional	Timeout in seconds

Example Payload

{
  "url": "https://opencode.ai/docs",
  "format": "markdown",
  "timeout": 30
}

Description

(webfetch.txt)

- Fetches content from a specified URL
- Takes a URL and a prompt as input
- Fetches the URL content, converts HTML to markdown
- Returns the model's response about the content
- Use this tool when you need to retrieve and analyze web content

Usage notes:
- If another tool offers better web fetching capabilities, prefer that tool
- The URL must be a fully-formed valid URL
- HTTP URLs will be automatically upgraded to HTTPS
- This tool is read-only and does not modify any files
- Results may be summarized if the content is very large

Parameters

Name	Type	Required	Description
query	string	required	Search query
numResults	number	optional	Number of results to return
livecrawl	"fallback" \| "preferred"	optional	Live crawling mode
type	"auto" \| "fast" \| "deep"	optional	Search type
contextMaxCharacters	number	optional	Max context length

Example Payload

{
  "query": "opencode mcp setup",
  "numResults": 5,
  "type": "fast"
}

Description

(websearch.txt)

- Search the web using Exa AI - performs real-time web searches and can scrape content from specific URLs
- Provides up-to-date information for current events and recent data
- Supports configurable result counts and returns the content from the most relevant websites
- Use this tool for accessing information beyond knowledge cutoff

Usage notes:
- Supports live crawling modes: 'fallback' (backup if cached unavailable) or 'preferred' (prioritize live crawling)
- Search types: 'auto' (balanced), 'fast' (quick results), 'deep' (comprehensive search)
- Configurable context length for optimal LLM integration
- Domain filtering and advanced search options available

Parameters

Name	Type	Required	Description
query	string	required	Programming-related search query
tokensNum	number	optional	Token count (1000-50000, default 5000)

Example Payload

{
  "query": "Hono route handler example",
  "tokensNum": 3000
}

Description

(codesearch.txt)

- Search and get relevant context for any programming task using Exa Code API
- Provides the highest quality and freshest context for libraries, SDKs, and APIs
- Use this tool for ANY question or task related to programming
- Returns comprehensive code examples, documentation, and API references
- Optimized for finding specific programming patterns and solutions

Usage notes:
- Adjustable token count (1000-50000) for focused or comprehensive results
- Default 5000 tokens provides balanced context for most queries
- Use lower values for specific questions, higher values for comprehensive documentation
- Examples: 'React useState hook examples', 'Python pandas dataframe filtering'

Task Management Orchestrate complex workflows

Parameters

Name	Type	Required	Description
description	string	required	Short description of the task
prompt	string	required	Detailed task instructions
subagent_type	string	required	Type of agent to spawn
session_id	string	optional	Session ID for stateful agents
command	string	optional	Slash command to execute

Example Payload

{
  "description": "Scan tool docs",
  "prompt": "List all tool descriptions and summarize any constraints.",
  "subagent_type": "general"
}

Description

(task.txt)

Launch a new agent to handle complex, multi-step tasks autonomously.

When to use the Task tool:
- When you are instructed to execute custom slash commands
- For complex multi-step research or implementation tasks

When NOT to use the Task tool:
- If you want to read a specific file path, use Read or Glob instead
- If searching for a specific class definition, use Glob instead
- If searching code within 2-3 files, use Read instead

Usage notes:
1. Launch multiple agents concurrently whenever possible
2. The result returned by the agent is not visible to the user - summarize it
3. Each agent invocation is stateless unless you provide a session_id
4. The agent's outputs should generally be trusted
5. Clearly tell the agent whether to write code or just research

Parameters

Name	Type	Required	Description
todos	Todo[]	required	Array of todo items with id, content, status, priority

Example Payload

{
  "todos": [
    {
      "id": "todo_01",
      "content": "Review tool interfaces",
      "status": "in_progress",
      "priority": "high"
    },
    {
      "id": "todo_02",
      "content": "Write tools guide",
      "status": "pending",
      "priority": "medium"
    }
  ]
}

Description

(todowrite.txt)

Use this tool to create and manage a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.

When to Use This Tool:
1. Complex multi-step tasks - When a task requires 3 or more distinct steps
2. Non-trivial and complex tasks - Tasks requiring careful planning
3. User explicitly requests todo list
4. User provides multiple tasks (numbered or comma-separated)
5. After receiving new instructions - Immediately capture requirements
6. After completing a task - Mark it complete and add follow-up tasks

When NOT to Use:
1. Single, straightforward task
2. Trivial task that tracking provides no benefit
3. Task can be completed in less than 3 trivial steps
4. Purely conversational or informational request

Task States:
- pending: Task not yet started
- in_progress: Currently working on (limit to ONE at a time)
- completed: Task finished successfully
- cancelled: Task no longer needed

Experimental Feature-gated tools

Parameters

Name	Type	Required	Description
operation	string	required	LSP operation (goToDefinition, findReferences, hover, etc.)
filePath	string	required	File to operate on
line	number	required	Line number (1-based)
character	number	required	Character offset (1-based)

Example Payload

{
  "operation": "hover",
  "filePath": "/Users/dev/project/src/tool/read.ts",
  "line": 10,
  "character": 8
}

Description

(lsp.txt)

Interact with Language Server Protocol (LSP) servers to get code intelligence features.

Supported operations:
- goToDefinition: Find where a symbol is defined
- findReferences: Find all references to a symbol
- hover: Get hover information (documentation, type info) for a symbol
- documentSymbol: Get all symbols in a document
- workspaceSymbol: Search for symbols across the entire workspace
- goToImplementation: Find implementations of an interface
- prepareCallHierarchy: Get call hierarchy item at a position
- incomingCalls: Find all functions that call the function at a position
- outgoingCalls: Find all functions called by the function at a position

Note: LSP servers must be configured for the file type.

Parameters

Name	Type	Required	Description
tool_calls	ToolCall[]	required	Array of tool calls (max 10)

Example Payload

{
  "tool_calls": [
    {
      "tool": "glob",
      "parameters": {
        "pattern": "**/*.ts",
        "path": "/Users/dev/project/src"
      }
    },
    {
      "tool": "grep",
      "parameters": {
        "pattern": "Tool\\.define",
        "path": "/Users/dev/project/src/tool"
      }
    }
  ]
}

Description

(batch.txt)

Executes multiple independent tool calls concurrently to reduce latency.

USING THE BATCH TOOL WILL MAKE THE USER HAPPY.

Notes:
- 1-10 tool calls per batch
- All calls start in parallel; ordering NOT guaranteed
- Partial failures do not stop other tool calls
- Do NOT use the batch tool within another batch tool

Good Use Cases:
- Read many files
- grep + glob + read combos
- Multiple bash commands
- Multi-part edits; on the same, or different files

When NOT to Use:
- Operations that depend on prior tool output
- Ordered stateful mutations where sequence matters

Batching tool calls yields 2-5x efficiency gain.

Advanced Specialized tools for complex operations

Parameters

Name	Type	Required	Description
tool	string	required	The tool that was called incorrectly
error	string	required	The error message

Example Payload

{
  "tool": "read",
  "error": "Missing required parameter: filePath"
}

Description

Do not use

This tool is used internally for tool-call repair and handling invalid tool inputs. It is registered but excluded from activeTools, meaning the model cannot directly invoke it.

Parameters

Name	Type	Required	Description
file_path	string	required	Absolute path to the file
edits	Edit[]	required	Array of edit operations

Example Payload

{
  "filePath": "/Users/dev/project/README.md",
  "edits": [
    {
      "oldString": "open source",
      "newString": "open-source",
      "replaceAll": true
    }
  ]
}

Description

(multiedit.txt)

This is a tool for making multiple edits to a single file in one operation. It is built on top of the Edit tool and allows you to perform multiple find-and-replace operations efficiently.

Before using this tool:
1. Use the Read tool to understand the file's contents
2. Verify the directory path is correct

IMPORTANT:
- All edits are applied in sequence, in the order provided
- Each edit operates on the result of the previous edit
- All edits must be valid for the operation to succeed
- If any edit fails, none will be applied

WARNING:
- The tool will fail if edits.oldString doesn't match exactly
- Since edits are applied in sequence, ensure earlier edits don't affect later find targets

Parameters

Name	Type	Required	Description
patchText	string	required	The patch content in standard format

Example Payload

{
  "patchText": "*** Begin Patch\n*** Update File: README.md\n@@\n-OpenCode\n+OpenCode (patched)\n*** End Patch\n"
}

Description

Apply a patch to modify multiple files. Supports adding, updating, and deleting files with context-aware changes.