Page history
text-editor-tool
agents-and-tools/tool-use/text-editor-tool
History
agents-and-tools/tool-use/text-editor-tool First recorded · 2277 lines, first recorded
## When to use the text editor tool ## Use the text editor tool ### Text editor tool commands #### view #### str\_replace #### create #### insert ### Example: Fixing a syntax error with the text editor tool ## Implement the text editor tool ### Handle errors ### Follow implementation best practices ## Pricing and token usage ## Integrate the text editor tool with other tools ## Change log ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: Text editor tool
url: https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool
description: Give Claude the Anthropic-defined text editor tool to view, create, and edit files, and handle its view, str_replace, create, and insert commands.
---
<Note>
For how zero data retention (ZDR) applies to this feature, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).
</Note>
Claude can use an Anthropic-schema text editor tool to view and modify text files, helping you debug, fix, and improve your code or other text documents. This allows Claude to directly interact with your files, providing hands-on assistance rather than just suggesting changes.
For model support, see the [Tool reference](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference).
## When to use the text editor tool
Some examples of when to use the text editor tool are:
* **Code debugging:** Have Claude identify and fix bugs in your code, from syntax errors to logic issues.
* **Code refactoring:** Let Claude improve your code structure, readability, and performance through targeted edits.
* **Documentation generation:** Ask Claude to add docstrings, comments, or README files to your code base.
* **Test creation:** Have Claude create unit tests for your code based on its analysis of the implementation.
## Use the text editor tool
Provide the text editor tool (named `str_replace_based_edit_tool`) to Claude using the Messages API.
You can optionally specify a `max_characters` parameter to control truncation when viewing large files.
<Note>
`max_characters` is only compatible with `text_editor_20250728` and later versions of the text editor tool.
</Note>
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5",
"max_tokens": 1024,
"tools": [
{
"type": "text_editor_20250728",
"name": "str_replace_based_edit_tool",
"max_characters": 10000
}
],
"messages": [
{
"role": "user",
"content": "There'\''s a syntax error in my primes.py file. Can you help me fix it?"
}
]
}'
```
```bash CLI
ant messages create \
--model claude-opus-5 \
--max-tokens 1024 \
--tool '{type: text_editor_20250728, name: str_replace_based_edit_tool, max_characters: 10000}' \
--message '{role: user, content: There is a syntax error in my primes.py file. Can you help me fix it?}'
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
tools=[
{
"type": "text_editor_20250728",
"name": "str_replace_based_edit_tool",
"max_characters": 10000,
}
],
messages=[
{
"role": "user",
"content": "There's a syntax error in my primes.py file. Can you help me fix it?",
}
],
)
print(response)
```
```typescript TypeScript
const anthropic = new Anthropic();
const response = await anthropic.messages.create({
model: "claude-opus-5",
max_tokens: 1024,
tools: [
{
type: "text_editor_20250728",
name: "str_replace_based_edit_tool",
max_characters: 10000
}
],
messages: [
{
role: "user",
content: "There's a syntax error in my primes.py file. Can you help me fix it?"
}
]
});
console.log(response);
```
```csharp C#
var client = new AnthropicClient();
var response = await client.Messages.Create(
new()
{
Model = Model.ClaudeOpus5,
MaxTokens = 1024,
Tools = [new ToolTextEditor20250728 { MaxCharacters = 10000 }],
Messages =
[
new()
{
Role = Role.User,
Content = "There's a syntax error in my primes.py file. Can you help me fix it?",
},
],
}
);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 1024,
Tools: []anthropic.ToolUnionParam{
{OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{
MaxCharacters: anthropic.Int(10000),
}},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("There's a syntax error in my primes.py file. Can you help me fix it?")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.messages.ToolTextEditor20250728;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
ToolTextEditor20250728 editorTool =
ToolTextEditor20250728.builder()
.maxCharacters(10000L)
.build();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(1024)
.addTool(editorTool)
.addUserMessage("There's a syntax error in my primes.py file. Can you help me fix it?")
.build();
Message message = client.messages().create(params);
IO.println(message);
}
```
```php PHP
$client = new Client();
$response = $client->messages->create(
model: 'claude-opus-5',
maxTokens: 1024,
tools: [ToolTextEditor20250728::with(maxCharacters: 10000)],
messages: [
[
'role' => 'user',
'content' => "There's a syntax error in my primes.py file. Can you help me fix it?",
],
],
);
echo $response;
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: "claude-opus-5",
max_tokens: 1024,
tools: [
{
type: "text_editor_20250728",
name: "str_replace_based_edit_tool",
max_characters: 10000
}
],
messages: [
{
role: "user",
content: "There's a syntax error in my primes.py file. Can you help me fix it?"
}
]
)
puts response
```
</CodeGroup>
Use the text editor tool in the following way:
<Steps>
<Step title="Provide Claude with the text editor tool and a user prompt">
* Include the text editor tool in your API request
* Provide a user prompt that may require examining or modifying files, such as "Can you fix the syntax error in my code?"
</Step>
<Step title="Claude uses the tool to examine files or directories">
* Claude assesses what it needs to look at and uses the `view` command to examine file contents or list directory contents
* The API response will contain a `tool_use` content block with the `view` command
</Step>
<Step title="Execute the view command and return results">
* Extract the file or directory path from Claude's tool use request
* Read the file's contents or list the directory contents
* If a `max_characters` parameter was specified in the tool configuration, truncate the file contents to that length
* Return the results to Claude by continuing the conversation with a new `user` message containing a `tool_result` content block
</Step>
<Step title="Claude uses the tool to modify files">
* After examining the file or directory, Claude may use a command such as `str_replace` to make changes or `insert` to add text at a specific line number.
* If Claude uses the `str_replace` command, Claude constructs a properly formatted tool use request with the old text and new text to replace it with
</Step>
<Step title="Execute the edit and return results">
* Extract the file path, old text, and new text from Claude's tool use request
* Perform the text replacement in the file
* Return the results to Claude
</Step>
<Step title="Claude provides its analysis and explanation">
* After examining and possibly editing the files, Claude provides a complete explanation of what it found and what changes it made
</Step>
</Steps>
### Text editor tool commands
The text editor tool supports several commands for viewing and modifying files:
#### view
The `view` command allows Claude to examine the contents of a file or list the contents of a directory. It can read the entire file or a specific range of lines.
Parameters:
* `command`: Must be "view"
* `path`: The path to the file or directory to view
* `view_range` (optional): An array of two integers specifying the start and end line numbers to view. Line numbers are 1-indexed, and -1 for the end line means read to the end of the file. This parameter only applies when viewing files, not directories.
<Accordion title="Example view commands">
Example for viewing a file:
```json
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "str_replace_based_edit_tool",
"input": {
"command": "view",
"path": "primes.py"
}
}
```
Example for viewing a directory:
```json
{
"type": "tool_use",
"id": "toolu_02B19r91rw91mr917835mr9",
"name": "str_replace_based_edit_tool",
"input": {
"command": "view",
"path": "src/"
}
Cut at 300 lines.