The text editor tool is an Anthropic-defined client tool: Claude decides what edit to make, but your application executes it. When Claude wants to change a file, the API returns a response with stop_reason: "tool_use" and a structured command — "view this file," "replace this exact string with that one" — and your code performs the operation and sends the result back. Claude never has direct access to your filesystem. That division of labor is what makes the tool safe enough for enterprise codebases: every edit passes through code you wrote and can log, restrict, or reject.
The commands Claude can issue
The current version is text_editor_20250728, declared in your request as {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}. It supports four commands your handler must implement:
| Command | What your handler does |
|---|---|
view | Return file contents (optionally a line range) or a directory listing |
str_replace | Replace one specific string in a file with another |
create | Create a new file with given content |
insert | Insert text after a given line number (0 = beginning of file) |
The str_replace design is deliberate: rather than emitting an entire rewritten file (slow, expensive, and easy to get subtly wrong), Claude quotes the exact text to find and the exact text to put in its place. Your handler can verify the old string appears exactly once before applying the change. The optional max_characters parameter, supported from text_editor_20250728 onward, caps how much text a view returns — useful when Claude opens very large files.
What happened to undo_edit
Older versions of this tool tell a short but instructive story. The original text_editor_20241022 included an undo_edit command. The Claude 4-era text_editor_20250429 removed undo_edit and renamed the tool to the str_replace-based editor; text_editor_20250728 is the same design plus fixes and max_characters. So on all current models there is no built-in undo — undo semantics are now your application's responsibility, and that is genuinely better for enterprises. The standard pattern is to run Claude's edits inside a version-controlled working copy (a git branch or a scratch checkout) so that "undo" becomes an ordinary revert you can audit, rather than tool state you can't inspect. If you are migrating code written for the 2024-era tool, remove any undo_edit handling and note that the tool name must change along with the type — keeping the old name with a new type returns a 400 error.
A minimal handler loop
from anthropic import AnthropicVertex
client = AnthropicVertex(project_id="my-project", region="global")
resp = client.messages.create(
model="claude-opus-4-8",
max_tokens=2048,
tools=[{"type": "text_editor_20250728",
"name": "str_replace_based_edit_tool"}],
messages=[{"role": "user",
"content": "Fix the typo in config/app.yaml"}],
)
for block in resp.content:
if block.type == "tool_use":
print(block.input) # e.g. {"command": "view", "path": "config/app.yaml"}Your code then executes the command and returns a tool_result block referencing the request's ID — the same loop described in our article on processing tool_use blocks.
Security and cost notes
The path Claude supplies is untrusted model output. Canonicalize every path and confine operations to a fixed project root: reject .. traversal, symlink escapes, absolute paths outside the root, and URL-encoded tricks. Budget-wise, the Claude 4.x tool definition adds about 700 input tokens per request on top of standard token pricing — small, but visible at scale.
Availability across platforms
Because the text editor tool runs in your code, it travels well: it is generally available on the first-party Claude API, Claude Platform on AWS, Amazon Bedrock, and Google Vertex AI, and in beta on Microsoft Foundry. It is also eligible for Zero Data Retention, unlike server-executed tools such as code execution. That makes it one of the most portable agentic building blocks across 3P platforms — see the feature matrix for the full picture.
Where to go next
Pair the text editor with the bash tool for full coding-agent workflows, or read the code execution article for the server-side alternative where Anthropic hosts the sandbox.