Text editor tool
Claude can use an Anthropic-defined 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.
Before using the text editor tool
Use a compatible model
Anthropic’s text editor tool is only available for Claude 3.5 Sonnet and Claude 3.7 Sonnet:
- Claude 3.7 Sonnet:
text_editor_20250124
- Claude 3.5 Sonnet:
text_editor_20241022
Both versions provide identical capabilities - the version you use should match the model you’re working with.
Assess your use case fit
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 codebase.
- Test creation: Have Claude create unit tests for your code based on its understanding of the implementation.
Use the text editor tool
Provide the text editor tool (named str_replace_editor
) to Claude using the Messages API:
The text editor tool can be used in the following way:
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?”
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 theview
command
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 and return them to Claude
- Return the results to Claude by continuing the conversation with a new
user
message containing atool_result
content block
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 orinsert
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
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
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
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 viewview_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.
str_replace
The str_replace
command allows Claude to replace a specific string in a file with a new string. This is used for making precise edits.
Parameters:
command
: Must be “str_replace”path
: The path to the file to modifyold_str
: The text to replace (must match exactly, including whitespace and indentation)new_str
: The new text to insert in place of the old text
create
The create
command allows Claude to create a new file with specified content.
Parameters:
command
: Must be “create”path
: The path where the new file should be createdfile_text
: The content to write to the new file
insert
The insert
command allows Claude to insert text at a specific location in a file.
Parameters:
command
: Must be “insert”path
: The path to the file to modifyinsert_line
: The line number after which to insert the text (0 for beginning of file)new_str
: The text to insert
undo_edit
The undo_edit
command allows Claude to revert the last edit made to a file.
Parameters:
command
: Must be “undo_edit”path
: The path to the file whose last edit should be undone
Example: Fixing a syntax error with the text editor tool
This example demonstrates how Claude uses the text editor tool to fix a syntax error in a Python file.
First, your application provides Claude with the text editor tool and a prompt to fix a syntax error:
Claude will use the text editor tool first to view the file:
Your application should then read the file and return its contents to Claude:
Line numbers
In the example above, the view
tool result includes file contents with line numbers prepended to each line (e.g., “1: def is_prime(n):”). Line numbers are not required, but they are essential for successfully using the view_range
parameter to examine specific sections of files and the insert_line
parameter to add content at precise locations.
Claude will identify the syntax error and use the str_replace
command to fix it:
Your application should then make the edit and return the result:
Finally, Claude will provide a complete explanation of the fix:
Implement the text editor tool
The text editor tool is implemented as a schema-less tool, identified by type: "text_editor_20250124"
. When using this tool, you don’t need to provide an input schema as with other tools; the schema is built into Claude’s model and can’t be modified.
Initialize your editor implementation
Create helper functions to handle file operations like reading, writing, and modifying files. Consider implementing backup functionality to recover from mistakes.
Handle editor tool calls
Create a function that processes tool calls from Claude based on the command type:
Implement security measures
Add validation and security checks:
- Validate file paths to prevent directory traversal
- Create backups before making changes
- Handle errors gracefully
- Implement permissions checks
Process Claude's responses
Extract and handle tool calls from Claude’s responses:
When implementing the text editor tool, keep in mind:
- Security: The tool has access to your local filesystem, so implement proper security measures.
- Backup: Always create backups before allowing edits to important files.
- Validation: Validate all inputs to prevent unintended changes.
- Unique matching: Make sure replacements match exactly one location to avoid unintended edits.
Handle errors
When using the text editor tool, various errors may occur. Here is guidance on how to handle them:
Follow implementation best practices
Pricing and token usage
The text editor tool uses the same pricing structure as other tools used with Claude. It follows the standard input and output token pricing based on the Claude model you’re using.
In addition to the base tokens, the following additional input tokens are needed for the text editor tool:
Tool | Additional input tokens |
---|---|
text_editor_20241022 (Claude 3.5 Sonnet) | 700 tokens |
text_editor_20250124 (Claude 3.7 Sonnet) | 700 tokens |
For more detailed information about tool pricing, see Tool use pricing.
Integrate the text editor tool with computer use
The text editor tool can be used alongside the computer use tool and other Anthropic-defined tools. When combining these tools, you’ll need to:
- Include the appropriate beta header (if using with computer use)
- Match the tool version with the model you’re using
- Account for the additional token usage for all tools included in your request
For more information about using the text editor tool in a computer use context, see the Computer use.
Change log
Date | Version | Changes |
---|---|---|
March 13, 2025 | text_editor_20250124 | Introduction of standalone Text Editor Tool documentation. This version is optimized for Claude 3.7 Sonnet but has identical capabilities to the previous version. |
October 22, 2024 | text_editor_20241022 | Initial release of the Text Editor Tool with Claude 3.5 Sonnet. Provides capabilities for viewing, creating, and editing files through the view , create , str_replace , insert , and undo_edit commands. |
Next steps
Here are some ideas for how to use the text editor tool in more convenient and powerful ways:
- Integrate with your development workflow: Build the text editor tool into your development tools or IDE
- Create a code review system: Have Claude review your code and make improvements
- Build a debugging assistant: Create a system where Claude can help you diagnose and fix issues in your code
- Implement file format conversion: Let Claude help you convert files from one format to another
- Automate documentation: Set up workflows for Claude to automatically document your code
As you build applications with the text editor tool, we’re excited to see how you leverage Claude’s capabilities to enhance your development workflow and productivity.
Was this page helpful?