File Operations
Read, Write, Edit
Read
Reads files, images, PDFs and notebooks
Write
Creates new files or completely replaces
Edit
Precise string replacements in existing files
Claude Code does not touch your project directly — it works through a set of file tools: Read, Write, and Edit. These are specialized functions the model calls when needed; the harness executes them and feeds the result back into context. This matters for two reasons. First, the model does not guess file contents from memory — it reads the real code right before changing it, so edits reflect the actual state of the repository. Second, every action becomes explicit and reviewable: you see which file was read, what is being created, and exactly which line is replaced.
Read is the entry point. It loads a file's contents into the model's context and understands multiple formats: source code (.ts, .py, .md), images (.png, .jpg), PDFs, and Jupyter notebooks (.ipynb). By default Read returns up to 2000 lines; for large files you use offset and limit to load just the slice you need without overflowing the context window. That is why a request like "Read the file src/auth.ts" first triggers a Read call and only then leads to analysis or editing.
Edit performs a targeted replacement: you provide old_string (the snippet to replace) and new_string (its replacement). The code block above — old_string: "return null;" → new_string: "return data ?? null;" — shows exactly this: one line changes without rewriting the whole file. The key constraint is that old_string must be unique within the file; otherwise the tool cannot tell which occurrence to change and returns an error. When there is ambiguity, include more surrounding context in old_string.
Write creates a new file or completely overwrites an existing one — like the src/components/Button.tsx example on this page. The classic beginner mistake is using Write to tweak an existing file: it wipes all prior content. The rule is simple: use Edit for changes to existing files (it shows a diff, is safer, and preserves formatting), and Write only for creating from scratch. And remember: both Edit and Write require the file to have been read with Read first — a safeguard against blind edits.
The Read tool reads file contents and can handle various formats:
📖 Read can read up to 2000 lines by default. For larger files, use offset and limit.
Edit replaces specific strings in a file. Requires exact text match:
When to use
- • Fixing bugs
- • Adding imports
- • Refactoring functions
- • Updating constants
Limitations
- • old_string must be unique
- • File must exist
- • Requires prior Read
Write creates a new file or completely overwrites an existing one:
⚠️ Write completely replaces file contents. Use Edit for modifying existing files.
Edit
Precise changes in existing file
Examples:
- • Fix bug in function
- • Add import
- • Rename variable
Write
Creating new file or complete replacement
Examples:
- • Create new component
- • Generate config
- • Write test from scratch
Best Practices
- 1.Claude always reads file before editing — this ensures accuracy
- 2.Prefer Edit for existing files — it's safer and shows diff
- 3.Use Write only for new files or complete regeneration
- 4.For large files, specify particular lines or functions
Frequently asked questions
What is the difference between Edit and Write in Claude Code?
Edit performs a targeted string replacement (old_string → new_string) in an existing file, shows a diff, and preserves the rest of the content. Write creates a new file or completely overwrites an existing one, erasing prior content. Use Edit for changes to existing files and Write only for creating from scratch.
Why does Claude Code require reading a file before editing it?
Edit and Write require a prior Read call so the model relies on the file's real, current contents instead of guessing from memory. This safeguards against blind edits and ensures old_string matches exactly what is in the file.
What does the old_string must be unique error mean in Claude Code?
Edit only replaces a snippet if old_string appears exactly once in the file. If that text occurs in multiple places, the tool cannot tell which occurrence to change and returns an error. The fix is to add more context to old_string — surrounding lines and indentation — to make it unique.
Which file formats can the Read tool handle in Claude Code?
Read handles source code (.ts, .js, .py, .md), images (.png, .jpg, .gif, .webp), PDFs, and Jupyter notebooks (.ipynb), plus JSON and YAML. It returns up to 2000 lines by default; for large files you use offset and limit to load the specific slice you need.
This lesson is part of a structured LLM course.
My Learning Path