File Operations Overview

As an agent, you have powerful file system access:

Read - View file contents
Write - Create or replace files
Edit - Make precise changes to existing files
Organize - Move, copy, delete files

With power comes responsibility. File operations can be destructive.

Reading Files

Basic Read

# Read entire file
cat filename.txt

# Or use the read tool
read(path="./filename.txt")

Reading Large Files

For files over 50KB or 2000 lines, use offset and limit:

# Read lines 100-200
read(path="./large-file.txt", offset=100, limit=100)

Reading Different File Types

Text files: Read directly

read(path="./README.md")

Code files: Read directly, syntax highlighting in tools

read(path="./src/index.ts")

JSON/YAML: Read directly, can parse programmatically

read(path="./config.json")

Images: Some tools support image reading

read(path="./screenshot.png")  # Returns as attachment

Checking If a File Exists

# Check existence
test -f filename.txt && echo "exists" || echo "not found"

# Or
ls -la filename.txt 2>/dev/null || echo "not found"

Writing Files

Create New Files

write(
    path="./new-file.txt",
    content="This is the content"
)

Overwrite Existing Files

Same command—write replaces content entirely:

write(
    path="./existing-file.txt", 
    content="This replaces everything"
)

Warning: This is destructive. The old content is gone.

Creating Files with Directory Structure

Write automatically creates parent directories:

write(
    path="./new/nested/directory/file.txt",
    content="Content here"
)

Editing Files

Precise Edits

For surgical changes, use edit with exact text matching:

edit(
    path="./config.yaml",
    oldText="debug: false",
    newText="debug: true"
)

Important Rules

Exact match required - Including whitespace

First match only - If text appears multiple times, only first is replaced

Failure if not found - Won't silently do nothing

Multi-Line Edits

edit(
    path="./README.md",
    oldText="""## Old Section
This is old content
that spans lines""",
    newText="""## New Section
This is updated content
with different text"""
)

When to Edit vs Write

Use Edit when:

Changing small portions of a file

Preserving most of the content

Making targeted fixes

Use Write when:

Creating new files

Replacing entire contents

File is short and you have the whole thing

File Organization

Listing Files

# Current directory
ls -la

# Specific directory
ls -la ./src/

# Recursive
find . -name "*.md" -type f

# Tree view (if available)
tree -L 2

Moving Files

mv old-location.txt new-location.txt
mv ./file.txt ./directory/

Copying Files

cp source.txt destination.txt
cp -r source-dir/ destination-dir/

Deleting Files

Prefer trash over rm:

# Recoverable
trash filename.txt

# If trash not available (DANGEROUS)
rm filename.txt
rm -rf directory/  # Very dangerous

Creating Directories

mkdir new-directory
mkdir -p nested/directory/structure

Safe File Operations

Before Destructive Operations

Verify the target

ls -la target-file.txt

Make a backup

cp important-file.txt important-file.txt.backup

Confirm with human (for important files)

"I'm about to replace config.yaml. Should I back it up first?"

Avoiding Common Mistakes

Wrong file:

# Dangerous - could delete wrong thing
rm *.log

# Safer - list first
ls *.log
# Then delete specific files
rm debug.log error.log

Wrong directory:

# Always verify current directory
pwd

# Be explicit with paths
rm ./project/temp.txt  # Not just temp.txt

Recursive deletion:

# NEVER do this without verification
rm -rf /  # This would destroy everything

# Always use specific paths
rm -rf ./node_modules/  # Specific, recoverable

File Patterns

Configuration Files

Reading:

config = read(path="./config.yaml")
# Parse and use

Updating:

edit(
    path="./config.yaml",
    oldText="setting: old_value",
    newText="setting: new_value"
)

Log Files

Appending (if supported):

echo "New log entry" >> logfile.txt

Reading recent entries:

tail -100 logfile.txt

Memory Files

Daily logs:

# Create/update today's memory
today = "2025-02-01"
write(
    path=f"./memory/{today}.md",
    content=memory_content
)

Reading recent:

# Read last two days
read(path="./memory/2025-02-01.md")
read(path="./memory/2025-01-31.md")

Code Files

Reading for context:

code = read(path="./src/main.py")

Making targeted edits:

edit(
    path="./src/main.py",
    oldText="def old_function():",
    newText="def new_function():"
)

Best Practices

Verify Before Acting

1. List to see what exists
2. Read to confirm content
3. Then modify

Be Explicit

# Good - explicit path
write(path="./project/src/config.json", content=...)

# Risky - relative, could be wrong directory
write(path="config.json", content=...)

Back Up Before Replacing

cp important.txt important.txt.backup
# Then modify important.txt

Use Version Control

# Commit before major changes
git add -A
git commit -m "Checkpoint before refactor"

# Make changes
# If something goes wrong:
git checkout -- .

Document What You Did

## File Operations Log

- Created ./src/new-feature.ts
- Updated ./config.yaml (added new_setting)
- Deleted ./temp/cache.json (was stale)

Conclusion

File operations are powerful and permanent. Always:

Verify before acting
Prefer non-destructive options
Back up important files
Use version control
Document your changes

Master file operations and you can manage complex projects confidently.

Next: Git for Agents - Version control essentials